Installing GitLab on Debian 9 (SSH) with a NGINX reverse proxy

Procédure

Do you need Gitlab to manage your projects? Create your own instance of GitLab on your VPS by following this tutorial.

Git is good. Gitlab is better. Gitlab is an open-source Git repository manager. Developed by GitLab Inc, it offers an intuitive graphical interface for managing your various projects while maintaining compatibility with Git. You can create feature requests, track bugs, etc. in a team and via a web browser.

Gitlab is available in several versions, both paid and free. In the following tutorial, we will install GitLab Community Edition (Gitlab CE), the free, open-source version of Gitlab.

Prerequisites

To use GitLab, you need at least :

• 2 vCores
• 4 GB of RAM

TheVPS M from the LWS Starter range is ideal for a few Gitlab projects, but if you have several collaborators and/or several projects to complete, we recommend that you take the VPS L or one of the VPS from the Pro range.

For this tutorial, we're going to consider a completely blank operating system from the Debian 9 + SSH system image offered on LWS Panel. Here are the links to other tutorials for other operating systems:

• Installing Gitlab on Ubuntu 16.04 + SSH (in progress)
• Installing Gitlab on CentOS 7 + SSH (in progress)
• Installing Gitlab on Debian 9 + ISPConfig

If you want to change the operating system on your VPS, here's a link to the help documentation: How do I change the operating system on my VPS?

Please note that this tutorial is based on a VIRGIN installation of Debian 9. If you have already installed something on it, we cannot guarantee that the tutorial will be effective and/or that all your other services will be available after installation.

Don't forget to enable the SSH port on your VPS firewall so that you can connect as root to the SSH console.

Summary of the tutorial

Here are the steps that will be covered in this tutorial:

1. Updating the operating system
2. Installing Gitlab CE
3. Setting up a NGINX reverse proxy in front of Gitlab
4. Installing a Let's Encrypt SSL certificate on the NGINX reverse proxy

Step 1: updating the operating system

Before installing anything, we recommend that you update the list of packages and the packages themselves.

On your SSH console, write the following commands:

apt-get update
apt-get upgrade -y
apt-get dist-upgrade -y

Step 2: Installing Gitlab CE

First, let's install the required dependencies:

apt-get install -y curl openssh-server ca-certificates

Next, add the Gitlab repository to your VPS:

curl https://packages.gitlab.com/install/repositories/gitlab/gitlab-ee/script.deb.sh | bash

Now let's install Gitlab:

EXTERNAL_URL="http://vpsXXXXX.lws-hosting.com" apt-get install gitlab-ee

The installation takes several minutes, so you can have a coffee while you wait.

Tip: if you have an unstable Internet connection, you can use screen to reconnect to the detachable console in the event of an unexpected disconnection. Documentation on how to use screen.

Once the installation is complete, go to http://vpsXXXXX.lws-hosting.com to configure Gitlab.

Tip: if you get a 502 error, try restarting Gitlab with the gitlab-ctl restart command and then wait 5 minutes before trying again(Ctrl+F5).

If everything goes as planned, you will be redirected to a page for creating your Gitlab password.

Specify a relatively complex password. You can also generate a random password.

Once this is done, you can connect to Gitlab with the root user and the password you specified.

Installing the NGINX reverse proxy

Now we're going to set up a reverse proxy with NGINX. This will allow you to host other sites and applications in the future, particularly if you have opted for a Cloud Pro S VPS server or higher.

The first step is to move Gitlab to an unused port. For this tutorial, we'll use port 6080 (taken at random).

Tip: you can find the list of ports already in use with the command netstat -tunap | grep LISTEN

To do this, edit the file /etc/gitlab/gitlab.rb with nano (or vim, or another editor):

nano /etc/gitlab/gitlab.rb

And edit the value of external_url to include the port:

