GitLab Installation and Configuration Guide
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.
Prerequisites
If you are using Ubuntu version 16.04 or below, we recommend you upgrade to a more latest version since Ubuntu no longer provides support for these versions. This collection of guides will help you in upgrading your Ubuntu version.
To follow along with this tutorial, you will need:
- A server running Ubuntu, along with a non-root user with sudo privileges and an active firewall.
- 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.
- A domain name pointed at your server.
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.
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:
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. Once this is complete, install the GitLab application with apt:
sudo apt install gitlab-ce
Step 3 — Adjusting the Firewall Rules
Before you configure GitLab, ensure your firewall rules are permissive enough to allow web traffic.
View the current status of your active firewall by running:
sudo ufw status
Output:
Status: active
To ensure access for web services, allow HTTP and HTTPS traffic:
sudo ufw allow http
sudo ufw allow https
sudo ufw allow OpenSSH
Check the firewall status again:
sudo ufw status
Step 4 — Editing the GitLab Configuration File
Before using the application, update the configuration file and run a reconfiguration command. Open GitLab’s configuration file:
sudo nano /etc/gitlab/gitlab.rb
Find the external_url line and update it with your domain:
external_url 'https://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.
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. Sign in as root.
GitLab generates an initial secure password for you, stored in a file accessible as an administrative sudo user:
sudo nano /etc/gitlab/initial_root_password
Use the generated password to log in. After logging in, you’ll be taken to the GitLab dashboard.
One of the first tasks you should perform is updating your password. To do this:
- Click on the user icon in the upper-right corner and select Edit Profile.
- Navigate to Password in the left navigation bar.
- Update your password and click Save password.
After saving, you’ll be logged out and prompted to log back in with your new password.
Step 6 — Restricting or Disabling Public Sign-ups
By default, anyone can sign up for an account on your GitLab instance. To adjust these settings:
- Navigate to the Admin section by clicking the hamburger menu in the top navigation bar.
- Click on Settings in the left navigation bar.
Disabling Sign-ups
If you wish to disable sign-ups completely, go to the Sign-up Restrictions section and deselect the Sign-up enabled checkbox. Click Save changes.
Restricting Sign-ups by Domain
If your organization provides email addresses associated with a domain, you can restrict sign-ups to those domains:
- Select the Send confirmation email on sign-up checkbox.
- Add your domain(s) to the Whitelisted domains for sign-ups box, one per line. Use a wildcard (*) if needed.
Click Save changes when done.
Restricting Project Creation
By default, new users can create up to 10 projects. To restrict this:
- Go to Account and Limit Settings.
- Set the Default projects limit to 0 to prevent new users from creating projects.
Click Save changes after updating.
Renewing Let’s Encrypt Certificates
By default, GitLab renews Let’s Encrypt certificates after midnight every fourth day. To modify this schedule:
-
- Open the GitLab configuration file:
sudo nano /etc/gitlab/gitlab.rb
-
- Find and uncomment the following lines, then set your preferred renewal schedule:
letsencrypt['auto_renew'] = true
letsencrypt['auto_renew_hour'] = "12"
letsencrypt['auto_renew_minute'] = "30"
letsencrypt['auto_renew_day_of_month'] = "*/7"
- Save and close the file. Changes will take effect during the next renewal cycle.
To disable auto-renewal, set letsencrypt['auto_renew'] to false.
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 your team. GitLab regularly adds features and updates their platform, so be sure to check their project’s homepage for improvements and notices.
