GitLab is a web-based open-source Git repository manager written in Ruby including wiki, issue management, code review, monitoring, and continuous integration and deployment. It enables developers to create, review, and deploy their projects.
There are three different editions of GitLab available, Community Edition (CE), Enterprise Edition (EE), and a GitLab-hosted version.
There are several ways to install GitLab depending on the required use case. This tutorial covers the steps necessary for installing and configuring GitLab (CE) on an Ubuntu 18.04 system using the Omnibus packages.
This tutorial assumes that you have a fresh Ubuntu 18.04 installation. According to the GitLab requirements page, it is recommended to use a server with:
- at least 4GB of RAM memory.
- 2 CPU cores.
- at least 2GB of swap space.
- (optional) Domain or subdomain pointing to the server IP address.
For an additional layer of security it is recommended to set up a basic firewall. You can follow the steps in our How To Set Up a Firewall with UFW on Ubuntu 18.04 guide.
Before starting with the tutorial, make sure you are logged in as a user with sudo privileges.
Installing Required Dependencies
Refresh the local package index and install the dependencies with the following commands:
sudo apt update
In order for GitLab to be able to send notification emails, you can either install and use Postfix or use some transactional mail service such as SendGrid, MailChimp, MailGun or SES in which case you can skip the following step and configure [GitLab SMTP settings] (https://docs.gitlab.com/omnibus/settings/smtp.html) after the installation is completed.
Run the following commands to install Postfix on your Ubuntu server:
debconf-set-selections <<< "postfix postfix/mailname string $(hostname -f)"
For more detailed information about how to setup your own mail server check this series.
GitLab installation is a pretty straight forward process. We will install the GitLab CE package using the
apt package manager.
Start by adding the GitLab repository to your system sources list using the following curl command:
curl https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash
Once the repository is enabled install the GitLab package by running the following command.
sudo apt install gitlab-ce
The installation process may take a while and after a successful installation, you will see the following output:
Thank you for installing GitLab!
Adjusting the Firewall Rules
The guide about setting up a basic firewall is linked in the prerequisites section. To be able to access the GitLab interface we need to open ports
sudo ufw allow OpenSSH
To be sure that the required ports are open you can check the status of the firewall with:
sudo ufw status
Status: active To Action From -- ------ ---- 80/tcp ALLOW Anywhere 443/tcp ALLOW Anywhere OpenSSH ALLOW Anywhere 80/tcp (v6) ALLOW Anywhere (v6) 443/tcp (v6) ALLOW Anywhere (v6) OpenSSH (v6) ALLOW Anywhere (v6)
Set the GitLab URL
Before accessing the GitLab web interface we need to set the URL on which GitLab will be reachable. Open Gitlab’s configuration file and make the following changes:
sudo nano /etc/gitlab/gitlab.rb
Near the top of the configuration file, you will see a line starting with
external_url. Change the value to match your domain/subdomain or IP address. If you have domain use
https and if you want to access the GitLab interface through your server IP address use
Next search for “Let’s Encrypt integration”, uncomment the line starting with
letsencrypt['enable'] and set it to true. Optionally if you want to receive emails from Let’s Encrypt concerning your domain uncomment the line starting with
letsencrypt['contact_emails'] and add your email address.
If you set the
external_url to an IP address then don’t enable Let’s Encrypt integration.
letsencrypt['enable'] = true letsencrypt['contact_emails'] = ['firstname.lastname@example.org'] # This should be an array of email addresses to add as contacts
Finally, save and close the file and run the following command to reconfigure Gitlab:
sudo gitlab-ctl reconfigure
The command will reconfigure your GitLab settings and generate a free Let’s encrypt SSL certificate.
Configure GitLab through the Web Interface
Now that you have configured the GitLab URL you can start with the initial configuration through the GitLab web interface.
Launch your web browser and navigate to:
1. Setting administrative account password
The first time you access the web interface you’ll be prompted to set the password for the administrative account.
Enter a secure password and click on the
Change your password button when you are finished.
You will be redirected to the login page:
The default administrative account username is
root. Later in this tutorial, we will show you how to change the username.
- Username: root
- Password: [the password you have set]
Once you enter the login credentials and click the
Sign in button you will taken to the GitLab Welcome page.
2. Editing User profile
The first thing you will want to do is to edit your user profile. Click on the user avatar (upper-right corner) and from the drop-down menu, select
Here you can change your Name, Email, and other profile information and settings. Make the changes according to your liking.
Once you are done click on the
Update Profile settings button and shortly you will receive a confirmation email to the address you provided. To confirm your account follow the instructions provided in the email.
3. Changing Username
To access the Profile page, click on the
Account link from the left-hand vertical navigation menu.
As you already know the default username of the first administrative account is
root. To change it just type your new username and click on the
Update username button.
On this screen, you can also enable two-factor authentication.
The next time you will log in to your GitLab dashboard you will need to enter the new username.
4. Adding SSH Key
To be able to push your local git changes to the GitLab server you to add your SSH public key to your GitLab account.
If you already have an SSH key pair created on your local system you can display the public key by typing:
The output should look something like the following:
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQDd/mnMzHwjUzK8g3ldfsfRpJuC16mhWamaXRk8ySQrD/dzpbRLfDnZsLxCzRoq+ZzFHGwcQlJergtergdHGRrO8FE5jl3IWRRp+mP12qYw== email@example.com
In case the command above prints
No such file or directory it means that you do not have an SSH key pair generated on your machine.
To generate a new SSH key pair use the following command:
ssh-keygen -t rsa -b 4096 -C "firstname.lastname@example.org"
Copy the output from the cat command and go back to the GitLab’s web interface. Click
SSH Keys from the left-hand vertical navigation menu to access the SSH Keys configuration page.
Key textarea paste the public key you previously copied from your local machine, set a descriptive title and click on the
Add key button:
Now you should be able to push and pull your project changes from your local computer without having to provide your GitLab account credentials.
This tutorial walked you through the installation and configuration of GitLab on Ubuntu 18.04. You also learned how to edit your profile settings, how to change the username and add an SSH key. You can now create your first project and start using your GitLab.
If you have questions, feel free to leave a comment below.