[...]
## GitLab URL
##! URL on which GitLab will be reachable.
##! For more details on configuring external_url see:
##! https://docs.gitlab.com/omnibus/settings/configuration.html#configuring-the-external-url-for-gitlab
external_url'http://vpsXXXXX.lws-hosting.com:6080'
[...]

Ctrl+X, Y then Enter to save the file and close nano(Esc then :wq for vim).

To apply this configuration, run the following command:

gitlab-ctl reconfigure

This will take a minute or two while Gitlab synchronises its settings with the applications that Gitlab uses by default (NGINX, omnibus, etc.).

Gitlab is now on 6080. We now need to install NGINX. The installation of NGINX is summarised by the following command lines:

apt-get install -y curl gnupg2 ca-certificates lsb-release
echo "deb http://nginx.org/packages/debian `lsb_release -cs` nginx" | tee /etc/apt/sources.list.d/nginx.list
curl -fsSL https://nginx.org/keys/nginx_signing.key | apt-key add -
apt-get update
apt-get install -y nginx

Now it's time to create a NGINX configuration file for GitLab. We'll name it /etc/nginx/conf.d/000-gitlab.conf. Use nano to create this file:

nano /etc/nginx/conf.d/000-gitlab.conf

Next, we need to create a new server{} block and create the reverse proxy. Here is a suggested content :

server {
listen 80;
server_name gitlab.example.com;

location / {
proxy_pass http://localhost:6080;
proxy_redirect off;
proxy_set_header Host $http_host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Protocol $scheme;
proxy_set_header X-Url-Scheme $scheme;
}
}

Tip: The "000- " prefix is required for the file to be loaded before default.conf. Otherwise, the default.conf file will overwrite our configuration.

Activate NGINX at startup:

systemctl enable nginx

Then restart nginx with the following command:

systemctl restart nginx

Next, you need to point gitlab.example.com to your VPS by adding an A record to your DNS zone. If your DNS is managed on the LWS client space, here's how to do it:

Next, let's configure Gitlab again to accept the X-Forwarded-For header to find the real IP addresses of visitors. This is done by editing the /etc/gitlab/gitlab.rb file:

[...]
nginx['real_ip_header'] = 'X-Forwarded-For'
nginx['real_ip_recursive'] = 'on'
[...]

Next, re-synchronise the configurations of Gitlab and its embedded services:

gitlab-ctl reconfigure

At this stage, you should be able to connect to http://gitlab.exemple.com.

Installing a Let's Encrypt SSL certificate on NGINX

We are now going to secure our access with a Let's Encrypt SSL certificate. First, let's install certbot :

apt-get install certbot -y

Next, we're going to set up a webroot for Let's Encrypt authentication. To do this, edit the file /etc/nginx/conf.d/000-gitlab.conf and add these lines after the location / block:

[...]
location / {
proxy_pass http://localhost:6080;
[...]
}

location ^~ /.well-known/acme-challenge/ {
root /var/www/letsencrypt;
}
}

Create the :

mkdir -p /var/www/letsencrypt

And restart NGINX :

systemctl restart nginx

Now let's create an SSL certificate for gitlab.example.com:

certbot certonly --webroot -w /var/www/letsencrypt/ -d gitlab.example.com

Follow the instructions on the screen:

• Enter your email address
• Read and accept the terms of use
• Subscribe (or not) to the EFF newsletter

Next, we're going to edit /etc/nginx/conf.d/000-gitlab.conf again to add a new server on HTTPS/443. We need to add the following lines to the end of the file:

[...]
server {
listen 443 ssl;
server_name gitlab.example.com;

ssl_certificate /etc/letsencrypt/live/gitlab.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/gitlab.example.com/privkey.pem;

location / {
proxy_pass http://localhost:6080;
proxy_redirect off;
proxy_set_header Host $http_host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Protocol $scheme;
proxy_set_header X-Url-Scheme $scheme;
}
}

And restart your NGINX server :

systemctl restart nginx

You now have a ready-to-use Gitlab server at https://gitlab.exemple.com.