GitLab CE on AWS User Guide

Overview

This image runs GitLab Community Edition Omnibus, the all in one upstream package from packages.gitlab.com. A single instance delivers the full GitLab stack: nginx serving on port 80, the Puma application server, embedded PostgreSQL for the database, embedded Redis for the cache and job queue, Sidekiq background workers, Gitaly for Git RPC, GitLab Workhorse for large transfers, and the bundled container registry. Git over SSH is served on port 22, alongside the system SSH daemon.

The GitLab application data, including the PostgreSQL database, the Git repositories, uploaded files and the registry, lives on a dedicated 40 GB gp3 EBS volume mounted at /var/opt/gitlab. This data tier is independent of the operating system disk and can be resized later without rebuilding the instance.

A one shot service rotates the GitLab root administrator password on the first boot of every deployed instance, so two instances launched from the same Amazon Machine Image never share credentials. The password is written to /root/gitlab-credentials.txt with mode 0600. The default Omnibus initial root password file is wiped at image build time, so no default credential ever ships in the image.

On the first boot the firstboot service also reads the instance's public IPv4 address through EC2 IMDSv2 and rewrites the external_url value in /etc/gitlab/gitlab.rb accordingly, then re runs gitlab-ctl reconfigure so nginx, Workhorse and the application server all agree on the customer visible URL.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network (and the networks that will push and pull over Git SSH), and inbound ports 80 and 443 from the networks that will access the GitLab web interface
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for GitLab CE. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of m5.xlarge or larger. GitLab Omnibus needs at least 4 GB of RAM, and a busy server with 50+ users wants m5.2xlarge. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that allows inbound port 22 from your management network and inbound ports 80 and 443 from the networks that will access the web interface. Leave the root volume at the default size or larger.

Select Launch instance. First boot initialisation, which rewrites external_url and rotates the root password, takes approximately three to five minutes after the instance state becomes Running and the status checks pass.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg GitLab CE Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens ports 22, 80, and 443 as described above.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type m5.xlarge \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --block-device-mappings '[{"DeviceName":"/dev/sda1","Ebs":{"VolumeSize":30,"VolumeType":"gp3"}}]' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=gitlab-ce-01}]'

The command prints a JSON document on success. Note the instance ID, then retrieve its public address once it is running with aws ec2 describe-instances --instance-ids <instance-id> --query "Reservations[].Instances[].PublicIpAddress" --output text.

Step 3: Connect and Retrieve Initial Credentials

Connect over SSH with the key pair you selected and the public IP address from step 2. The SSH login user depends on the operating system of the AMI variant you launched:

AMI variant	SSH login user
GitLab CE on Ubuntu 24.04	ubuntu

The firstboot service waits for GitLab to be serving before it rotates the root password, so first boot completion typically lags the SSH daemon coming up by a couple of minutes. Confirm the sentinel file is present before reading the credentials file:

ssh <login-user>@<public-ip>
sudo ls -la /var/lib/cloudimg/gitlab-firstboot.done
sudo cat /root/gitlab-credentials.txt

You will see a plain text file containing the GitLab URL, the sign in URL, the root username, the rotated root password, and the Git SSH port. Copy these values somewhere secure (a password manager or encrypted vault). Do not commit them to source control.

From the same SSH session you can confirm the deployment is healthy:

curl -fsS -o /dev/null -w 'sign-in HTTP %{http_code}\n' http://127.0.0.1/users/sign_in
sudo gitlab-ctl status

A sign-in HTTP 200 response and a gitlab-ctl status output that lists every bundled service as run: confirms the full GitLab stack is serving requests.

Step 4: First Login to the GitLab Web Interface

Open a web browser and navigate to http://<public-ip>/. GitLab presents the Community Edition sign in page.

Enter the username root and the password from /root/gitlab-credentials.txt, then select Sign in. GitLab shows the personal dashboard for the root administrator after a successful login.

The administrator dashboard surfaces your projects, groups, work items, merge requests and a quick start panel. The dashboard also displays the upstream security advisories that the GitLab maintainers want every administrator to act on, such as the public sign up restriction reminder.

Step 5: Restrict Public Sign Ups and Change the Root Email

By default the GitLab Omnibus package allows anyone reaching the instance to register an account. For a private deployment, select Deactivate on the sign up restrictions banner on the dashboard, or open the admin area at http://<public-ip>/admin/application_settings/general and clear the Sign up enabled checkbox.

While you are in the admin area, open the root user under Admin then Users, select Edit, and set a real email address so password recovery and system notifications reach you. You can also rotate the root password from the same page if you prefer not to keep the firstboot generated value.

Step 6: Create Your First Project

Open the Projects area in the left hand navigation and select New project. GitLab presents a chooser of project templates; for a fresh repository select Create blank project.

Give the project a name, choose a visibility level (private, internal, or public), and tick Initialize repository with a README if you want a starter commit. Select Create project. GitLab provisions the bare repository on the dedicated Gitaly volume at /var/opt/gitlab/git-data/repositories/.

The Explore projects area at http://<public-ip>/explore lists every project on the instance that you have access to:

