Development Tools

GitLab User Guide

| Product: GitLab

Overview

This guide covers the deployment and configuration of GitLab Community Edition on Linux using cloudimg AMIs from the AWS Marketplace. GitLab is a complete DevOps platform that provides Git repository management, CI/CD pipelines, issue tracking, code review, and more in a single application.

What's included in this AMI:

  • GitLab Community Edition with web interface on port 80
  • Integrated PostgreSQL database at /var/opt/gitlab/postgresql
  • Preconfigured URL setup scripts for private IP, public IP, or DNS hostname
  • Automatic startup on boot via GitLab services
  • OS package update script for keeping the system current
  • AWS CLI v2 for AWS service integration
  • Systems Manager Agent (SSM) for remote management
  • CloudWatch Agent for monitoring
  • Latest security patches applied at build time
  • 24/7 cloudimg support with guaranteed 24 hour response SLA

Prerequisites

Before launching this AMI, ensure you have:

  1. An active AWS account
  2. An active subscription to the GitLab listing on AWS Marketplace
  3. An EC2 key pair for SSH access
  4. Familiarity with EC2 instance management and SSH

Recommended Instance Type: t3.large (2 vCPU, 8 GB RAM) or larger. The minimum requirements are 2 vCPU, 4 GB RAM, and 20 GB disk space. GitLab is a resource intensive application and performs best with adequate memory.

Step 1: Launch the AMI

  1. Navigate to the AWS Marketplace and search for "GitLab cloudimg"
  2. Click Continue to Subscribe, accept the terms, then Continue to Configuration
  3. Select your preferred Region and Software Version
  4. Click Continue to Launch
  5. Choose Launch through EC2 for full control over instance configuration
  6. Select your instance type (t3.large recommended)
  7. Configure storage: 20 GB gp3 minimum, 50 GB or more recommended for active repositories
  8. Configure your Security Group with the following inbound rules:
Port Protocol Source Purpose
22 TCP Your IP SSH access
80 TCP Your IP GitLab web interface
5432 TCP Your IP PostgreSQL database (restrict to internal only)

Important: Port 5432 (PostgreSQL) should only be accessible from within your VPC or from specific trusted IPs. Do not expose the database to the public internet.

  1. Select your EC2 key pair and launch the instance

Step 2: Connect via SSH

Once your instance is running and has passed both status checks (2/2), connect using SSH:

ssh -i your-key.pem ec2-user@<public-ip-address>

Replace your-key.pem with the path to your EC2 key pair and <public-ip-address> with your instance's public IP.

Important: Wait for the EC2 instance to reach 2/2 successful status checks before attempting to connect. If you connect too early, you may see errors such as:

Permission denied (publickey,gssapi-keyex,gssapi-with-mic).

This is expected during the initial boot process. Wait for both status checks to pass and try again.

To switch to the root user:

sudo su -

Step 3: Configure the GitLab URL

Three URL configuration scripts are provided under /stage/scripts/. Choose the one that matches your use case. Each script updates the external_url setting in /etc/gitlab/gitlab.rb and runs gitlab-ctl reconfigure.

Note: The reconfigure process takes approximately 3 minutes and 20 seconds on average (tested on t3.medium, t3.large, and t3.xlarge instance types).

Option A: Use private IP address

Use this if you access GitLab from within the same VPC:

/stage/scripts/gitlab-ce-set-private-url.sh

GitLab will be accessible at http://PRIVATE_IP_OF_YOUR_EC2_INSTANCE

Option B: Use public IP address

Use this if you access GitLab from the internet:

/stage/scripts/gitlab-ce-set-public-url.sh

GitLab will be accessible at http://PUBLIC_IP_OF_YOUR_EC2_INSTANCE

Option C: Use a DNS hostname

Use this if you have a custom domain pointed to your instance:

/stage/scripts/gitlab-ce-set-dns-hostname-url-http.sh

GitLab will be accessible at http://DNS_HOSTNAME_OF_YOUR_CHOOSING

Expected output upon successful completion of any script:

Notes:
Default admin account has been configured with following details:
Username: root
Password: You didn't opt-in to print initial root password to STDOUT.
Password stored to /etc/gitlab/initial_root_password. This file will be cleaned up in first
reconfigure run after 24 hours.

NOTE: Because these credentials might be present in your log files in plain text, it is highly
recommended to reset the password following
https://docs.gitlab.com/ee/security/reset_user_password.html#reset-your-root-password.

gitlab Reconfigured!

Step 4: Log In to GitLab

Open your web browser and navigate to the URL configured in Step 3.

You will see the GitLab login page. Sign in with:

  • Username: root
  • Password: Retrieve from the file generated on the instance:
cat /etc/gitlab/initial_root_password

Important: This password file is automatically deleted after 24 hours. Make a note of the password or change it promptly using the steps below.

Step 5: Change the Root Password

It is strongly recommended to change the default root password immediately after your first login.

