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.
Prerequisites
To deploy a gitlab-ce container/instance, you must be familiar with the following techs and tools:
- Linux
- docker
- Reverse proxy
- nginx
- certbot
- ssl/https
A server and a domain will be required in this tutorial. Prepare your cloud resources before you begin.
Install Docker
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.
If you happen to use a ubuntu server, I have a script to install it which is based on official guide(ubuntu) and can save your time significantly.
1 | curl https://raw.githubusercontent.com/ShinChven/mirrors/master/docker/install.sh | bash - |
Deploy GitLab Via docker-compose
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.
The docker-compose.yml
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 up
.
1 | web: |
docker-compose up
Once your docker-compose.yml
is created, run the following commands in your project directory to deploy your gitlab-ce container:
1 | docker-compose up -d |
docker-compose up
will execute your docker-compose.yml.-d
Detached mode: Run containers in the background.
Check status
After container is created, use the docker ps
command to see the container’s status.
1 | docker ps | grep 'gitlab' |
See GitLab container’s status
STATUS | EXPLAIN |
---|---|
Up | Starting, you may see 502 error, please wait for GitLab finish starting. |
Up | Boot finished. |
Up | Some error occurred. |
Serve GitLab Behind A Nginx Reverse Proxy
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.
DNS
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 Configuration
Nginx is often preinstalled, create a simple nginx reverse proxy conf file to serve GitLab.
1 | vim /etc/nginx/conf.d/gitlab.conf |
1 | server { |
Test Nginx Configuration
1 | nginx -t |
If everything is fine, terminal should return:
1 | nginx: the configuration file /etc/nginx/nginx.conf syntax is ok |
**If something is wrong, please check your configuration before proceed! **
Reload Nginx Configuration
1 | 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.
Let’s Encrypt! (Certbot/SSL)
Normally a SSL certificate must be purchased from issuer, but Let’s Encrypt! is free and automated.
Install Certbot
certbot is the commandline tool for Let’s Encrypt, please install it with it’s nginx plugin by following the official guide.
If you happen to use Ubuntu 20.04, installation is simple according to Digital Ocean‘s guide:
1 | # https://www.digitalocean.com/community/tutorials/how-to-secure-nginx-with-let-s-encrypt-on-ubuntu-20-04 |
Deploy SSL via Certbot
Run certbot, terminal will show your nginx configuration:
1 | certbot |
Then select your domain by input it’s number.
If the SSL certificate is successfully deployed, choose direct all request to https.
Done.
Finish Up
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.
Back up Secrets
IMPORTANT!
If your GitLab instance is used for production, you should backup your GitLab’s config directory once deployed.
If 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-compose.yml
.
Back up Data
1 | docker exec -it \ # execute command inside container https://docs.docker.com/engine/reference/commandline/exec/ |
See docker-compose.yml
‘s volume mapping for path of data, backup files will be in data/backups
Back up Data Automatically
It is advised to set up a cron jobs in host machine to back up your GitLab’s data:
1 | crontab -e |
1 | 30 23 * * * docker exec gitlab /opt/gitlab/bin/gitlab-rake gitlab:backup:create |
Upgrade GitLab
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:
1 | docker pull gitlab/gitlab-ce # pull latest image |
Restore
1 | docker exec -it <GITLAB_CONTAINER_NAME> gitlab-backup restore BACKUP=<BACK_UP_FILENAME> |