Introduction
GitLab is an open-source application primarily used to host Git repositories, with additional development-related features like issue tracking. It is designed to be hosted using your own infrastructure, and provides flexibility in deploying as an internal repository store for your development team, a public way to interface with users, or a means for contributors to host their own projects.
The GitLab project enables you to create a GitLab instance on your own hardware with a minimal installation mechanism. In this guide, you will learn how to install and configure GitLab Community Edition on an Ubuntu 18.04 server.
Prerequisites
To follow along with this tutorial, you will need:
An Ubuntu 18.04 server with a non-root sudo user and basic firewall. To set this up, follow our Ubuntu 18.04 initial server setup guide.
The published GitLab hardware requirements recommend using a server with a minimum of:
4 cores for your CPU
4GB of RAM for memory
Although you may be able to get by with substituting some swap space for RAM, it is not recommended. The following examples in this guide will use these minimum resources.
A domain name pointed at your server. For more information, read our documentation on how to get started with DNS on DigitalOcean. This tutorial will use your_domain as an example, but be sure to replace this with your actual domain name.
Step 1 — Installing the Dependencies
Before installing GitLab, it is important to install the software that it leverages during installation and on an ongoing basis. The required software can be installed from Ubuntu’s default package repositories.
First, refresh the local package index:
sudo apt update
Then install the dependencies by entering this command:
sudo apt install ca-certificates curl openssh-server postfix tzdata perl
You will likely have some of this software installed already. For the postfix installation, select Internet Site when prompted. On the next screen, enter your server’s domain name to configure how the system will send mail.
Now that you have the dependencies installed, you’re ready to install GitLab.
Step 2 — Installing GitLab
With the dependencies in place, you can install GitLab. This process leverages an installation script to configure your system with the GitLab repositories.
First, move into the /tmp directory:
cd /tmp
Then download the installation script:
curl -LO https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh
Feel free to examine the downloaded script to ensure that you are comfortable with the actions it will take. You can also find a hosted version of the script on the GitLab installation instructions:
less /tmp/script.deb.sh
Once you are satisfied with the safety of the script, run the installer:
sudo bash /tmp/script.deb.sh
The script sets up your server to use the GitLab maintained repositories. This lets you manage GitLab with the same package management tools you use for your other system packages. Once this is complete, you can install the actual GitLab application with apt:
sudo apt install gitlab-ce
This installs the necessary components on your system and may take some time to complete.
Step 3 — Adjusting the Firewall Rules
Before you configure GitLab, you need to ensure that your firewall rules are permissive enough to allow web traffic. If you followed the guide linked in the prerequisites, you will already have a ufw firewall enabled.
View the current status of your active firewall by running:
sudo ufw status
Status: active
To Action From
-- ------ ----
OpenSSH ALLOW Anywhere
OpenSSH (v6) ALLOW Anywhere (v6)
The current rules allow SSH traffic through, but access to other services is restricted. Since GitLab is a web application, you need to allow HTTP access. Because you will be taking advantage of GitLab’s ability to request and enable a free TLS/SSL certificate from Let’s Encrypt, also allow HTTPS access.
The protocol to port mapping for HTTP and HTTPS are available in the /etc/services file, so you can allow that traffic in by name. If you didn’t already have OpenSSH traffic enabled, you should allow that traffic:
sudo ufw allow http
sudo ufw allow https
sudo ufw allow OpenSSH
You can check the ufw status again to ensure that you granted access to at least these two services:
sudo ufw status
Status: active
To Action From
-- ------ ----
OpenSSH ALLOW Anywhere
80/tcp ALLOW Anywhere
443/tcp ALLOW Anywhere
OpenSSH (v6) ALLOW Anywhere (v6)
80/tcp (v6) ALLOW Anywhere (v6)
443/tcp (v6) ALLOW Anywhere (v6)
This output indicates that the GitLab web interface is now accessible once you configure the application.
Step 4 — Editing the GitLab Configuration File
Before you can use the application, update the configuration file and run a reconfiguration command. First, open GitLab’s configuration file with your preferred text editor. This example uses nano:
sudo nano /etc/gitlab/gitlab.rb
Search for the external_url configuration line. Update it to match your domain and make sure to change http to https to automatically redirect users to the site protected by the Let’s Encrypt certificate:
/etc/gitlab/gitlab.rb
...
## 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
##!
##! Note: During installation/upgrades, the value of the environment variable
##! EXTERNAL_URL will be used to populate/replace this value.
##! On AWS EC2 instances, we also attempt to fetch the public hostname/IP
##! address from AWS. For more details, see:
##! https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instancedata-data-retrieval.html
external_url 'https://your_domain'
...
Next, find the letsencrypt['contact_emails'] setting. If you’re using nano, you can enable a search prompt by pressing CTRL+W. Write letsencrypt['contact_emails'] into the prompt, then press ENTER. This setting defines a list of email addresses that the Let’s Encrypt project can use to contact you if there are problems with your domain. It’s recommended to uncomment and fill this out to inform yourself of any issues that may occur:
/etc/gitlab/gitlab.rb
letsencrypt['contact_emails'] = ['sammy@example.com']
Once you’re done making changes, save and close the file. If you’re using nano, you can do this by pressing CTRL+X, then Y, then ENTER.
Run the following command to reconfigure GitLab:
sudo gitlab-ctl reconfigure
This will initialize GitLab using the information it can find about your server. This is a completely automated process, so you will not have to answer any prompts. The process will also configure a Let’s Encrypt certificate for your domain.
Step 5 — Performing Initial Configuration Through the Web Interface
With GitLab running, you can perform an initial configuration of the application through the web interface.
Logging In for the First Time
Visit the domain name of your GitLab server in your web browser:
https://your_domain
On your first visit, you’ll be greeted with a login page:
On your first visit, sign as ‘root’.
GitLab generates an initial secure password for you. It is stored in a folder that you can access as an administrative sudo user:
sudo nano /etc/gitlab/initial_root_password
/etc/gitlab/initial_root_password
# WARNING: This value is valid only in the following conditions
# 1. If provided manually (either via `GITLAB_ROOT_PASSWORD` environment variable or via `gitlab_rails['initial_root_password']` setting in `gitlab.rb`, it was provided before database was seeded for the firs$
# 2. Password hasn't been changed manually, either via UI or via command line.
#
# If the password shown here doesn't work, you must reset the admin password following https://docs.gitlab.com/ee/security/reset_user_password.html#reset-your-root-password.
Password: YOUR_PASSWORD
# NOTE: This file will be automatically deleted in the first reconfigure run after 24 hours.
Back on the login page, enter the following:
Username: root
Password: [the password listed on /etc/gitlab/initial_root_password]
Enter these values into the fields and click the Sign in button. You will be signed in to the application and taken to a landing page that prompts you to begin adding projects:
Your dashboard after logging in as ‘root’.
You can now fine tune your GitLab instance.
Updating Your Password
One of the first things you should do after logging in, is change your password. To make this change, click on the icon in the upper-right corner of the navigation bar and select Edit Profile:
Select ‘Edit Profile’ after clicking on the user icon.
You’ll then enter a User Settings page. On the left navigation bar, select Password to change your GitLab generated password, to a secure password, then click on the Save password button when you’re finished with your updates:
You’ll be taken back to the login screen with a notification that your password has been changed. Enter your new password to log back into your GitLab instance:
Enter your new password to log back into your GitLab instance.
Adjusting your Profile Settings
GitLab selects some reasonable defaults, but these are not usually appropriate once you start using the software.
To make the necessary modifications, click on the user icon in the upper-right corner of the navigation bar and select Edit Profile.
You can adjust the Name and Email address from “Administrator” and “admin@example.com” to something more accurate. The name you select will be displayed to other users, while the email will be used for default avatar detection, notifications, Git actions through the interface, and more:
Edit your ‘Full Name’ and ‘Email’.
Click on the Update Profile settings button at the bottom when you are finished with your updates. You’ll be prompted to enter your password to confirm changes.
A confirmation email will be sent to the address you provided. Follow the instructions in the email to confirm your account so that you can begin using it with GitLab.
Changing Your Account Name
Next, select Account in the left navigation bar:
Here, you can enable two-factor authentication and change your username. By default, the first administrative account is given the name root. Since this is a known account name, it is more secure to change this to a different name. You will still have administrative privileges; the only thing that will change is the name. Replace root with your preferred username:
Change the username from ‘root’ to something else.
Click on the Update username button to make the change. You’ll be prompted to confirm the change thereafter.
Next time you log into GitLab, remember to use your new username.
Adding an SSH Key to your Account
You can enable SSH keys with Git to interact with your GitLab projects. To do this, you need to add your SSH public key to your GitLab account.
In the left navigation bar, select SSH Keys:
You can enter your public SSH key here.
If you already have an SSH key pair created on your local computer, you can view the public key by typing:
cat ~/.ssh/id_rsa.pub
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDMuyMtMl6aWwqBCvQx7YXvZd7bCFVDsyln3yh5/8Pu23LW88VXfJgsBvhZZ9W0rPBGYyzE/TDzwwITvVQcKrwQrvQlYxTVbqZQDlmsC41HnwDfGFXg+QouZemQ2YgMeHfBzy+w26/gg480nC2PPNd0OG79+e7gFVrTL79JA/MyePBugvYqOAbl30h7M1a7EHP3IV5DQUQg4YUq49v4d3AvM0aia4EUowJs0P/j83nsZt8yiE2JEYR03kDgT/qziPK7LnVFqpFDSPC3MR3b8B354E9Af4C/JHgvglv2tsxOyvKupyZonbyr68CqSorO2rAwY/jWFEiArIaVuDiR9YM5 sammy@mydesktop
Copy this text and enter it into the Key text box inside your GitLab instance.
If, instead, you get a different message, you do not yet have an SSH key pair configured on your machine:
cat: /home/sammy/.ssh/id_rsa.pub: No such file or directory
If this is the case, you can create an SSH key pair by entering the following command:
ssh-keygen
Accept the defaults and optionally provide a password to secure the key locally:
Generating public/private rsa key pair.
Enter file in which to save the key (/home/sammy/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/sammy/.ssh/id_rsa.
Your public key has been saved in /home/sammy/.ssh/id_rsa.pub.
The key fingerprint is:
SHA256:I8v5/M5xOicZRZq/XRcSBNxTQV2BZszjlWaIHi5chc0 sammy@gitlab.docsthat.work
The key's randomart image is:
+---[RSA 2048]----+
| ..%o==B|
| *.E =.|
| . ++= B |
| ooo.o . |
| . S .o . .|
| . + .. . o|
| + .o.o ..|
| o .++o . |
| oo=+ |
+----[SHA256]-----+
Once you have this, you can display your public key as the previous example by entering this command:
cat ~/.ssh/id_rsa.pub
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDMuyMtMl6aWwqBCvQx7YXvZd7bCFVDsyln3yh5/8Pu23LW88VXfJgsBvhZZ9W0rPBGYyzE/TDzwwITvVQcKrwQrvQlYxTVbqZQDlmsC41HnwDfGFXg+QouZemQ2YgMeHfBzy+w26/gg480nC2PPNd0OG79+e7gFVrTL79JA/MyePBugvYqOAbl30h7M1a7EHP3IV5DQUQg4YUq49v4d3AvM0aia4EUowJs0P/j83nsZt8yiE2JEYR03kDgT/qziPK7LnVFqpFDSPC3MR3b8B354E9Af4C/JHgvglv2tsxOyvKupyZonbyr68CqSorO2rAwY/jWFEiArIaVuDiR9YM5 sammy@mydesktop
Insert this block of text in the output and enter it into the Key text box inside your GitLab instance. Give it a descriptive title, and click the Add key button.
Now you’re able to manage your GitLab projects and repositories from your local machine without having to provide your GitLab account credentials.
Step 6 — Restricting or Disabling Public Sign-ups
With your current setup, it is possible for anyone to sign up for an account when you visit your GitLab instance’s landing page. This may be what you want if you are seeking to host a public project. However, many times, more restrictive settings are desirable.
To begin, navigate to the administrative area by clicking on the hamburger menu in the top navigation bar and select Admin from the drop-down:
Select Settings from the left navigation bar:
Select ‘Settings’ from the left navigation bar.
You will be taken to the global settings for your GitLab instance. Here, you can adjust a number of settings that affect whether new users can sign up and their level of access.
Disabling Sign-ups
If you wish to disable sign-ups completely, scroll to the Sign-up Restrictions section and press Expand to view the options.
Then deselect the Sign-up enabled check box:
Remember to click on the Save changes button after making your changes.
The sign-up section is now removed from the GitLab landing page.
Restricting Sign-ups By Domain
If you are using GitLab as part of an organization that provides email addresses associated with a domain, you can restrict sign-ups by domain instead of completely disabling them.
In the Sign-up Restrictions section, select the Send confirmation email on sign-up box, which will allow users to log in only after they’ve confirmed their email.
Next, add your domain or domains to the Whitelisted domains for sign-ups box, one domain per line. You can use the asterisk “*” to specify wildcard domains:
Restrict sign-ups by domain.
When you’re finished, click on the Save changes button.
The sign-up section is now removed from the GitLab landing page.
Restricting Project Creation
By default, new users can create up to 10 projects. If you wish to allow new users from the outside for visibility and participation, but want to restrict their access to creating new projects, you can do so in the Account and Limit Settings section.
Inside, you can change the Default projects limit to 0 to completely disable new users from creating projects:
From the ‘Account and limit’ setting, you can set project limits to zero.
New users can still be added to projects manually and have access to internal or public projects created by other users.
After your updates, remember to click on the Save changes button.
New users will now be able to create accounts, but unable to create projects.
Renewing Let’s Encrypt Certificates
By default, GitLab has a scheduled task set up to renew Let’s Encrypt certificates after midnight every fourth day, with the exact minute based on your external_url. You can modify these settings in the /etc/gitlab/gitlab.rb file.
For example, if you wanted to renew every 7th day at 12:30, you can configure it to do so. First, navigate to the configuration file:
sudo nano /etc/gitlab/gitlab.rb
Then, find the following lines in the file and remove the # and update it with following:
/etc/gitlab/gitlab.rb
...
################################################################################
# Let's Encrypt integration
################################################################################
# letsencrypt['enable'] = nil
letsencrypt['contact_emails'] = ['sammy@digitalocean'] # This should be an array of email addresses to add as contacts
# letsencrypt['group'] = 'root'
# letsencrypt['key_size'] = 2048
# letsencrypt['owner'] = 'root'
# letsencrypt['wwwroot'] = '/var/opt/gitlab/nginx/www'
# See http://docs.gitlab.com/omnibus/settings/ssl.html#automatic-renewal for more on these settings
letsencrypt['auto_renew'] = true
letsencrypt['auto_renew_hour'] = "12"
letsencrypt['auto_renew_minute'] = "30"
letsencrypt['auto_renew_day_of_month'] = "*/7"
...
You can also disable auto-renewal by setting the letsencrypt['auto_renew'] to false:
/etc/gitlab/gitlab.rb
...
letsencrypt['auto_renew'] = false
...
With auto-renewals in place, you don’t need to worry about service interruptions.
Conclusion
You now have a working GitLab instance hosted on your own server. You can begin to import or create new projects and configure the appropriate level of access for a team. GitLab is regularly adding features and making updates to their platform, so be sure to check out the project’s home page to stay up-to-date on any improvements or important notices.
