Howto – Install Gitlab on Debian in a Docker Container


In this procedure we will be installing Gitlab in a Docker Container on a freshly installed Debian Server.  Installing the OS is beyond the scope of this installation procedure, which focuses primarily on setting up docker and getting a container up and running with Gitlab.

Install Gitlab Container on Docker


The Gitlab docker image is hosted on docker hub and can therefore be pulled with docker. 

Pulling and running the image can be done with below snippet, which pulls and runs the docker image, maps a few folders from the docker host into the Gitlab container, and exposes the web, secure shell, and registry ports.

  • We instruct docker to download and run the container from the docker hub.
  • We configure the the hostname of the gitlab instance.
  • We map the ssh port to the outside world so we can ssh to the container.
  • We map 3 paths to the local filesystem.
  • The container is stateless, configuration files, data and logs are written outside of the container on the local machines filesystem.
$ sudo docker run --detach \
--hostname \
--env GITLAB_OMNIBUS_CONFIG="external_url ''" \
--publish 443:443 --publish 80:80 --publish 2222:22 --publish 4567:4567 \
--name gitlab \
--restart always \
--volume /srv/gitlab/config:/etc/gitlab \
--volume /srv/gitlab/logs:/var/log/gitlab \
--volume /srv/gitlab/data:/var/opt/gitlab \

A few useful things to know:

Check the status of the running containers on your docker instance:

$  docker container ls 

If you want to take a look into the container, you can spawn a shell session in the container with below command:

$  sudo docker exec -it gitlab /bin/bash 

Gitlab can be either configured with the parameters when deploying the container, or with the main configuration file ‘/srv/gitlab/config/gitlab.rb’ on the local filesystem (which is mapped to /etc/gitlab inside the container).  

NOTE: each time that you make a change to the configuration file, you will need to issue a gitlab reconfiguration command:

$  sudo docker exec -it gitlab gitlab-ctl reconfigure 

Editing the configuration via the local filesystem:

$  vi /srv/gitlab/config/gitlab.rb 

configuration inside the container:

$  sudo docker exec -it gitlab vi /etc/gitlab/gitlab.rb 

Restart the gitlab docker container:

$  sudo docker restart gitlab 

How to upgrade gitlab to a newer version:

To upgrade the running gitlab docker container, we need to stop and remove it, then pull the latest version.

$ sudo docker stop gitlab
$ sudo docker rm gitlab
$ sudo docker pull gitlab/gitlab-ce:latest 

After pulling the latest version, re-launch your gitlab container as u did the first time:

 $ sudo docker run --detach \
--hostname \
--env GITLAB_OMNIBUS_CONFIG="external_url ''" \
--publish 443:443 --publish 80:80 --publish 2222:22 --publish 4567:4567 \
--name gitlab \
--restart always \
--volume /srv/gitlab/config:/etc/gitlab \
--volume /srv/gitlab/logs:/var/log/gitlab \
--volume /srv/gitlab/data:/var/opt/gitlab \

Configure the web gui of gitlab to use SSL

Generate a private key and a certificate signing request with openssl:

$ mkdir -p /srv/gitlab/config/ssl
openssl genrsa -out /srv/gitlab/config/ 2048

$ openssl req -new -sha256 -key /srv/gitlab/config/ -out /srv/gitlab/config/ 

Now sign this certificate signing request with our internal root certificate authority, and copy the resulting base64 encoded key back to gitlab:

$ vi /srv/gitlab/config/ssl/ 

Configuring gitlab for ldap authentication:

First copy our root certification authority certificate to the trusted_certificates folder of gitlab ‘/srv/gitlab/config/trusted-certs/myca001.crt ‘.  (this is necessary to validate the server certificate of our ldap server for tls encryption)

Open the gitlab configuration file:

$ vi /srv/gitlab/config/gitlab.rb 

Find the LDAP section and add below configuration snippet for our Active Directory

