How to setup a GitLab server using Docker

GitLab is a refined open source alternative to GitHub. Take control of your code by self-hosting your own GitLab server!

In about 15 minutes you’ll have a GitLab server running with Docker, SSL certificates, outgoing email, automatic backups and nightly updates.

If you’ve got your own server already — whether at Bytemark or not — skip the Create a Cloud Server section and run our setup script on your server instead.

Important note

• Most of you use SSH (port 22) to login to your Cloud Server. However, you probably want GitLab to allow Git-over-SSH, so in this guide we’ll change the Cloud Server to run SSH on port 2222 so that the GitLab container can use port 22.

Create a Cloud Server

1. Login to the Bytemark Panel (or start a free trial).
2. Add a Cloud Server with these settings:
   • Name: Give your server a name (eg, “gitlab”)
   • Group: Leave as “default”
   • Resources: 3 Cores, 8GiB Memory (based on GitLab’s recommendations)
     
   • Operating System: Debian 9
   • Discs: 25GiB SSD storage (or more)
   • Backup Schedule: Leave enabled (optional, but recommended)
   • Boot options: Select Add script and paste this inside:

? Copy to clipboard

#!/bin/sh
export DEBIAN_FRONTEND=noninteractive

# Wait for apt-get to be available.
while ! apt-get -qq check; do sleep 1s; done

# Install docker-ce and docker-compose.
apt-get update
apt-get install -y apt-transport-https ca-certificates curl gnupg2 software-properties-common
curl -fsSL https://download.docker.com/linux/debian/gpg | apt-key add -
add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/debian `lsb_release -cs` stable"
apt-get update
apt-get install -y docker-ce
curl -fsSL https://github.com/docker/compose/releases/download/1.21.2/docker-compose-`uname -s`-`uname -m` -o /usr/local/bin/docker-compose
chmod +x /usr/local/bin/docker-compose

# Check for security updates every night and install them.
apt-get install -y unattended-upgrades

# Retrieve configuration files. Lots of explanatory comments inside!
# If you'd rather inspect and install these files yourself, see:
# https://github.com/BytemarkHosting/configs-gitlab-docker
mkdir -p /root/compose
curl -fsSL https://raw.githubusercontent.com/BytemarkHosting/configs-gitlab-docker/master/docker-compose.yml -o /root/compose/docker-compose.yml
curl -fsSL https://raw.githubusercontent.com/BytemarkHosting/configs-gitlab-docker/master/.env -o /root/compose/.env

# Use server hostname as the domain.
# This can be changed later in the /root/compose/.env file.
DOMAIN="`hostname -f`"
sed -i -e "s|^GITLAB_DOMAIN=.*|GITLAB_DOMAIN=$DOMAIN|" /root/compose/.env

# Change SSH port to 2222, so that GitLab can use port 22.
sed -i -e "s|^#Port 22|Port 2222|" /etc/ssh/sshd_config
systemctl restart sshd.service

# Start our containers.
cd /root/compose
docker-compose up -d

3. The Panel will tell you the root password for your server. Save it!
4. Click on the Console button next to your Cloud Server. You’ll know installation has finished when you see a login prompt. You can login with username root.
5. The first time around, GitLab takes a while to finish installing so it’ll be about 10 minutes before you can access your website. (If you want to follow progress, see Troubleshooting — GitLab is up once you see lots of lines starting with ==> /var/log/gitlab.)

After installation

In your browser, navigate to the hostname of your server (eg, http://name.of.server.uk0.bigv.io).

GitLab will ask you to set a password. Once you’ve set the password, you can login with the username root and start using GitLab!

Before you start uploading code to GitLab, we recommend that you follow the steps below to Use your own domain, Enable SSL/TLS and Enable backups.

Use your own domain

NB: This is easier before you start uploading projects to GitLab, as the remote address for all repositories will change.

Login to your Cloud Server and open /root/compose/.env in a text editor:

nano /root/compose/.env

Change GITLAB_DOMAIN to your own domain. For example:

GITLAB_DOMAIN=gitlab.example.com

Restart your Docker containers to apply the change:

cd /root/compose
docker-compose down
docker-compose up -d

Enable SSL/TLS

Configure your own domain as per the previous step. The domain must have DNS records pointing to your server, otherwise this won’t work.

Login to your Cloud Server and open /root/compose/docker-compose.yml in a text editor:

nano /root/compose/docker-compose.yml

Find the following two lines and change http to https, and change false to true so that it looks like this:

external_url 'https://${GITLAB_DOMAIN}'
letsencrypt['enable'] = true

Restart your Docker containers to apply the change:

cd /root/compose
docker-compose down
docker-compose up -d

Enable backups

We’re going to use GitLab’s recommended backup method.

GitLab’s Docker image doesn’t install cron, so we have to schedule backups from the Docker server instead. Install the cron script by running these commands:

? Copy to clipboard

curl -fsSLO https://raw.githubusercontent.com/BytemarkHosting/configs-gitlab-docker/master/backup-gitlab
mv backup-gitlab /etc/cron.daily/backup-gitlab
chmod +x /etc/cron.daily/backup-gitlab

Restore a backup

Use docker-compose exec to open a shell session in the GitLab container:

cd /root/compose
docker-compose exec gitlab bash

Stop two of GitLab’s services:

gitlab-ctl stop unicorn
gitlab-ctl stop sidekiq

Look at what backups are available:

ls -l /var/opt/gitlab/backups

Backups have filenames like: 1536227393_2018_09_06_11.2.3_gitlab_backup.tar.

When running the restore command, populate the BACKUP variable with the filename (but strip off _gitlab_backup.tar).

gitlab-rake gitlab:backup:restore BACKUP=1536227393_2018_09_06_11.2.3
gitlab-ctl restart
gitlab-rake gitlab:check SANITIZE=true

Start using GitLab

Some good places to start:

• Go to your Profile Settings, change your email address from admin@example.com to something else and add an SSH key.
• Go to the Admin area and personalize your GitLab.

Troubleshooting

To view logs of what’s going on with your GitLab container, login to your Cloud Server and run:

cd /root/compose
docker-compose logs -f gitlab

The most common problems include:

• Let’s Encrypt SSL certificate failure: The container will fail to start. Check your domain has appropriate DNS records pointing to your server. (NB: your bigv.io hostname won’t work due to Let’s Encrypt rate limits.)
• Limited resources: GitLab has quite steep hardware requirements, so if you encounter poor performance or unexpected errors (eg, HTTP 500 errors) then you might need to increase your server specifications.

Technical details

Inside /root/compose you’ll find the configuration files, which are taken from our Git repository. Feel free to browse around or adapt those configuration files to your needs.

• Watchtower automatically updates your containers to the latest version. This keeps your containers secure.
• GitLab’s Docker image provides GitLab and handily also sorts out Let’s Encrypt SSL certificates for you.
• Our bytemark/smtp image allows your GitLab server to send outgoing emails if needed (eg, password resets and notifications).