Installing self-managed instance of GitLab

If you are like me, curious to see how things works under the hood. So I am learning how the CI (continuous integration) and CD (continuous delivery) pipeline works. In the world of DevOps and Agile delivery this is important to make sure that we can deploy our codes without error to the test environment and subsequently to the production environment.

Enter GitLab, which provide an amazing serving to allow this to happen. There are several options to use, you can sign up their cloud based solution (ideal) this will allow you to collaborate with your co-worker and being able to deploy, merge code seamlessly. For me, I like to do it manually for my personal projects and learning the system. So here are the step by step guide if you would like to install the local instance of GitLab on your virtual machine or physical machine.

Note that in this build I am using a VMWare virtual machine running Debian linux OS in my local network. So here goes:

Step 1. Create a Debian Linux VMWare machine

I am saving some time by using the pre-build Debian in VMWare provided by osboxes.org, you can get them in the following location. At the time of writing the version is Debian 11 Bullseye.

Once you have downloaded the image, you will need to create a blank virtual machine then mount the vmdk image downloaded so that it is bootable. Just follow their guide page. Check to make sure that it boots an you can use the credential provided in the same page.

Note: Please make sure you change the root password and also the osboxes user password for security.

Step 2. Decide on what you want to call the machine (Very Important)

In this example, I’m calling mine gitlab.mach. So from this point onwards I will refer to mine gitlab install via http://gitlab.mach url. Note that I didn’t use the https because unless you have a webserver that allows connection externally and have a proper ssl certificate, it is not going to work.

Then you need to make sure your machine have a fixed ip address and not dhcp. You can do this by editing the file /etc/network/interfaces with the following

iface ens33 inet static
    address 192.168.8.250
    netmask 255.255.255.0
    gateway 192.168.8.1

You will have to edit the above to suit your own network. In the example above my machine have the static ip of 192.168.8.250.

I also add the gitlab.mach into my /etc/hosts file in my local machine so that I can address it easily. So in this case you will be adding the following lines to your local machine /etc/hosts (if you are using linux OS, OSX). For Windows you will need to edit the hosts files in the Windows directory

192.168.8.250 gitlab.mach

Step 3. Install GitLab

The next step is to install gitlab using the instructions provided from the official website. I am following the instructions for Debian in the following url https://about.gitlab.com/install/#debian

In summary here are the commands:

sudo apt-get update
sudo apt-get install -y curl openssh-server ca-certificates perl
sudo apt-get install -y postfix
curl https://packages.gitlab.com/install/repositories/gitlab/gitlab-ee/script.deb.sh | sudo bash
sudo EXTERNAL_URL="http://gitlab.mach" apt-get install gitlab-ee

Note that for the last line, I am referring to the machine name that I have decided in Step 2 above. If you didn’t do this properly then you need to use the instruction to change the external_url in the configuration file to fix it.

Step 4. Configure GitLab to use Apache instead of Nginx

The default installation of gitlab will attempt to use Nginx to serve the web pages, this doesn’t work for me, so I am using the following script to change it to use Apache instead.

I found the following website that provide some instructions on how to do that https://topdigital.agency/install-and-configure-gitlab-and-website-on-apache-server-in-your-vps/

If you are using the Debian distribution from osboxes above, the apache webserver is already installed, so you just have to makes sure the following mods are enabled using the following command

sudo a2enmod proxy_http
sudo a2enmod rewrite
sudo a2enmod ssl
sudo a2enmod headers
sudo service apache2 restart

Now at this point you should check that your apache webserver is running by pointing your web browser to http://gitlab.mach. You should see the default apache website. Or you can use the following command to check

sudo systemctl status apache2

It should show that the apache 2 is active (running) like in the following screenshot.

Now you will change the configuration of gitlab located in /etc/gitlab/gitlab.rb using the following command

sudo vi /etc/gitlab/gitlab.rb

Add the following lines

external_url “http://gitlab.mach”
# Disable nginx
nginx[‘enable’] = false
# Give apache user privileges to listen to GitLab
web_server[‘external_users’] = [‘www-data’]

Now create the apache2 config file using the following command

sudo vi /etc/apache2/sites-available/gitlab.conf

And paste the following lines

<VirtualHost *:80> ServerName gitlab.mach
ServerSignature Off

ProxyPreserveHost On
AllowEncodedSlashes NoDecode

<Location />
Require all granted

ProxyPassReverse http://127.0.0.1:8080
ProxyPassReverse gitlab.mach
</Location>

RewriteEngine on
RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_FILENAME} !-f
RewriteRule .* http://127.0.0.1:8080%{REQUEST_URI} [P,QSA]

# needed for downloading attachments
DocumentRoot /opt/gitlab/embedded/service/gitlab-rails/public

#Set up apache error documents, if back end goes down (i.e. 503 error) then a maintenance/deploy page is thrown up.
ErrorDocument 404 /404.html
ErrorDocument 422 /422.html
ErrorDocument 500 /500.html
ErrorDocument 503 /deploy.html

LogFormat “%{X-Forwarded-For}i %l %u %t \”%r\” %>s %b” common_forwarded
ErrorLog /var/log/apache2/gitlab.mach_error.log
CustomLog /var/log/apache2/gitlab.mach_forwarded.log common_forwarded
CustomLog /var/log/apache2/gitlab.mach_access.log combined env=!dontlog
CustomLog /var/log/apache2/gitlab.mach.log combined

</VirtualHost>

Save the file above and enable the site using the following command:

sudo a2ensite gitlab  #Restart apache
sudo service apache2 restart #Reconfigure gitlab
sudo gitlab-ctl reconfigure  #Restart gitlab server
sudo gitlab-ctl restart

If all goes well you should have a working gitlab when you point your browser to the following address http://mach.gitlab

Now at this point you can use the root user to login and manage your gitlab projects.