Step 7: Push a Repository over HTTPS and over SSH

To clone the new project over HTTPS, use the URL from the project's Clone dropdown with your username and password:

git clone http://<public-ip>/root/my-project.git
cd my-project
echo 'Hello GitLab' > README.md
git add README.md
git commit -m 'first commit'
git push

To use Git over SSH instead, paste your public SSH key into Edit profile then SSH Keys in the GitLab UI. The image serves Git SSH on the same port 22 that you use for shell access, with the special git user:

git clone git@<public-ip>:root/my-project.git

You can confirm that GitLab SSH is responding with the gitlab-shell banner:

ssh -T git@<public-ip>

GitLab replies with Welcome to GitLab, @root! if the SSH key is associated with your user.

Step 8: Configure a GitLab Runner for CI/CD

GitLab CI requires at least one registered Runner to execute pipeline jobs. The simplest pattern is a separate EC2 instance running gitlab-runner registered against this server.

In the GitLab UI open Admin then CI/CD then Runners and select New instance runner. Choose Linux and select Create runner. GitLab displays a registration token; copy it.

On a second small EC2 instance (a t3.small is sufficient for a shell or docker executor) install the Runner and register it with the token:

sudo curl -fsSL https://gitlab-runner-downloads.s3.amazonaws.com/latest/deb/gitlab-runner_amd64.deb \
  -o /tmp/gitlab-runner.deb
sudo dpkg -i /tmp/gitlab-runner.deb
sudo gitlab-runner register \
  --non-interactive \
  --url http://<public-ip>/ \
  --registration-token <token> \
  --executor shell \
  --description "shared shell runner"

The Runner appears in the Runners list in the GitLab UI within a few seconds.

Step 9: Enable HTTPS with Let's Encrypt

For any production GitLab deployment serve the site over HTTPS so passwords, Git push traffic and personal access tokens cannot be intercepted. The Omnibus package has built in Let's Encrypt support that you toggle in /etc/gitlab/gitlab.rb.

The following assumes you have a DNS A record pointing your fully qualified domain name at the instance's public IP address.

sudo sed -i "s|^external_url .*|external_url 'https://gitlab.your-domain.example'|" /etc/gitlab/gitlab.rb
sudo tee -a /etc/gitlab/gitlab.rb >/dev/null <<'GLRB'
letsencrypt['enable'] = true
letsencrypt['contact_emails'] = ['admin@your-domain.example']
nginx['redirect_http_to_https'] = true
GLRB
sudo gitlab-ctl reconfigure

GitLab's reconfigure step requests the certificate, installs it, switches nginx to HTTPS, and schedules automatic renewal. The web UI will be reachable on https://gitlab.your-domain.example/ once the reconfigure finishes.

Step 10: Backups and Maintenance

GitLab has two data sources that must be backed up together: the application data (the embedded PostgreSQL database, the Git repositories, the uploads, the registry, the CI artifacts) and the server configuration and secrets in /etc/gitlab/.

The Omnibus gitlab-backup command bundles the application data into a single tarball under /var/opt/gitlab/backups/:

sudo gitlab-backup create
sudo tar -czf /var/backups/gitlab-config-$(date +%F).tgz -C /etc gitlab

Ship both artifacts to an Amazon S3 bucket or another object store. Restoration is gitlab-backup restore against an empty GitLab instance plus an unpack of the /etc/gitlab tarball.

For kernel and package updates, Ubuntu's unattended-upgrades is enabled on the deployed AMI, so security patches apply automatically. To update GitLab itself, run sudo apt-get update && sudo apt-get install gitlab-ce to pull the latest version from the packages.gitlab.com repository, then sudo gitlab-ctl reconfigure.

Step 11: Scaling Beyond a Single Instance

For larger deployments, GitLab Omnibus supports decoupling individual subsystems while keeping the same all in one binary on the application node:

• Move the embedded PostgreSQL to Amazon RDS for PostgreSQL and point Omnibus at it via gitlab_rails['db_host']
• Move the embedded Redis to Amazon ElastiCache for Redis via gitlab_rails['redis_host']
• Offload the GitLab container registry, CI artifacts and LFS objects to Amazon S3 by configuring the object storage settings under gitlab_rails['object_store']
• Place a load balancer (an Application Load Balancer or an AWS Network Load Balancer for the Git SSH traffic) in front of multiple GitLab application nodes, with shared Gitaly nodes for the Git repositories

Each of these patterns is documented in the official GitLab reference architectures at https://docs.gitlab.com/ee/administration/reference_architectures/.

---

Screenshots

The GitLab Community Edition sign-in page, served on first boot with no manual setup.

The GitLab dashboard after signing in as root, showing projects and activity.

Creating a new project from the GitLab projects interface.

The GitLab projects explore page listing repositories on the instance.

---

Support

cloudimg provides 24/7/365 expert technical support for this image. Guaranteed response within 24 hours, one hour average for critical issues. Contact support@cloudimg.co.uk.

For general GitLab administration questions consult the GitLab community forum at https://forum.gitlab.com/ and the documentation at https://docs.gitlab.com/.