GitLab CE Installation on Linux

GitLab Community Edition is a complete DevOps platform providing Git repository management, CI/CD pipelines, issue tracking, and team collaboration features. With the Omnibus installer, deploying GitLab becomes straightforward, offering a comprehensive solution for organizations managing code, projects, and deployments. This guide covers the Omnibus installation, configuration, Nginx setup, SSL encryption, SMTP configuration, and GitLab Runner setup.

Table of Contents

Prerequisites

Ensure you have:

  • Ubuntu 20.04 LTS or later
  • Root or sudo access
  • A registered domain name
  • Minimum 4GB RAM (8GB recommended)
  • 30GB available disk space
  • Basic Linux administration knowledge

Update system packages:

sudo apt update && sudo apt upgrade -y

System Requirements

Verify system meets GitLab requirements:

Check OS version:

lsb_release -a
uname -r

Verify available resources:

free -h
df -h

Install required dependencies:

sudo apt install -y curl openssh-server ca-certificates postfix perl-base

Package Repository Setup

Add GitLab repository:

curl https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash

Verify repository is configured:

sudo apt-cache search gitlab-ce

GitLab Installation

Install GitLab Community Edition:

sudo EXTERNAL_URL="https://gitlab.example.com" apt install -y gitlab-ce

The installation process will:

  1. Install dependencies
  2. Configure services
  3. Initialize database
  4. Generate SSL certificates

Verify installation completed successfully:

sudo gitlab-ctl status

Monitor installation progress:

sudo tail -f /var/log/gitlab/gitlab-rails/application.log

Wait for all services to become available (may take several minutes).

Configuration

Edit GitLab configuration file:

sudo nano /etc/gitlab/gitlab.rb

Configure essential settings:

external_url 'https://gitlab.example.com'

# Email configuration
gitlab_rails['incoming_email_enabled'] = true
gitlab_rails['incoming_email_address'] = "[email protected]"

# Backup configuration
gitlab_rails['backup_path'] = '/var/opt/gitlab/backups'
gitlab_rails['backup_archive_permissions'] = 0644
gitlab_rails['backup_keep_time'] = 604800

# Database configuration
postgresql['max_connections'] = 500
postgresql['shared_buffers'] = "256MB"

# Redis configuration  
redis['maxmemory'] = "1gb"

# Unicorn configuration
unicorn['worker_processes'] = 4
unicorn['worker_timeout'] = 60

# Nginx configuration
nginx['enable'] = true
nginx['redirect_http_to_https'] = true
nginx['ssl_protocols'] = "TLSv1.2 TLSv1.3"
nginx['ssl_ciphers'] = "HIGH:!aNULL:!MD5"

Apply configuration changes:

sudo gitlab-ctl reconfigure

Monitor reconfiguration:

sudo tail -f /var/log/gitlab/gitlab-rails/application.log

Verify all services:

sudo gitlab-ctl status
sudo gitlab-healthcheck

Nginx Web Server

GitLab's Omnibus installer includes Nginx configuration. Verify it's properly set up:

Check Nginx status:

sudo systemctl status nginx

View GitLab Nginx configuration:

sudo cat /etc/nginx/sites-enabled/gitlab.conf

The configuration should include:

