Install GitLab

How to Install GitLab on Ubuntu 26.04 Using Docker Compose

GitLab is a powerful open-source DevOps platform that combines source code management, CI/CD, issue tracking, and collaboration tools in a single application. Whether you’re managing personal projects or coordinating large development teams, GitLab provides everything needed to streamline the software development lifecycle.

In this tutorial, you’ll learn how to install GitLab on Ubuntu 26.04 using Docker Compose. Since GitLab support for Ubuntu 26.04 is not available through the official APT repository at the time of writing, we’ll deploy GitLab inside a Docker container.

Prerequisites

Before you begin, make sure you have:

  • An Ubuntu 26.04 server
  • At least 8 GB RAM available
  • SSH access as root or a user with sudo privileges
  • A domain name or subdomain (recommended), or a public server IP address

Throughout this guide:

  • Commands prefixed with # should be run as root or using sudo
  • Commands prefixed with $ should be run as a regular user

Step 1: Update the System

First, connect to your Ubuntu server via SSH.

ssh root@IP_Address -p Port_Number

Replace:

  • IP_Address with your server’s IP address
  • Port_Number with your SSH port

Verify the Ubuntu Version

Check that the server is running Ubuntu 26.04:

lsb_release -a

Install Gitlab Ubuntu Howsnip

This command displays the current Linux distribution and version.

Update Package Information

Next, refresh the package index:

apt update

Install Gitlab Ubuntu Howsnip

This ensures your system uses the latest package information before installing additional software.

Step 2: Install Required Dependencies

Several packages are required before installing Docker and GitLab.

Run:

apt install ca-certificates curl gnupg git sudo

Install Gitlab Ubuntu Howsnip

Note: Installing dependencies first helps avoid installation issues later.

Step 3: Create a Dedicated System User

It’s a good practice to manage GitLab using a dedicated user account.

Create a new user named master:

/usr/sbin/adduser master

Install Gitlab Ubuntu Howsnip

During the setup process, you’ll be prompted to create a password.

Important: Use a strong password that includes uppercase letters, lowercase letters, numbers, and special characters.

Step 4: Grant Sudo Privileges

Add the newly created user to the sudo group:

/usr/sbin/usermod -aG sudo master

Install Gitlab Ubuntu Howsnip

Adding the user to the sudo group allows administrative tasks to be executed without logging in directly as root.

You can verify group membership later with:

groups master

Step 5: Install Docker Engine

GitLab will be deployed inside a Docker container. First, configure Docker’s official repository.

Create the Docker Keyring Directory

install -m 0755 -d /etc/apt/keyrings

Install Gitlab Ubuntu Howsnip

This creates a secure directory for repository signing keys.

Download Docker’s GPG Key

curl -fsSL https://download.docker.com/linux/debian/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg

The GPG key allows your system to verify Docker packages.

Set Correct Permissions

chmod a+r /etc/apt/keyrings/docker.gpg

This makes the key readable by APT.

Add the Docker Repository

echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian \
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
tee /etc/apt/sources.list.d/docker.list > /dev/null

Install Gitlab Ubuntu Howsnip

This command adds Docker’s package repository to your system.

Update Package Lists

apt update

Install Gitlab Ubuntu Howsnip

Install Docker Components

apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Install Gitlab Ubuntu Howsnip

This installs:

  • Docker Engine
  • Docker CLI
  • Container runtime
  • Docker Buildx
  • Docker Compose plugin

Verify the Installation

Confirm Docker is installed correctly:

docker version

If Docker is running, you’ll see information about both the Docker client and server.

Install Gitlab Ubuntu Howsnip

Step 6: Configure Docker for Non-Root Usage

By default, running Docker commands without sudo may produce a permissions error. To allow a user to run Docker commands directly, add the user to the Docker group.

/usr/sbin/usermod -aG docker master

Install Gitlab Ubuntu Howsnip

Switch to the new user:

su - master

Now create the directories that GitLab will use for persistent storage:

sudo mkdir -p /opt/gitlab/{config,logs,data}

Set ownership:

sudo chown -R master: /opt/gitlab

Why These Directories Matter

  • /opt/gitlab/config โ€“ Stores GitLab configuration
  • /opt/gitlab/logs โ€“ Stores service logs
  • /opt/gitlab/data โ€“ Stores repositories and application data

Important: These directories ensure your GitLab data remains available even if the container is recreated.

Step 7: Create the Docker Compose Configuration

Move into the GitLab directory:

cd /opt/gitlab

Create a Docker Compose file:

nano docker-compose.yml

Install Gitlab Ubuntu Howsnip

Paste the following configuration into the file:

services:
  web:
    image: 'gitlab/gitlab-ce:latest'
    container_name: 'gitlab'
    restart: always
    hostname: 'gitlab.yourdomain.com'

  environment:
    GITLAB_OMNIBUS_CONFIG: |
    external_url 'https://gitlab.yourdomain.com'
    gitlab_rails['gitlab_shell_ssh_port'] = 2222

  ports:
    - '80:80'
    - '443:443'
    - '2222:22'

  volumes:
    - '/opt/gitlab/config:/etc/gitlab'
    - '/opt/gitlab/logs:/var/log/gitlab'
    - '/opt/gitlab/data:/var/opt/gitlab'

  shm_size: '256m'

If you do not have a domain name, use your server’s public IP address for both:

  • hostname
  • external_url

Step 8: Deploy the GitLab Container

Start GitLab using Docker Compose:

docker compose up -d

Install Gitlab Ubuntu Howsnip

The initial deployment can take several minutes.

Monitor Container Startup

Follow the logs in real time:

docker logs -f gitlab

This allows you to monitor initialization progress and identify any startup issues.

Install Gitlab Ubuntu Howsnip

Step 9: Access GitLab

Once the container finishes initializing, open a web browser and visit:

https://gitlab.yourdomain.com

or the IP address configured in external_url.

GitLab will display the initial login page.

Install Gitlab Ubuntu Howsnip

Retrieve the Initial Root Password

GitLab automatically creates a root account during installation.

To view the generated password, run:

docker exec -it gitlab grep 'Password:' /etc/gitlab/initial_root_password

Install Gitlab Ubuntu Howsnip

Example output:

Password: your-generated-password

Use:

  • Username: root
  • Password: The value returned by the command above

Security Tip: After your first login, change the default root password immediately.

Install Gitlab Ubuntu Howsnip

Troubleshooting Notes

a) GitLab Takes a Long Time to Start

The first startup may take several minutes because GitLab must initialize its services and database.

Check progress with:

docker logs -f gitlab

b) Can’t Access GitLab from a Browser

Verify that:

  • Docker container is running
  • Ports 80, 443, and 2222 are open
  • The configured domain points to the correct server IP
  • The external_url value is correct

c) Docker Permission Denied Error

If you still receive Docker permission errors after adding the user to the Docker group, log out and back in, or start a new shell session.

Conclusion

You have successfully installed GitLab on Ubuntu 26.04 using Docker Compose. The setup includes Docker Engine, persistent storage volumes, and a containerized GitLab deployment that can be managed easily through Docker.

After logging in with the initial root account, you can begin creating projects, managing repositories, configuring CI/CD pipelines, and collaborating with your development team from a single platform.