Method 1: From the GitLab web interface

  1. Log in as root
  2. Navigate to your user profile settings
  3. Change your password from the Password section

Method 2: From the command line

As the root OS user, run:

gitlab-rake "gitlab:password:reset[root]"

Wait approximately 30 seconds for the command prompt to return, then enter your new password:

[root@ip-172-31-87-42 scripts]# gitlab-rake "gitlab:password:reset[root]"
Enter password:
Confirm password:
Password successfully updated for user with username root.
[root@ip-172-31-87-42 scripts]#

You can now log in with the username root and your newly set password.

GitLab is now available and ready to use.

Server Components

Component Install Path
GitLab Community Edition /etc/gitlab/gitlab.rb
PostgreSQL Database /var/opt/gitlab/postgresql

Note: Component versions may be updated on first boot by the automatic OS package update script.

Filesystem Layout

Mount Point Size Description
/ 38 GB Root filesystem
/boot 2 GB Operating system kernel files
/var/opt/gitlab 9.8 GB GitLab data directory (repositories, uploads, packages)

Key GitLab directories:

Directory Purpose
/etc/gitlab GitLab configuration files
/etc/gitlab/gitlab.rb Main configuration file
/var/opt/gitlab Application data (repos, database, uploads)
/var/opt/gitlab/postgresql PostgreSQL database files
/var/opt/gitlab/git-data Git repository storage
/var/log/gitlab GitLab service logs

Managing GitLab Services

GitLab uses its own service management through gitlab-ctl.

Check service status:

gitlab-ctl status

Stop all GitLab services:

gitlab-ctl stop

Start all GitLab services:

gitlab-ctl start

Restart all GitLab services:

gitlab-ctl restart

Reconfigure GitLab (required after changing /etc/gitlab/gitlab.rb):

gitlab-ctl reconfigure

View GitLab logs:

gitlab-ctl tail

Scripts and Log Files

Script/Log Path Description
initial_boot_update.sh /stage/scripts Updates the OS with the latest packages on first boot
initial_boot_update.log /stage/scripts Output log for the boot update script
gitlab-ce-set-private-url.sh /stage/scripts Configure GitLab URL to the instance private IP
gitlab-ce-set-public-url.sh /stage/scripts Configure GitLab URL to the instance public IP
gitlab-ce-set-dns-hostname-url-http.sh /stage/scripts Configure GitLab URL to a DNS hostname

On Startup

An OS package update script runs on first boot to ensure the image is fully up to date. You can disable this by removing the script and its crontab entry:

rm -f /stage/scripts/initial_boot_update.sh

crontab -e
# Delete the following line, save and exit:
@reboot /stage/scripts/initial_boot_update.sh

Troubleshooting

Cannot access GitLab web interface on port 80

  1. Verify GitLab services are running: gitlab-ctl status
  2. Check that your security group allows inbound traffic on port 80 from your IP
  3. Ensure you have run one of the URL configuration scripts from Step 3
  4. Check GitLab logs for errors: gitlab-ctl tail

GitLab is slow or uses too much memory

  1. GitLab requires a minimum of 4 GB RAM. If using a smaller instance, upgrade to t3.large or larger.
  2. Monitor memory usage: free -m
  3. Consider increasing swap space if memory is constrained
  4. Reduce the number of Sidekiq workers in /etc/gitlab/gitlab.rb

GitLab reconfigure fails

  1. Check for syntax errors in /etc/gitlab/gitlab.rb
  2. Review the reconfigure log: gitlab-ctl tail reconfigure
  3. Ensure adequate disk space: df -h

Cannot log in with root password

  1. If the 24 hour window has passed, the /etc/gitlab/initial_root_password file is deleted
  2. Reset the password from the command line: gitlab-rake "gitlab:password:reset[root]"

502 error when accessing GitLab

  1. GitLab may still be starting up. Wait 2 to 3 minutes and refresh.
  2. Check if all services are running: gitlab-ctl status
  3. Restart GitLab: gitlab-ctl restart

Security Recommendations

  • Change the default root password immediately after first login
  • Restrict port access: Only allow port 80 from trusted IPs. Never expose port 5432 publicly.
  • Enable HTTPS: Configure SSL in /etc/gitlab/gitlab.rb using Let's Encrypt or your own certificate
  • Disable public registration: Navigate to Admin Area > Settings > General > Sign up restrictions and uncheck "Sign up enabled"
  • Enable two factor authentication: Encourage or enforce 2FA for all users
  • Configure backup schedules: Set up automated backups with gitlab-backup create
  • Keep GitLab updated: Regularly update GitLab packages with yum update gitlab-ce
  • Monitor logs: Review /var/log/gitlab/ for suspicious activity

Support

If you encounter any issues with this product, contact cloudimg support:

  • Email: support@cloudimg.co.uk
  • Website: www.cloudimg.co.uk
  • Support hours: 24/7 with guaranteed 24 hour response SLA