server {
    listen 80;
    listen [::]:80;
    server_name gitlab.example.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name gitlab.example.com;

    client_max_body_size 100m;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Test Nginx configuration:

sudo nginx -t

Reload Nginx:

sudo systemctl reload nginx

SSL Certificate Configuration

GitLab Omnibus can manage SSL certificates automatically. Configure Let's Encrypt:

Edit GitLab configuration:

sudo nano /etc/gitlab/gitlab.rb

Add:

letsencrypt['enable'] = true
letsencrypt['contact_emails'] = ['[email protected]']
letsencrypt['auto_renew'] = true
letsencrypt['auto_renew_hour'] = 1
letsencrypt['auto_renew_minute'] = 0

Alternatively, use existing certificates:

letsencrypt['enable'] = false
nginx['ssl_certificate'] = "/etc/letsencrypt/live/gitlab.example.com/fullchain.pem"
nginx['ssl_certificate_key'] = "/etc/letsencrypt/live/gitlab.example.com/privkey.pem"

Obtain certificate using Certbot:

sudo apt install -y certbot
sudo certbot certonly --standalone -d gitlab.example.com

Reconfigure GitLab:

sudo gitlab-ctl reconfigure

Verify certificate installation:

sudo openssl x509 -in /etc/letsencrypt/live/gitlab.example.com/fullchain.pem -noout -dates

SMTP Email Setup

Configure email delivery for notifications:

Edit GitLab configuration:

sudo nano /etc/gitlab/gitlab.rb

Add SMTP configuration:

gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = "smtp.gmail.com"
gitlab_rails['smtp_port'] = 587
gitlab_rails['smtp_user_name'] = "[email protected]"
gitlab_rails['smtp_password'] = "your-app-password"
gitlab_rails['smtp_domain'] = "gmail.com"
gitlab_rails['smtp_authentication'] = "plain"
gitlab_rails['smtp_enable_starttls_auto'] = true
gitlab_rails['smtp_tls'] = false

gitlab_rails['gitlab_email_from'] = '[email protected]'
gitlab_rails['gitlab_email_display_name'] = 'GitLab'
gitlab_rails['gitlab_email_reply_to'] = '[email protected]'

Apply changes:

sudo gitlab-ctl reconfigure

Test SMTP configuration:

sudo gitlab-rails console
Gitlab::Email::ServiceEmailValidator.new('[email protected]').execute
exit

GitLab Runner Installation

Install GitLab Runner for CI/CD pipelines:

Add GitLab Runner repository:

curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh | sudo bash

Install runner:

sudo apt install -y gitlab-runner

Register runner:

sudo gitlab-runner register

Follow the prompts:

  1. GitLab instance URL: https://gitlab.example.com
  2. Registration token: (from GitLab Admin → Runners)
  3. Runner description: My Runner
  4. Tags: docker, linux
  5. Executor: docker
  6. Default image: ubuntu:latest

Verify runner status:

sudo gitlab-runner status
sudo gitlab-runner list

Backup Configuration

Configure automated backups:

Edit GitLab configuration:

sudo nano /etc/gitlab/gitlab.rb

Update backup settings:

gitlab_rails['backup_path'] = '/var/opt/gitlab/backups'
gitlab_rails['backup_archive_permissions'] = 0644
gitlab_rails['backup_keep_time'] = 604800

Apply configuration:

sudo gitlab-ctl reconfigure

Create manual backup:

sudo gitlab-rake gitlab:backup:create

Backup location:

ls -lh /var/opt/gitlab/backups/

Schedule daily backups:

sudo crontab -e

Add:

0 2 * * * /opt/gitlab/bin/gitlab-rake gitlab:backup:create CRON=1 >> /var/log/gitlab-backup.log 2>&1

Restore from backup:

sudo gitlab-ctl stop unicorn
sudo gitlab-ctl stop sidekiq
sudo gitlab-rake gitlab:backup:restore BACKUP=filename
sudo gitlab-ctl start

Performance Optimization

Configure database connection pooling:

sudo nano /etc/gitlab/gitlab.rb

Add:

postgresql['max_connections'] = 500
postgresql['shared_buffers'] = "512MB"
postgresql['work_mem'] = "16MB"

redis['maxmemory'] = "2gb"
redis['maxmemory_policy'] = "allkeys-lru"

unicorn['worker_processes'] = 8
unicorn['worker_timeout'] = 60

Enable object storage for artifacts (optional):

gitlab_rails['object_store']['enabled'] = true
gitlab_rails['object_store']['proxy_download'] = true
gitlab_rails['object_store']['connection'] = {
  'provider' => 'AWS',
  'aws_access_key_id' => 'your-access-key',
  'aws_secret_access_key' => 'your-secret-key',
  'region' => 'us-east-1',
  'bucket' => 'gitlab-artifacts'
}

Reconfigure:

sudo gitlab-ctl reconfigure

Troubleshooting

Check service status:

sudo gitlab-ctl status

View logs:

sudo tail -f /var/log/gitlab/gitlab-rails/application.log

Diagnose issues:

sudo gitlab-healthcheck

Reset admin password:

sudo gitlab-rails console -e production
user = User.where(id: 1).first
user.password = 'new-password'
user.password_confirmation = 'new-password'
user.save!
exit

Check Nginx:

sudo nginx -t
sudo systemctl status nginx

Conclusion

GitLab Community Edition is now fully installed and configured with Omnibus, providing a complete DevOps platform. With Nginx, SSL encryption, SMTP email, and CI/CD runners configured, you have a powerful tool for code management and automation. Regular backups and performance optimization ensure reliable operation. Explore GitLab's features like issue tracking, merge requests, and pipelines to maximize team productivity.