Programster's Blog

Tutorials focusing on Linux, programming, and open-source

Deploy GitLab Through Docker

Table of Contents

  1. About
    1. Related Posts
  2. Deployment Instructions
    1. Requirements
    2. Install Docker
    3. Configure SSH Port
    4. Docker Run Command
    5. Login - Default User
  3. Updating GitLab
    1. Updating Across Multiple Versions
  4. References

About

GitLab is an excellent open source self-hosted alternative to using GitHub. However, I find it to be much more useful and don't really think of it as an "alternative" at all.

Deploying GitLab through Docker has become a lot simpler than it used to be, and this tutorial will show you how in just a few simple steps.

Deployment Instructions

Requirements

  • At least 2GB RAM, preferably 3+

Install Docker

If you haven't already, install docker, then install docker compose.

Configure SSH Port

Next, we need to change the server's SSH port from the default 22 to something else such as 2222 or 23825. You can do this by editing the /etc/ssh/sshd_config file and changing the line below

...
# What ports, IPs and protocols we listen for 
Port 22
...

You will need to remember this so that next time you SSH into the server, you specify the port with -p like so:

ssh -p 2222 my-host-or-ip.org

Docker Run Command

Now we can deploy the gitlab container by executing the following script:

HOSTNAME="gitlab.mydomain.com"

sudo docker run \
  --detach \
  --hostname $HOSTNAME \
  --publish 443:443 \
  --publish 80:80 \
  --publish 22:22 \
  --publish 5000:5000 \
  --publish 5001:5001 \
  --name gitlab \
  --restart always \
  --volume $PWD/gitlab/config:/etc/gitlab \
  --volume $PWD/gitlab/logs:/var/log/gitlab \
  --volume $PWD/gitlab/data:/var/opt/gitlab \
  --log-driver json-file \
  --log-opt max-size=10m \
  --log-opt max-file=3 \
  gitlab/gitlab-ce:latest

Don't forget to set the HOSTNAME. The hostname must not start with http:// or https://. I would recommend setting up a secondary "data" disk through LVM, and performing this action/script within there. This will save you a lot of effort later if your server starts to run out of space and you need to expand. Moving the volume files correctly without messing up GItlab is almost impossible, whereas with LVM, you could add a disk, and expand across that. This will allow you to retain all your existing KVM snapshots, which expanding a qcow2 disk image does not allow you to do. Port 5000 is for the container registry if you wish to enable it, and 5001 is for debugging it.

Docker Compose File

If you wish to use Docker compose instead, then the equivalent would be:

services:
  gitlab:
    container_name: "gitlab"
    image: gitlab/gitlab-ce:${GITLAB_VERSION}
    ports:
      - "443:443"
      - "80:80"
      - "22:22"
      - "5000:5000"
      - "5001:5001"
    restart: always
    volumes:
      - ./gitlab/config:/etc/gitlab
      - ./gitlab/data:/var/opt/gitlab
      - ./gitlab/logs:/var/log/gitlab
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

Login - Default User

After the container has deployed, you will need to wait a while before the website will appear when you type your server's IP or hostname into your browser's URL.

To log in, the default user is root. You will then need to find out what the password is, which can be found by executing the following command on the host:

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

Updating GitLab

If you are updating GitLab frequently (like once a month), then you will generally be updating by just one version at a time, and don't need to worry about issues that can arise if you are jumping multiple versions. In such a case, you can just keep running the following commands to update to the latest version of GitLab. However, I recommend taking a snapshot of your server first just in case.

# Pull the latest image
docker pull gitlab/gitlab-ce:latest

# kill and remove the existing container
docker stop `gitlab`
docker rm `gitlab`

# Launch a new container using the new image.
sudo docker run \
  --detach \
  --hostname gitlab.example.com \
  --publish 443:443 \
  --publish 80:80 \
  --publish 22:22 \
  --publish 5000:5000 \
  --publish 5001:5001 \
  --name gitlab \
  --restart always \
  --volume /srv/gitlab/config:/etc/gitlab \
  --volume /srv/gitlab/logs:/var/log/gitlab \
  --volume /srv/gitlab/data:/var/opt/gitlab \
  --log-driver json-file \
  --log-opt max-size=10m \
  --log-opt max-file=3 \
  gitlab/gitlab-ce:latest

This will always pull the latest image, irrespective of major releases. You may need to manually specify image versions when there has been a major release change, in order to ensure that you upgrade to the latest version of the previous major release, before upgrading to the next major release version. Refer to the upgrade paths.

Updating Across Multiple Versions

If you are updating across multiple versions, then you need to use a tool like the Gitlab Upgrade Path, to specify your current version and your desired version, for which it will tell you about any intermediary versions you need to update to along the way first.

Once you have those intermediary versions, use the Docker tags to upgrade to those images one by one, and be sure to wait until all of the background migrations have completed each time, before running the next upgrade step.

References

Last updated: 20th January 2025
First published: 16th August 2018

This blog is created by Stuart Page

I'm a freelance web developer and technology consultant based in Surrey, UK, with over 10 years experience in web development, DevOps, Linux Administration, and IT solutions.

Need support with your infrastructure or web services?

Get in touch