What is GitLab?

GitLab is a git-based code hosting service that users can use to collaborate on coding projects. GitLab is an alternative to Github, which has over 68 MILLION users! While Github is the gold standard for code-hosting, GitLab provides nearly all the features of Github, and more! There are many reasons to use GitLab, but for small users with thier own servers, the biggest advantage is arguably the fact that you can have unlimited private repositories without paying for it. Additionally, I like to have more control over the things I use, and GitLab, being self-hosted, is an excellent alternative. GitLab also features excellent backup solutions to save all your data in case of a disaster. Gitlab does come with an enterprise plan, but for most "self-hosters", all the good stuff is free! In fact, I host all my code on my own personal GitLab!

Step-by-Step guide

Minimum recommendations for your Server or VM:

  • Atleast 4GB of RAM. Highly recommended to use a dedicated Server or VM for GitLab. I also recommend Ubuntu Server instead of Ubuntu Desktop, as your resources don't have to deal with graphics
  • Atleast 2 cores or 2 vCPUs
  • Recommend atleast 40GB of disk space. More if possible. Assign it 100GB if you are thin-provisioning a disk for a VM
  1. First, install all the dependencies:
    sudo apt-get install -y curl openssh-server ca-certificates
  2. Next, you are going to install a Postfix Server which will handle all the emails sent by GitLab
    sudo apt-get install -y postfix
    • Use Internet Site as you Postfix installation type
    • Enter the Domain name that you want the GitLab emails to be sent using. For example, by name is set to gitlab.shivamtrivedi.com
  3. Next, you will add the GitLab package repository to your machine
    curl -sS https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash
  4. Next, install the GitLab package
    sudo EXTERNAL_URL="http://<domain-name> apt-get install gitlab-ce"
    Note: - DO NOT change the URL to https. To enable native https support, follow this page. I will explaing reverse-proxying to the GitLab server using your Apache frontend later in this guide.
    - You can change gitlab-ce to gitlab-ee for enterprise edition, if you want to have the option of upgrading to enterprise edition
  5. You can now browse to your hostname and you should be able to access GitLab from there!

Setting up your GitLab server behind a reverse proxy

GitLab comes bundled with its own instance of Nginx web server. If you wish to enable SSL support, have the external url with "https" in it, and still be able to reverse proxy to GitLab via http, make the following changes to the /etc/gitlab/gitlab.rb file:

external_url "https://<domain-name>"
nginx['listen_port'] = 8081 #(or leave this at 80 for default http access)
nginx['listen_https'] = false

Also, I am including a sample SMTP configuration for localhost:

gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = "localhost"
gitlab_rails['smtp_port'] = 25
gitlab_rails['smtp_domain'] = "<smtp-domain-name>"
gitlab_rails['smtp_enable_starttls_auto'] = false
gitlab_rails['smtp_tls'] = false

Last, add the VirtualHost to your Apache config. Here is a sample VirtualHost config for incoming http connections (they are redirected to HTTPS):

<VirtualHost *:80>

ServerName <domain-name>
ServerAlias <alternate-domain-name>
ServerAdmin <your-actual-email>

Redirect permanent / https://<domain-name>/

ErrorLog ${APACHE_LOG_DIR}/error-http.log
CustomLog ${APACHE_LOG_DIR}/access-http.log combined

</VirtualHost>

Here is a sample VirtualHost config for all incoming HTTPS connections:

<VirtualHost *:443>

ServerName <domain-name>
ServerAlias <alternate-domain-name>
ServerAdmin <your-actual-email>

ProxyPreserveHost On
ProxyPass "/" "http://<IP>:<port>/"
ProxyPassReverse "/" "http://<IP>:<port>/"
ErrorLog ${APACHE_LOG_DIR}/error-ssl.log
CustomLog ${APACHE_LOG_DIR}/access-ssl.log combined

SSLEngine On

#Uncomment the line below if using Let's Encrypt
#Include /etc/letsencrypt/options-ssl-apache.conf
SSLCertificateFile <Path-To-Certificate>
SSLCertificateKeyFile <Path-To-Private-Key>

</VirtualHost>

And that's it! This should give you a working instance of GitLab! You can configure the rest of GitLab using the webpage. If you are getting Apache errors, make sure your Apache configs are correct and reverse proxying to the right IP and port. If you get GitLa Server Capacity or some other errors. Make sure to let GitLab boot, or give it more resources such as RAM (GitLab is very RAM hungry) or CPU power.

Some other useful commands

  • gitlab-ctl and gitlab-rake are your friends, especially for reconfiguration and backup functionality
  • Use sudo gitlab-ctl reconfigure every time you make a change to GitLab's configuration via command-line
  • Use sudo gitlab-ctl restart to restart the GitLab server
  • Here's a guide for GitLab backup stratergies