There is a new version of this tutorial available for Ubuntu 18.04 (Bionic Beaver).
How to Install and Configure GitLab on Ubuntu 16.04
This tutorial exists for these OS versions
- Ubuntu 18.04 (Bionic Beaver)
- Ubuntu 16.04 (Xenial Xerus)
On this page
GitLab is an open source GIT repository manager based on Rails and developed by GitLab Inc. It is a web-based GIT repository manager that allows your team to work on code, track bugs and feature requests and to test and deploy applications. GitLab provides features like a wiki, issue tracking, code reviews, activity feeds and merge management. It is capable of hosting multiple projects.
GitLab is available in four editions:
- Gitlab CE (Community Edition) - self-hosted, free and support from the Community forum.
- Gitlab EE (Enterprise Edition) - self-hosted, paid app, comes with additional features.
- GitLab.com - SaaS, free.
- GitLab.io - Private GitLab instance managed by GitLab Inc.
In this tutorial, I will show you step-by-step how to install GitLab CE (Community Edition) on your own Ubuntu 16.04 Xenial Xerus server. In this tutorial, I will be using the 'omnibus' package provided by GitLab for easy installation.
What we will do:
- Install Packages
- Install GitLab
- Configure GitLab URL
- Generate SSL Let's encrypt and DHPARAM Certificate
- Enable Nginx HTTPS for GitLab
- Configure UFW Firewall
- Perform the GitLab Installation
- Ubuntu 16.04 Server - 64bit
- Min RAM 2GB
- Root Privileges
Step 1 - Install required Ubuntu Packages
The first step is to install the packages needed for the GitLab installation. Please log in to the server as root user and upddate the Ubuntu repository.
ssh [email protected]
Now install the packages including curl for downloading the GitLab repository, ca-certificates, and postfix for the SMTP configuration.
Install all packages with the apt command below.
sudo apt install curl openssh-server ca-certificates postfix
During postfix installation, you will be prompted about the configuration, select 'Internet Site'.
and then enter the server domain name that shall be used for sending an email.
Step 2 - Install Gitlab
In this step, we will install GitLab using the omnibus packages. Omnibus will install all packages, services, and tools required for running GitLab on your server.
Add GitLab repository with the curl command.
curl -sS https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash
And then install GitLab CE Community Edition with the apt command.
sudo apt install gitlab-ce
Wait for the server to download and install the gitlab package. When the installation is complete, you will see the results as below.
Step 3 - Configure Gitlab Main URL
Now we should configure the URL that will be used to access our GitLab server. I will use the domain name 'gitlab.hakase-labs.co' for the GitLab URL here (please choose your own domain name) and I'll use HTTPS for users access security.
The main configuration of GitLab is in the '/etc/gitlab' directory. Go to that directory and edit the configuration file 'gitlab.rb' with vim.
In the GitLab configuration go to line 9 'external_url' and change the URL to your URL 'gitlab.hakase-labs.co'.
Save the file and exit the editor. In the next step will enable HTTPS for GitLab.
Step 4 - Generate SSL Let's encrypt and DHPARAM Certificate
In this step, we will enable the HTTPS protocol for GitLab. I will use a free SSL certificates provided by let's encrypt for the gitlab domain name.
Install letsencrypt command-line tool with apt command.
sudo apt install letsencrypt -y
When the installation is complete, generate a new certificate for the gitlab domain name with the command below.
letsencrypt certonly -d gitlab.hakase-labs.co
Enter your email address for the SSL certificate renew notification.
Choose 'Agree' for the Let's Encrypt Terms of Services and wait.
When it's done, you will see the result below.
New Let's encrypt certificate files for GitLab have been generated. You can find the certificate files in the '/etc/letsencrypt/live' directory.
Next, create a new directory named 'ssl' under the GitLab configuration directory.
mkdir -p /etc/gitlab/ssl/
And generate dhparam pem files in the ssl directory with the openssl command.
sudo openssl dhparam -out /etc/gitlab/ssl/dhparams.pem 2048
Now change the permissions of the certificate files to 600.
chmod 600 /etc/gitlab/ssl/*
The SSL Let's encrypt cert for GitLab and the DHPARAM certificate has been generated.
Step 5 - Enable Nginx HTTPS for GitLab
At this stage, we have the certificate files from Letsencrypt in '/etc/letsencrypt/live' directory and the DHPARAM certificate in the '/etc/gitlab/ssl' directory.
In this step, we will configure a GitLab to use our certificate files. Go to the '/etc/gitlab' directory, then edit 'gitlab.rb' configuration with vim.
Change the external url to use 'https' instead of 'http'.
Then add the new SSL configuration for gitlab as below.
nginx['redirect_http_to_https'] = true
nginx['ssl_certificate'] = "/etc/letsencrypt/live/gitlab.hakase-labs.co/fullchain.pem"
nginx['ssl_certificate_key'] = "/etc/letsencrypt/live/gitlab.hakase-labs.co/privkey.pem"
nginx['ssl_dhparam'] = "/etc/gitlab/ssl/dhparams.pem"
We will enable HTTP to HTTPS redirect in gitlab.
Save the file and exit vim.
Now we need to run the command below as root to apply the new gitlab configuration.
sudo gitlab-ctl reconfigure
You will see the results as below.
HTTPS Configuration for GitLab has been completed.
Step 6 - Configure UFW Firewall
In this step, we will enable the UFW firewall. It's already installed on the system, we just need to start the service. We will run GitLab behind the UFW firewall, so we must open the HTTP and HTTPS ports.
Enable UFW firewall with the command below.
The command will run ufw service and add it to start automatically at the boot time.
Next, open new ports ssh, HTTP, and HTTPS.
ufw allow ssh
ufw allow http
ufw allow https
Now check the firewall status and make sure ssh, http, and https ports is on the list.
HTTP and HTTPS ports are configured.
Step 7 - Gitlab post-installation
GitLab has been installed to the system, and it's running behind the UFW firewall. In this step, we will do some quick settings like changing password, username and profile settings.
Open your web browser and type in the gitlab URL, mine is 'gitlab.hakase-labs.co'. You will be redirected to the HTTPS connection.
Reset GitLab root password
Now login to GitLab with user 'root' and with your password.
Change Username and Profile
On the top right corner, click your profile and choose 'Profile Settings'.
On the profile tab, exchange the default name with your name and email with your email address. Now click 'Update Profile'.
Click on the tab 'Account', change username with your own username. Then click 'Update Username'.
Add SSH Key
Make sure you already have a key, if you do not have an SSH key, you can generate with it with the command below.
And you will get two keys, 'id_rsa' your private key and 'id_rsa.pub' your public key.
Next, click on the tab 'SSH Key', copy the content of 'id_rsa.pub' file and paste to the key box, and click 'Add Key'.
New SSH Key has been added.
Sign up Restrictions and Limit Settings
Click on the 'admin area' icon, and then click on the gear icon and choose 'Settings'.
On the 'Account and Limit Settings' - you can configure max projects per user and the 'Sign-up Restrictions', you can add the domain name of your email to the white-list box.
And if all is complete, scroll to the bottom and click 'Save'.
Basic GitLab configuration has been completed.
Step 8 - Testing
Finally, we will do some tests to ensure that our GitLab system is working properly.
Create New Project
Click the plus icon on the top to create a new project repository. Type in your project name, description, and setup the visibility settings of your project. Then click on the 'Create project' button.
The new project has been created.
Test First Commit and Push
After the 'howtoforge' project has been created, you will be redirected to the project page. Now start adding new content to the repository. Make sure Git is installed on your computer and setup the global username and email for git with the command below.
git config --global user.name "hakase"
git config --global user.email "[email protected]"
Clone the Repository and add a README.md file.
git clone https://[email protected]/hakase/howtoforge.git
You will be asked for the 'hakase' user password. Please type the same password that you used when we accessed GitLab the first time.
Commit a new file to the howtoforge repository.
git add .
git commit -m 'Add README.md file by hakase-labs'
Next, push the change to the repository on the GitLab server.
git push origin master
Type in your password and press Enter to continue. You will see the result as below.
Now open the howtoforge project from your web browser, and you will see that the new README.md file has been added to the repository.
Gitlab has been installed on a Ubuntu 16.04 Xenial Xerus server.