I’ve been maintaining self-host GitLab instances for a few years. gitlab-ce is fully dockerized, you can easily deploy a GitLab container within a few minutes.
Here’s my cookbook.
To deploy a gitlab-ce container/instance, you must be familiar with the following techs and tools:
A server and a domain will be required in this tutorial. Prepare your cloud resources before you begin.
You can install docker on almost all modern Linux distribution. Please follow the official guide to install docker-engine on your sever.
To manage your docker deployment, you will also need docker-compose, please follow the official guide to install it.
curl https://raw.githubusercontent.com/ShinChven/mirrors/master/docker/install.sh | bash -
Compose is a tool for defining and running multi-container Docker applications. To manage GitLab’s configuration and variables with docker-compose is one of the best practice.
To begin with, let’s
mkdir for your deployment project.
Then create a file named
docker-compose.yml in your project directory.
A docker virtual network will be created by the directory name once you execute
docker-compose.yml is created, run the following commands in your project directory to deploy your gitlab-ce container:
docker-compose up -d
docker-compose upwill execute your docker-compose.yml.
-dDetached mode: Run containers in the background.
After container is created, use the
docker ps command to see the container’s status.
docker ps | grep 'gitlab'
See GitLab container’s status
|Up||Starting, you may see 502 error, please wait for GitLab finish starting.|
|Up||Some error occurred.|
In order to share the server’s 80/443 port with other web app and manage SSL via certbot, you should consider serving GitLab behind a reverse proxy, that’s why I disabled the nginx inside the container and left the job to host machine’s nginx instance.
Add a DNS record to point your domain to your server, and make sure port 80 and 443 is open in your server’s firewall.
Once DNS is done, we can get onto nginx.
Nginx is often preinstalled, create a simple nginx reverse proxy conf file to serve GitLab.
If everything is fine, terminal should return:
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
**If something is wrong, please check your configuration before proceed! **
nginx -s reload
The reverse proxy configuration is not finished since GitLab is configured to forward all requests to 80 to 443. SSL must be setup.
Normally a SSL certificate must be purchased from issuer, but Let’s Encrypt! is free and automated.
Run certbot, terminal will show your nginx configuration:
Then select your domain by input it’s number.
If the SSL certificate is successfully deployed, choose direct all request to https.
By now your GitLab is deployed as a docker container and is served behind a reverse proxy via https.
However, there are still a few things you should do.
If your GitLab instance is used for production, you should backup your GitLab’s config directory once deployed.
gitlab-secrets.json is missing, you will see malfunctions after you restored or migrated your GitLab.
To find GitLab’s config directory in your host machine, please see
volumes in your
docker exec -it \ # execute command inside container https://docs.docker.com/engine/reference/commandline/exec/
docker-compose.yml‘s volume mapping for path of data, backup files will be in
It is advised to set up a cron jobs in host machine to back up your GitLab’s data:
30 23 * * * docker exec gitlab /opt/gitlab/bin/gitlab-rake gitlab:backup:create
If you intend to use GitLab in production, please follow it’s version up. When your instance is behind too many major versions to the current release, you may see errors during upgrading an old instance.
To upgrade a dockerized GitLab is simple. Navigate to your docker-compose project directory, and run the following codes:
docker pull gitlab/gitlab-ce # pull latest image
docker exec -it <GITLAB_CONTAINER_NAME> gitlab-backup restore BACKUP=<BACK_UP_FILENAME>