summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAchilleas Pipinellis <axil@gitlab.com>2018-11-06 19:18:47 +0000
committerAchilleas Pipinellis <axil@gitlab.com>2018-11-06 19:18:47 +0000
commit173c6ca1e8925d69e9aba88c8331096521d3f388 (patch)
tree9ff375d70ee299b93d1f6209310049876004a739
parentaa9a662b666b3ca85f5165cb52c18bbfb6d8d3f0 (diff)
parente148dd3d16223edcd4020455d6789be1445a5a56 (diff)
downloadgitlab-ce-173c6ca1e8925d69e9aba88c8331096521d3f388.tar.gz
Merge branch 'docs/aws-install' into 'master'
Add AWS installation docs Closes #49501 See merge request gitlab-org/gitlab-ce!20778
-rw-r--r--doc/install/README.md6
-rw-r--r--doc/install/aws/img/add_tags.pngbin0 -> 17834 bytes
-rw-r--r--doc/install/aws/img/associate_subnet_gateway.pngbin0 -> 16522 bytes
-rw-r--r--doc/install/aws/img/associate_subnet_gateway_2.pngbin0 -> 10617 bytes
-rw-r--r--doc/install/aws/img/aws_diagram.pngbin0 -> 502497 bytes
-rw-r--r--doc/install/aws/img/choose_ami.pngbin0 -> 4892 bytes
-rw-r--r--doc/install/aws/img/create_gateway.pngbin0 -> 13927 bytes
-rw-r--r--doc/install/aws/img/create_route_table.pngbin0 -> 8293 bytes
-rw-r--r--doc/install/aws/img/create_security_group.pngbin0 -> 12594 bytes
-rw-r--r--doc/install/aws/img/create_subnet.pngbin0 -> 16679 bytes
-rw-r--r--doc/install/aws/img/create_vpc.pngbin0 -> 15613 bytes
-rw-r--r--doc/install/aws/img/ec_az.pngbin0 -> 10476 bytes
-rw-r--r--doc/install/aws/img/ec_subnet.pngbin0 -> 23517 bytes
-rw-r--r--doc/install/aws/img/policies.pngbin0 -> 39723 bytes
-rw-r--r--doc/install/aws/img/rds_subnet_group.pngbin0 -> 30107 bytes
-rw-r--r--doc/install/aws/index.md655
16 files changed, 658 insertions, 3 deletions
diff --git a/doc/install/README.md b/doc/install/README.md
index 27df03c6ac6..92116305775 100644
--- a/doc/install/README.md
+++ b/doc/install/README.md
@@ -34,11 +34,11 @@ the hardware requirements.
- [Install GitLab on Google Cloud Platform](google_cloud_platform/index.md)
- [Install GitLab on Google Kubernetes Engine (GKE)](https://about.gitlab.com/2017/01/23/video-tutorial-idea-to-production-on-google-container-engine-gke/): video tutorial on
the full process of installing GitLab on Google Kubernetes Engine (GKE), pushing an application to GitLab, building the app with GitLab CI/CD, and deploying to production.
-- [Install on AWS](https://about.gitlab.com/aws/)
-- _Testing only!_ [DigitalOcean and Docker Machine](digitaloceandocker.md) -
- Quickly test any version of GitLab on DigitalOcean using Docker Machine.
+- [Install on AWS](aws/index.md): Install GitLab on AWS using the community AMIs that GitLab provides.
- [Getting started with GitLab and DigitalOcean](https://about.gitlab.com/2016/04/27/getting-started-with-gitlab-and-digitalocean/): requirements, installation process, updates.
- [Demo: Cloud Native Development with GitLab](https://about.gitlab.com/2017/04/18/cloud-native-demo/): video demonstration on how to install GitLab on Kubernetes, build a project, create Review Apps, store Docker images in Container Registry, deploy to production on Kubernetes, and monitor with Prometheus.
+- _Testing only!_ [DigitalOcean and Docker Machine](digitaloceandocker.md) -
+ Quickly test any version of GitLab on DigitalOcean using Docker Machine.
## Database
diff --git a/doc/install/aws/img/add_tags.png b/doc/install/aws/img/add_tags.png
new file mode 100644
index 00000000000..3572cd5daa1
--- /dev/null
+++ b/doc/install/aws/img/add_tags.png
Binary files differ
diff --git a/doc/install/aws/img/associate_subnet_gateway.png b/doc/install/aws/img/associate_subnet_gateway.png
new file mode 100644
index 00000000000..1edca974fca
--- /dev/null
+++ b/doc/install/aws/img/associate_subnet_gateway.png
Binary files differ
diff --git a/doc/install/aws/img/associate_subnet_gateway_2.png b/doc/install/aws/img/associate_subnet_gateway_2.png
new file mode 100644
index 00000000000..76e101d32a3
--- /dev/null
+++ b/doc/install/aws/img/associate_subnet_gateway_2.png
Binary files differ
diff --git a/doc/install/aws/img/aws_diagram.png b/doc/install/aws/img/aws_diagram.png
new file mode 100644
index 00000000000..bcd5c69bbeb
--- /dev/null
+++ b/doc/install/aws/img/aws_diagram.png
Binary files differ
diff --git a/doc/install/aws/img/choose_ami.png b/doc/install/aws/img/choose_ami.png
new file mode 100644
index 00000000000..034ac92691d
--- /dev/null
+++ b/doc/install/aws/img/choose_ami.png
Binary files differ
diff --git a/doc/install/aws/img/create_gateway.png b/doc/install/aws/img/create_gateway.png
new file mode 100644
index 00000000000..9408520e050
--- /dev/null
+++ b/doc/install/aws/img/create_gateway.png
Binary files differ
diff --git a/doc/install/aws/img/create_route_table.png b/doc/install/aws/img/create_route_table.png
new file mode 100644
index 00000000000..ea72c57257e
--- /dev/null
+++ b/doc/install/aws/img/create_route_table.png
Binary files differ
diff --git a/doc/install/aws/img/create_security_group.png b/doc/install/aws/img/create_security_group.png
new file mode 100644
index 00000000000..9a0dfccfe37
--- /dev/null
+++ b/doc/install/aws/img/create_security_group.png
Binary files differ
diff --git a/doc/install/aws/img/create_subnet.png b/doc/install/aws/img/create_subnet.png
new file mode 100644
index 00000000000..26f5ab1b625
--- /dev/null
+++ b/doc/install/aws/img/create_subnet.png
Binary files differ
diff --git a/doc/install/aws/img/create_vpc.png b/doc/install/aws/img/create_vpc.png
new file mode 100644
index 00000000000..a678f7013fd
--- /dev/null
+++ b/doc/install/aws/img/create_vpc.png
Binary files differ
diff --git a/doc/install/aws/img/ec_az.png b/doc/install/aws/img/ec_az.png
new file mode 100644
index 00000000000..22a8291c593
--- /dev/null
+++ b/doc/install/aws/img/ec_az.png
Binary files differ
diff --git a/doc/install/aws/img/ec_subnet.png b/doc/install/aws/img/ec_subnet.png
new file mode 100644
index 00000000000..c44fb4485e3
--- /dev/null
+++ b/doc/install/aws/img/ec_subnet.png
Binary files differ
diff --git a/doc/install/aws/img/policies.png b/doc/install/aws/img/policies.png
new file mode 100644
index 00000000000..e99497a52a2
--- /dev/null
+++ b/doc/install/aws/img/policies.png
Binary files differ
diff --git a/doc/install/aws/img/rds_subnet_group.png b/doc/install/aws/img/rds_subnet_group.png
new file mode 100644
index 00000000000..7c6157e38e0
--- /dev/null
+++ b/doc/install/aws/img/rds_subnet_group.png
Binary files differ
diff --git a/doc/install/aws/index.md b/doc/install/aws/index.md
new file mode 100644
index 00000000000..53fe1a6b25b
--- /dev/null
+++ b/doc/install/aws/index.md
@@ -0,0 +1,655 @@
+# Installing GitLab on Amazon Web Services (AWS)
+
+To install GitLab on AWS, you can use the Amazon Machine Images (AMIs) that GitLab
+provides with [each release](https://about.gitlab.com/releases/).
+
+This page offers a walkthrough of a common HA (Highly Available) configuration
+for GitLab on AWS. You should customize it to accommodate your needs.
+
+## Introduction
+
+GitLab on AWS can leverage many of the services that are already
+configurable with GitLab High Availability (HA). These services offer a great deal of
+flexibility and can be adapted to the needs of most companies, while enabling the
+automation of both vertical and horizontal scaling.
+
+In this guide, we'll go through a basic HA setup where we'll start by
+configuring our Virtual Private Cloud and subnets to later integrate
+services such as RDS for our database server and ElastiCache as a Redis
+cluster to finally manage them within an auto scaling group with custom
+scaling policies.
+
+## Requirements
+
+In addition to having a basic familiarity with [AWS](https://docs.aws.amazon.com/) and [Amazon EC2](https://docs.aws.amazon.com/ec2/), you will need:
+
+- [An AWS account](https://console.aws.amazon.com/console/home)
+- [To create or upload an SSH key](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html)
+ to connect to the instance via SSH
+- A domain name for the GitLab instance
+
+## Architecture
+
+Below is a diagram of the recommended architecture.
+
+![AWS architecture diagram](img/aws_diagram.png)
+
+## AWS costs
+
+Here's a list of the AWS services we will use, with links to pricing information:
+
+- **EC2**: GitLab will deployed on shared hardware which means
+ [on-demand pricing](https://aws.amazon.com/ec2/pricing/on-demand)
+ will apply. If you want to run it on a dedicated or reserved instance,
+ consult the [EC2 pricing page](https://aws.amazon.com/ec2/pricing/) for more
+ information on the cost.
+- **EBS**: We will also use an EBS volume to store the Git data. See the
+ [Amazon EBS pricing](https://aws.amazon.com/ebs/pricing/).
+- **S3**: We will use S3 to store backups, artifacts, LFS objects, etc. See the
+ [Amazon S3 pricing](https://aws.amazon.com/s3/pricing/).
+- **ALB**: An Application Load Balancer will be used to route requests to the
+ GitLab instance. See the [Amazon ELB pricing](https://aws.amazon.com/elasticloadbalancing/pricing/).
+- **RDS**: An Amazon Relational Database Service using PostgreSQL will be used
+ to provide a High Availability database configuration. See the
+ [Amazon RDS pricing](https://aws.amazon.com/rds/postgresql/pricing/).
+- **ElastiCache**: An in-memory cache environment will be used to provide a
+ High Availability Redis configuration. See the
+ [Amazon ElastiCache pricing](https://aws.amazon.com/elasticache/pricing/).
+
+## Creating an IAM EC2 instance role and profile
+To minimize the permissions of the user, we'll create a new [IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html)
+role with limited access:
+
+1. Navigate to the IAM dashboard https://console.aws.amazon.com/iam/home and
+ click **Create role**.
+1. Create a new role by selecting **AWS service > EC2**, then click
+ **Next: Permissions**.
+1. Choose **AmazonEC2FullAccess** and **AmazonS3FullAccess**, then click **Next: Review**.
+1. Give the role the name `GitLabAdmin` and click **Create role**.
+
+## Configuring the network
+
+We'll start by creating a VPC for our GitLab cloud infrastructure, then
+we can create subnets to have public and private instances in at least
+two [Availability Zones (AZs)](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html). Public subnets will require a Route Table keep and an associated
+Internet Gateway.
+
+### Creating the Virtual Private Cloud (VPC)
+
+We'll now create a VPC, a virtual networking environment that you'll control:
+
+1. Navigate to https://console.aws.amazon.com/vpc/home.
+1. Select **Your VPCs** from the left menu and then click **Create VPC**.
+ At the "Name tag" enter `gitlab-vpc` and at the "IPv4 CIDR block" enter
+ `10.0.0.0/16`. If you don't require dedicated hardware, you can leave
+ "Tenancy" as default. Click **Yes, Create** when ready.
+
+ ![Create VPC](img/create_vpc.png)
+
+### Subnets
+
+Now, let's create some subnets in different Availability Zones. Make sure
+that each subnet is associated the the VPC we just created and
+that CIDR blocks don't overlap. This will also
+allow us to enable multi AZ for redundancy.
+
+We will create private and public subnets to match load balancers and
+RDS instances as well:
+
+1. Select **Subnets** from the left menu.
+1. Click **Create subnet**. Give it a descriptive name tag based on the IP,
+ for example `gitlab-public-10.0.0.0`, select the VPC we created previously,
+ and at the IPv4 CIDR block let's give it a 24 subnet `10.0.0.0/24`:
+
+ ![Create subnet](img/create_subnet.png)
+
+1. Follow the same steps to create all subnets:
+
+ | Name tag | Type |Availability Zone | CIDR block |
+ | -------- | ---- | ---------------- | ---------- |
+ | gitlab-public-10.0.0.0 | public | us-west-2a | 10.0.0.0 |
+ | gitlab-private-10.0.1.0 | private | us-west-2a | 10.0.1.0 |
+ | gitlab-public-10.0.2.0 | public | us-west-2b | 10.0.2.0 |
+ | gitlab-private-10.0.3.0 | private | us-west-2b | 10.0.3.0 |
+
+### Route Table
+
+Up to now all our subnets are private. We need to create a Route Table
+to associate an Internet Gateway. On the same VPC dashboard:
+
+1. Select **Route Tables** from the left menu.
+1. Click **Create Route Table**.
+1. At the "Name tag" enter `gitlab-public` and choose `gitlab-vpc` under "VPC".
+1. Hit **Yes, Create**.
+
+### Internet Gateway
+
+Now, still on the same dashboard, go to Internet Gateways and
+create a new one:
+
+1. Select **Internet Gateways** from the left menu.
+1. Click **Create internet gateway**, give it the name `gitlab-gateway` and
+ click **Create**.
+1. Select it from the table, and then under the **Actions** dropdown choose
+ "Attach to VPC".
+
+ ![Create gateway](img/create_gateway.png)
+
+1. Choose `gitlab-vpc` from the list and hit **Attach**.
+
+### Configuring subnets
+
+We now need to add a new target which will be our Internet Gateway and have
+it receive traffic from any destination.
+
+1. Select **Route Tables** from the left menu and select the `gitlab-public`
+ route to show the options at the bottom.
+1. Select the **Routes** tab, hit **Edit > Add another route** and set `0.0.0.0/0`
+ as destination. In the target, select the `gitlab-gateway` we created previously.
+ Hit **Save** once done.
+
+ ![Associate subnet with gateway](img/associate_subnet_gateway.png)
+
+Next, we must associate the **public** subnets to the route table:
+
+1. Select the **Subnet Associations** tab and hit **Edit**.
+1. Check only the public subnet and hit **Save**.
+
+ ![Associate subnet with gateway](img/associate_subnet_gateway_2.png)
+
+---
+
+Now that we're done with the network, let's create a security group.
+
+## Creating a security group
+
+The security group is basically the firewall:
+
+1. Select **Security Groups** from the left menu.
+1. Click **Create Security Group** and fill in the details. Give it a name,
+ add a description, and choose the VPC we created previously
+1. Select the security group from the list and at the the bottom select the
+ Inbound Rules tab. You will need to open the SSH, HTTP, and HTTPS ports. Set
+ the source to `0.0.0.0/0`.
+
+ ![Create security group](img/create_security_group.png)
+
+ TIP: **Tip:**
+ Based on best practices, you should allow SSH traffic from only a known
+ host or CIDR block. In that case, change the SSH source to be custom and give
+ it the IP you want to SSH from.
+
+1. When done, click **Save**.
+
+## PostgreSQL with RDS
+
+For our database server we will use Amazon RDS which offers Multi AZ
+for redundancy. Let's start by creating a subnet group and then we'll
+create the actual RDS instance.
+
+### RDS Subnet Group
+
+1. Navigate to the RDS dashboard and select **Subnet Groups** from the left menu.
+1. Give it a name (`gitlab-rds-group`), a description, and choose the VPC from
+ the VPC dropdown.
+1. Click "Add all the subnets related to this VPC" and
+ remove the public ones, we only want the **private subnets**.
+ In the end, you should see `10.0.1.0/24` and `10.0.3.0/24` (as
+ we defined them in the [subnets section](#subnets)).
+ Click **Create** when ready.
+
+ ![RDS Subnet Group](img/rds_subnet_group.png)
+
+### Creating the database
+
+Now, it's time to create the database:
+
+1. Select **Instances** from the left menu and click **Create database**.
+1. Select PostgreSQL and click **Next**.
+1. Since this is a production server, let's choose "Production". Click **Next**.
+1. Let's see the instance specifications:
+ 1. Leave the license model as is (`postgresql-license`).
+ 1. For the version, select the latest of the 9.6 series (check the
+ [database requirements](../../install/requirements.md#postgresql-requirements))
+ if there are any updates on this).
+ 1. For the size, let's select a `t2.medium` instance.
+ 1. Multi-AZ-deployment is recommended as redundancy, so choose "Create
+ replica in different zone". Read more at
+ [High Availability (Multi-AZ)](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.MultiAZ.html).
+ 1. A Provisioned IOPS (SSD) storage type is best suited for HA (though you can
+ choose a General Purpose (SSD) to reduce the costs). Read more about it at
+ [Storage for Amazon RDS](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/CHAP_Storage.html).
+
+1. The rest of the settings on this page request a DB isntance identifier, username
+ and a master password. We've chosen to use `gitlab-db-ha`, `gitlab` and a
+ very secure password respectively. Keep these in hand for later.
+1. Click **Next** to proceed to the advanced settings.
+1. Make sure to choose our gitlab VPC, our subnet group, set public accessibility to
+ **No**, and to leave it to create a new security group. The only additional
+ change which will be helpful is the database name for which we can use
+ `gitlabhq_production`. At the very bottom, there's an option to enable
+ auto updates to minor versions. You may want to turn it off.
+1. When done, click **Create database**.
+
+### Installing the `pg_trgm` extension for PostgreSQL
+
+Once the database is created, connect to your new RDS instance to verify access
+and to install a required extension.
+
+You can find the host or endpoint by selecting the instance you just created and
+after the details drop down you'll find it labeled as 'Endpoint'. Do not to
+include the colon and port number:
+
+```sh
+sudo /opt/gitlab/embedded/bin/psql -U gitlab -h <rds-endpoint> -d gitlabhq_production
+```
+
+At the psql prompt create the extension and then quit the session:
+
+```sh
+psql (9.4.7)
+Type "help" for help.
+
+gitlab=# CREATE EXTENSION pg_trgm;
+gitlab=# \q
+```
+
+---
+
+Now that the database is created, let's move on setting up Redis with ElasticCache.
+
+## Redis with ElastiCache
+
+ElastiCache is an in-memory hosted caching solution. Redis maintains its own
+persistence and is used for certain types of the GitLab application.
+
+To set up Redis:
+
+1. Navigate to the ElastiCache dashboard from your AWS console.
+1. Go to **Subnet Groups** in the left menu, and create a new subnet group.
+ Make sure to select our VPC and its [private subnets](#subnets). Click
+ **Create** when ready.
+
+ ![ElastiCache subnet](img/ec_subnet.png)
+
+1. Select **Redis** on the left menu and click **Create** to create a new
+ Redis cluster. Depending on your load, you can choose whether to enable
+ cluster mode or not. Even without cluster mode on, you still get the
+ chance to deploy Redis in multi availability zones. In this guide, we chose
+ not to enable it.
+1. In the settings section:
+ 1. Give the cluster a name (`gitlab-redis`) and a description.
+ 1. For the version, select the latest of `3.2` series (e.g., `3.2.10`).
+ 1. Select the node type and the number of replicas.
+1. In the advanced settings section:
+ 1. Select the multi-AZ auto-failover option.
+ 1. Select the subnet group we created previously.
+ 1. Manually select the preferred availability zones, and under "Replica 2"
+ choose a different zone than the other two.
+
+ ![Redis availability zones](img/ec_az.png)
+
+1. In the security settings, edit the security groups and choose the
+ `gitlab-security-group` we had previously created.
+1. Leave the rest of the settings to their default values or edit to your liking.
+1. When done, click **Create**.
+
+## RDS and Redis Security Group
+
+Let's navigate to our EC2 security groups and add a small change for our EC2
+instances to be able to connect to RDS. First, copy the security group name we
+defined, namely `gitlab-security-group`, select the RDS security group and edit the
+inbound rules. Choose the rule type to be PostgreSQL and paste the name under
+source.
+
+Similar to the above, jump to the `gitlab-security-group` group
+and add a custom TCP rule for port `6379` accessible within itself.
+
+## Load Balancer
+
+On the EC2 dashboard, look for Load Balancer on the left column:
+
+1. Click the **Create Load Balancer** button.
+ 1. Choose the Application Load Balancer.
+ 1. Give it a name (`gitlab-loadbalancer`) and set the scheme to "internet-facing".
+ 1. In the "Listeners" section, make sure it has HTTP and HTTPS.
+ 1. In the "Availability Zones" section, select the `gitlab-vpc` we have created
+ and associate the **public subnets**.
+1. Click **Configure Security Settings** to go to the next section to
+ select the TLS certificate. When done, go to the next step.
+1. In the "Security Groups" section, create a new one by giving it a name
+ (`gitlab-loadbalancer-sec-group`) and allow both HTTP ad HTTPS traffic
+ from anywhere (`0.0.0.0/0, ::/0`).
+1. In the next step, configure the routing and select an existing target group
+ (`gitlab-public`). The Load Balancer Health will allow us to indicate where to
+ ping and what makes up a healthy or unhealthy instance.
+1. Leave the "Register Targets" section as is, and finally review the settings
+ and create the ELB.
+
+After the Load Balancer is up and running, you can revisit your Security
+Groups to refine the access only through the ELB and any other requirement
+you might have.
+
+## Deploying GitLab inside an auto scaling group
+
+We'll use AWS's wizard to deploy GitLab and then SSH into the instance to
+configure the PostgreSQL and Redis connections.
+
+The Auto Scaling Group option is available through the EC2 dashboard on the left
+sidebar.
+
+1. Click **Create Auto Scaling group**.
+1. Create a new launch configuration.
+
+### Choose the AMI
+
+Choose the AMI:
+
+1. Go to the Community AMIs and search for `GitLab EE <version>`
+ where `<version>` the latest version as seen on the
+ [releases page](https://about.gitlab.com/releases/).
+
+ ![Choose AMI](img/choose_ami.png)
+
+### Choose an instance type
+
+You should choose an instance type based on your workload. Consult
+[the hardware requirements](../requirements.md#hardware-requirements) to choose
+one that fits your needs (at least `c4.xlarge`, which is enough to accommodate 100 users):
+
+1. Choose the your instance type.
+1. Click **Next: Configure Instance Details**.
+
+### Configure details
+
+In this step we'll configure some details:
+
+1. Enter a name (`gitlab-autoscaling`).
+1. Select the IAM role we created.
+1. Optionally, enable CloudWatch and the EBS-optimized instance settings.
+1. In the "Advanced Details" section, set the IP address type to
+ "Do not assign a public IP address to any instances."
+1. Click **Next: Add Storage**.
+
+### Add storage
+
+The root volume is 8GB by default and should be enough given that we won't store
+any data there. Let's create a new EBS volume that will host the Git data. Its
+size depends on your needs and you can always migrate to a bigger volume later.
+You will be able to [set up that volume](#setting-up-the-ebs-volume)
+after the instance is created.
+
+### Configure security group
+
+As a last step, configure the security group:
+
+1. Select the existing load balancer security group we have [created](#load-balancer).
+1. Select **Review**.
+
+### Review and launch
+
+Now is a good time to review all the previous settings. When ready, click
+**Create launch configuration** and select the SSH key pair with which you will
+connect to the instance.
+
+### Create Auto Scaling Group
+
+We are now able to start creating our Auto Scaling Group:
+
+1. Give it a group name.
+1. Set the group size to 2 as we want to always start with two instances.
+1. Assign it our network VPC and add the **private subnets**.
+1. In the "Advanced Details" section, choose to receive traffic from ELBs
+ and select our ELB.
+1. Choose the ELB health check.
+1. Click **Next: Configure scaling policies**.
+
+This is the really great part of Auto Scaling; we get to choose when AWS
+launches new instances and when it removes them. For this group we'll
+scale between 2 and 4 instances where one instance will be added if CPU
+utilization is greater than 60% and one instance is removed if it falls
+to less than 45%.
+
+![Auto scaling group policies](img/policies.png)
+
+Finally, configure notifications and tags as you see fit, and create the
+auto scaling group.
+
+You'll notice that after we save the configuration, AWS starts launching our two
+instances in different AZs and without a public IP which is exactly what
+we intended.
+
+## After deployment
+
+After a few minutes, the instances should be up and accessible via the internet.
+Let's connect to the primary and configure some things before logging in.
+
+### Configuring GitLab to connect with postgres and Redis
+
+While connected to your server, let's connect to the RDS instance to verify
+access and to install a required extension:
+
+```sh
+sudo /opt/gitlab/embedded/bin/psql -U gitlab -h <rds-endpoint> -d gitlabhq_production
+```
+
+Edit the `gitlab.rb` file at `/etc/gitlab/gitlab.rb`
+find the `external_url 'http://gitlab.example.com'` option and change it
+to the domain you will be using or the public IP address of the current
+instance to test the configuration.
+
+For a more detailed description about configuring GitLab, see [Configuring GitLab for HA](../../administration/high_availability/gitlab.md)
+
+Now look for the GitLab database settings and uncomment as necessary. In
+our current case we'll specify the database adapter, encoding, host, name,
+username, and password:
+
+```ruby
+# Disable the built-in Postgres
+postgresql['enable'] = false
+
+# Fill in the connection details
+gitlab_rails['db_adapter'] = "postgresql"
+gitlab_rails['db_encoding'] = "unicode"
+gitlab_rails['db_database'] = "gitlabhq_production"
+gitlab_rails['db_username'] = "gitlab"
+gitlab_rails['db_password'] = "mypassword"
+gitlab_rails['db_host'] = "<rds-endpoint>"
+```
+
+Next, we need to configure the Redis section by adding the host and
+uncommenting the port:
+
+```ruby
+# Disable the built-in Redis
+redis['enable'] = false
+
+# Fill in the connection details
+gitlab_rails['redis_host'] = "<redis-endpoint>"
+gitlab_rails['redis_port'] = 6379
+```
+
+Finally, reconfigure GitLab for the change to take effect:
+
+
+```sh
+sudo gitlab-ctl reconfigure
+```
+
+You might also find it useful to run a check and a service status to make sure
+everything has been setup correctly:
+
+```sh
+sudo gitlab-rake gitlab:check
+sudo gitlab-ctl status
+```
+
+If everything looks good, you should be able to reach GitLab in your browser.
+
+### Setting up the EBS volume
+
+The EBS volume will host the Git repositories data:
+
+1. First, format the `/dev/xvdb` volume and then mount it under the directory
+ where the data will be stored. For example, `/mnt/gitlab-data/`.
+1. Tell GitLab to store its data in the new directory by editing
+ `/etc/gitlab/gitlab.rb` with your editor:
+
+ ```ruby
+ git_data_dirs({
+ "default" => { "path" => "/mnt/gitlab-data" }
+ })
+ ```
+
+ where `/mnt/gitlab-data` the location where you will store the Git data.
+
+1. Save the file and reconfigure GitLab:
+
+ ```sh
+ sudo gitlab-ctl reconfigure
+ ```
+
+TIP: **Tip:**
+If you wish to add more than one data volumes to store the Git repositories,
+read the [repository storage paths docs](../../administration/repository_storage_paths.md).
+
+### Setting up Gitaly
+
+Gitaly is a service that provides high-level RPC access to Git repositories.
+It should be enabled and configured in a separate EC2 instance on the
+[private VPC](#subnets) we configured previously.
+
+Follow the [documentation to set up Gitaly](../../administration/gitaly/index.md).
+
+### Using Amazon S3 object storage
+
+GitLab stores many objects outside the Git repository, many of which can be
+uploaded to S3. That way, you can offload the root disk volume of these objects
+which would otherwise take much space.
+
+In particular, you can store in S3:
+
+- [The Git LFS objects](../../workflow/lfs/lfs_administration.md#s3-for-omnibus-installations) ((Omnibus GitLab installations))
+- [The Container Registry images](../../administration/container_registry.md#container-registry-storage-driver) (Omnibus GitLab installations)
+- [The GitLab CI/CD job artifacts](../../administration/job_artifacts.md#using-object-storage) (Omnibus GitLab installations)
+
+### Setting up a domain name
+
+After you SSH into the instance, configure the domain name:
+
+1. Open `/etc/gitlab/gitlab.rb` with your preferred editor.
+1. Edit the `external_url` value:
+
+ ```ruby
+ external_url 'http://example.com'
+ ```
+
+1. Reconfigure GitLab:
+
+ ```sh
+ sudo gitlab-ctl reconfigure
+ ```
+
+You should now be able to reach GitLab at the URL you defined. To use HTTPS
+(recommended), see the [HTTPS documentation](https://docs.gitlab.com/omnibus/settings/nginx.html#enable-https).
+
+### Logging in for the first time
+
+If you followed the previous section, you should be now able to visit GitLab
+in your browser. The very first time, you will be asked to set up a password
+for the `root` user which has admin privileges on the GitLab instance.
+
+After you set it up, login with username `root` and the newly created password.
+
+## Health check and monitoring with Prometheus
+
+Apart from Amazon's Cloudwatch which you can enable on various services,
+GitLab provides its own integrated monitoring solution based on Prometheus.
+For more information on how to set it up, visit the
+[GitLab Prometheus documentation](../../administration/monitoring/prometheus/index.md)
+
+GitLab also has various [health check endpoints](../..//user/admin_area/monitoring/health_check.md)
+that you can ping and get reports.
+
+## GitLab Runners
+
+If you want to take advantage of [GitLab CI/CD](../../ci/README.md), you have to
+set up at least one [GitLab Runner](https://docs.gitlab.com/runner/).
+
+Read more on configuring an
+[autoscaling GitLab Runner on AWS](https://docs.gitlab.com/runner/configuration/runner_autoscale_aws/).
+
+## Backup and restore
+
+GitLab provides [a tool to backup](../../raketasks/backup_restore.md#creating-a-backup-of-the-gitlab-system)
+and restore its Git data, database, attachments, LFS objects, etc.
+
+Some important things to know:
+
+- The backup/restore tool **does not** store some configuration files, like secrets; you'll
+ need to [configure this yourself](../../raketasks/backup_restore.md#storing-configuration-files).
+- By default, the backup files are stored locally, but you can
+ [backup GitLab using S3](../../raketasks/backup_restore.md#using-amazon-s3).
+- You can [exclude specific directories form the backup](../../raketasks/backup_restore.md#excluding-specific-directories-from-the-backup).
+
+### Backing up GitLab
+
+To back up GitLab:
+
+1. SSH into your instance.
+1. Take a backup:
+
+ ```sh
+ sudo gitlab-rake gitlab:backup:create
+ ```
+
+### Restoring GitLab from a backup
+
+To restore GitLab, first review the [restore documentation](../../raketasks/backup_restore.md#restore),
+and primarily the restore prerequisites. Then, follow the steps under the
+[Omnibus installations section](../../raketasks/backup_restore.md#restore-for-omnibus-installations).
+
+## Updating GitLab
+
+GitLab releases a new version every month on the 22nd. Whenever a new version is
+released, you can update your GitLab instance:
+
+1. SSH into your instance
+1. Take a backup:
+
+ ```sh
+ sudo gitlab-rake gitlab:backup:create
+ ```
+
+1. Update the repositories and install GitLab:
+
+ ```sh
+ sudo apt update
+ sudo apt install gitlab-ee
+ ```
+
+After a few minutes, the new version should be up and running.
+
+## Conclusion
+
+In this guide, we went mostly through scaling and some redundancy options,
+your mileage may vary.
+
+Keep in mind that all Highly Available solutions come with a trade-off between
+cost/complexity and uptime. The more uptime you want, the more complex the solution.
+And the more complex the solution, the more work is involved in setting up and
+maintaining it.
+
+Have a read through these other resources and feel free to
+[open an issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/new)
+to request additional material:
+
+- [GitLab High Availability](https://docs.gitlab.com/ee/administration/high_availability/):
+ GitLab supports several different types of clustering and high-availability.
+- [Geo replication](https://docs.gitlab.com/ee/administration/geo/replication/):
+ Geo is the solution for widely distributed development teams.
+- [Omnibus GitLab](https://docs.gitlab.com/omnibus/) - Everything you need to know
+ about administering your GitLab instance.
+- [Upload a license](https://docs.gitlab.com/ee/user/admin_area/license.html):
+ Activate all GitLab Enterprise Edition functionality with a license.
+- [Pricing](https://about.gitlab.com/pricing): Pricing for the different tiers.