gitlab_rails['ldap_enabled'] = true
gitlab_rails['ldap_servers'] = YAML.load <<-EOS # remember to close this block with 'EOS' below
main: # 'main' is the GitLab 'provider ID' of this LDAP server
  ## label
  # A human-friendly name for your LDAP server. It is OK to change the label later,
  # for instance if you find out it is too large to fit on the web page.
  # Example: 'Paris' or 'Acme, Ltd.'
  label: 'mycompany AD'
  host: ''
  port: 636
  uid: 'sAMAccountName'
  encryption: 'simple_tls' # "start_tls" or "simple_tls" or "plain"
  bind_dn: 'CN=ADBind,OU=SystemAccounts,OU=Operations,DC=mycompany,DC=com'
  password: 'mypassword'
  # This setting specifies if LDAP server is Active Directory LDAP server.
  # For non AD servers it skips the AD specific queries.
  # If your LDAP server is not AD, set this to false.
  active_directory: true
  # If allow_username_or_email_login is enabled, GitLab will ignore everything
  # after the first '@' in the LDAP username submitted by the user on login.
  # Example:
  # - the user enters '' and 'p@ssw0rd' as LDAP credentials;
  # - GitLab queries the LDAP server with 'jane.doe' and 'p@ssw0rd'.
  # If you are using "uid: 'userPrincipalName'" on ActiveDirectory you need to
  # disable this setting, because the userPrincipalName contains an '@'.
  allow_username_or_email_login: false
  # If lowercase_usernames is enabled, GitLab will lower case the username.
  lowercase_usernames: false
  # Base where we can search for users and groups
  #   Ex. ou=People,dc=gitlab,dc=example
  base: 'DC=mycompany,DC=com'
  group_base: 'OU=Groups,OU=1. Data Center Assets,,DC=mycompany,DC=com'
  admin_group: 'web_mygitlab001.mycompany.com_admin'
  # Filter LDAP users
  #   Format: RFC 4515
  #   Ex. (employeeType=developer)
  #   Note: GitLab does not support omniauth-ldap's custom filter syntax.
  user_filter: ''

Or the short version 🙂

gitlab_rails['ldap_enabled'] = true gitlab_rails['ldap_servers'] = { 'main' => {   'label' => 'mycompany AD',   'host' =>  '',   'port' => 636,   'uid' => 'sAMAccountName',   'encryption' => 'simple_tls',   'verify_certificates' => true,   'bind_dn' => 'CN=ADBind,OU=SystemAccounts,OU=Operations,DC=mycompany,DC=com',   'password' => 'Lymmundectoriathoracc8',   'active_directory' => true,   'base' => 'DC=mycompany,DC=com',   'group_base' => 'OU=Groups,OU=1. Data Center Assets,,DC=mycompany,DC=com',   'admin_group' => 'web_mygitlab001.mycompany.com_admin'   } } 

Now connect to the docker container and reconfigure gitlab for the changes to take effect:

$ docker exec -it gitlab /bin/bash
$ gitlab-ctl reconfigure 

If you surft to the gitlab web page, a new tab for ldap authentication should now be visible.

Enabling Container Registry on Gitlab


Edit the gitlab configuration file:

$ vi /srv/gitlab/config/gitlab.rb 

configure the registry_external_url

registry_external_url '' 

Reconfigure gitlab:

$ docker exec -it gitlab /bin/bash 
$ gitlab-ctl reconfigure 

Howto clone your git repository over SSH

There are two possibilities for this, the first one uses a ssh url syntax, on which you can specify the correct port of the gitlab server, the second example involves creating a .ssh/config file with an entry for gitlab server ssh parameters.

In the first example (url syntax):

Create a folder for your repository:

$ mkdir -p /home/netadm/myproject 

Then clone your repository in this folder

$ cd /home/netadm/myproject
$ git clone ssh:// 

In the second example (ssh config alias):

$ vi ~/.ssh/config 

Paste below config snippet:

 Host gitlab
        Port 2222
        User git
        IdentityFile ~/.ssh/id_rsa
        PreferredAuthentications publickey 

Then you can use the config alias to clone your repository with the correct ssh settings:

$ git clone gitlab:IT/Pastebin.git 

Published by

Ronny Van den Broeck

I'm a network and system engineer for more than 20 years now. During this period I became a pro in hunting down one's and zero's, with an eager mindset to help people accomplish the same or abstract them away from the matrix.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s