How to Setup GitLab on Ubuntu: A Step-by-Step Guide

For software developers and teams looking for a robust version control system and CI/CD platform, GitLab offers an all-in-one solution. Setting up a GitLab server can seem daunting, but with the right guidance, you can have your instance running on an Ubuntu server in no time. This guide will walk you through the necessary steps to get your GitLab server up and running.

Key Takeaways

  • Ensure your Ubuntu server meets the system requirements before starting the installation process.
  • Update and upgrade your system packages to avoid compatibility issues.
  • Configure GitLab with a static hostname and set up necessary dependencies.
  • Secure your GitLab instance by setting up HTTPS using Let’s Encrypt.
  • Regularly maintain your GitLab server by updating, backing up data, and monitoring performance.

Preparing Your Ubuntu Server

System Requirements

Before you begin, ensure your server meets the following system requirements:

  • Ubuntu 18.04 or later
  • Minimum 4GB of RAM (8GB recommended for better performance)
  • At least 20GB of disk space
  • Root privileges or a user with sudo permissions

Updating and Upgrading Packages

First, update your system’s package list and upgrade the installed packages to their latest versions. This ensures you have the latest security updates and software improvements.

Run the following commands:

sudo apt update
sudo apt upgrade -y

Setting Up a Static Hostname

A static hostname is crucial for your GitLab server to ensure consistent network identification. To set a static hostname, use the hostnamectl command:

sudo hostnamectl set-hostname

Replace with your desired hostname. Verify the change with:


Note: A static hostname helps in avoiding potential network issues and ensures your server is easily identifiable on the network.

Installing GitLab Dependencies

person setting up GitLab on Ubuntu with a laptop, coding environment, and software installation process

Before you can install GitLab, you need to ensure that your system has all the necessary dependencies. This involves installing several required packages, adding the GitLab repository, and finally installing the dependencies.

Required Packages

First, update your system’s package list and upgrade any existing packages to their latest versions:

sudo apt update
sudo apt upgrade -y

Next, install the essential packages that GitLab needs to function correctly. These include curl, openssh-server, ca-certificates, and postfix:

sudo apt install -y curl openssh-server ca-certificates postfix

Adding GitLab Repository

With the dependencies in place, you can now add the GitLab repository to your system. 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

Run the script to add the GitLab repository:

sudo bash

Installing Dependencies

Now that the repository is added, you can install the GitLab dependencies. Run the following command to install them:

sudo apt install -y gitlab-ce

Note: Ensure your server meets the minimum hardware requirements for optimal performance. GitLab recommends at least 4GB of RAM and 4 CPU cores.

Downloading and Installing GitLab

Downloading GitLab

Now that you have the dependencies installed, you’re ready to install GitLab. First, move into the /tmp directory:

cd /tmp

Then download the installation script:

curl -LO

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/

Running the Installer

Once you are satisfied with the safety of the script, run the installer:

sudo bash /tmp/

This process leverages an installation script to configure your system with the GitLab repositories. Make sure your system package database is up to date before continuing.

Verifying Installation

After running the installer, install GitLab CE (Community Edition) with the following command:

sudo apt install gitlab-ce -y

The command will download and install the GitLab CE package. When the installation is complete, you will see the results as below.

It’s crucial to verify the installation to ensure everything is set up correctly. This will help avoid issues later on.

Next, we should configure the URL that will be used to access our GitLab server. We will be using a domain named for the GitLab access URL and will enable the HTTPS on it.

To change the GitLab URL access, edit the /etc/gitlab/gitlab.rb file.

Configuring GitLab for First Use

Once GitLab is installed, it’s time to configure it for first use. This involves editing configuration files, setting up the external URL, and configuring the email service to ensure smooth operation.

Setting Up HTTPS with Let’s Encrypt

Generating SSL Certificates

To secure your GitLab instance with HTTPS, you’ll need to generate SSL certificates using Let’s Encrypt. First, install the Let’s Encrypt tool:

sudo apt install letsencrypt -y

After the installation, run the following command to generate the certificates:

sudo letsencrypt certonly --standalone --agree-tos --no-eff-email --email [email protected] -d

The generated SSL certificates will be located in the /etc/letsencrypt/ directory.

Configuring GitLab for HTTPS

Once you have your SSL certificates, you need to configure GitLab to use them. Open the GitLab configuration file located at /etc/gitlab/gitlab.rb and set the external URL to use HTTPS:

external_url ''

Next, specify the paths to your SSL certificate and key:

gitlab_rails['gitlab_ssl_certificate'] = "/etc/letsencrypt/live/"
gitlab_rails['gitlab_ssl_certificate_key'] = "/etc/letsencrypt/live/"

Reconfigure GitLab to apply the changes:

sudo gitlab-ctl reconfigure

Testing HTTPS Setup

After configuring GitLab for HTTPS, it’s crucial to test the setup to ensure everything is working correctly. Open a web browser and navigate to your GitLab instance using the HTTPS URL:

You should see the GitLab login page without any SSL certificate warnings. If you encounter any issues, check the GitLab logs for more information.

Note: GitLab Premium users have access to additional features and support for HTTPS configuration. Make sure to consult the official documentation for more advanced setups.

Configuring the Firewall

To ensure your GitLab instance is secure and accessible, configuring the firewall is a crucial step. This section will guide you through installing UFW, allowing necessary ports, and enabling and checking UFW status.

Post-Installation Steps

Creating a Root Password

After installing GitLab, the first thing you should do is create a new root password. This ensures that your GitLab instance is secure from unauthorized access. Make sure to choose a strong, unique password and store it in a safe place.

Updating User Profile

Next, update your user profile to include relevant information such as your name, email address, and any other pertinent details. This helps in identifying commits and other activities within GitLab.

Adding SSH Keys

To streamline your workflow, add your SSH keys to GitLab. This allows you to clone repositories and push changes without needing to enter your username and password each time. Follow these steps to add your SSH key:

  1. Generate an SSH key if you don’t already have one.
  2. Copy the public key to your clipboard.
  3. Navigate to your GitLab profile settings.
  4. Paste the public key into the SSH keys section and save.

Taking these post-installation steps will help you get the most out of your GitLab setup and ensure a smooth, secure experience.

Managing GitLab Services

Managing GitLab services is crucial for ensuring that your repository manager runs smoothly and efficiently. This section will guide you through the essential tasks of starting, checking, and restarting GitLab services.

Troubleshooting Common Issues

When setting up GitLab on Ubuntu, you might encounter some common issues. This section provides a step-by-step guide to help you resolve them effectively.

Optimizing GitLab Performance

GitLab, an open-source platform, provides a robust and feature-rich solution for managing repositories, issues, CI/CD pipelines, and much more. If you’re an Ubuntu 22.04 user and want to set up your own GitLab instance to streamline your DevOps workflow, you’re in the right place.

Adjusting Unicorn Workers

Configuring GitLab Caching

Monitoring Performance Metrics

GitLab performance optimization is crucial for ensuring efficient operations and maximizing productivity. By adjusting the number of Unicorn workers, configuring caching settings, and monitoring performance metrics, you can enhance the overall performance of your GitLab instance. These optimizations help in handling increased user loads and maintaining a smooth user experience. Additionally, regular monitoring and fine-tuning of performance metrics ensure that your GitLab environment operates at its peak efficiency.

Regular Maintenance Tasks

Regular maintenance is crucial to ensure your GitLab instance runs smoothly and efficiently. This section covers the essential tasks you should perform regularly to keep your system in top shape.

Updating GitLab

Keeping GitLab up-to-date is vital for security and performance. Regular updates ensure you have the latest features and bug fixes. To update GitLab, follow these steps:

  1. Backup your data: Always start by backing up your GitLab data to avoid any loss during the update process.
  2. Check for updates: Use the command sudo apt-get update to check for available updates.
  3. Install updates: Run sudo apt-get upgrade gitlab-ee to install the latest version.
  4. Restart GitLab: After updating, restart GitLab using sudo gitlab-ctl restart.

Backing Up GitLab Data

Regular backups are essential to prevent data loss. GitLab provides built-in tools to help you back up your data efficiently. Here’s how to do it:

  1. Create a backup: Use the command sudo gitlab-rake gitlab:backup:create to create a backup of your GitLab instance.
  2. Store backups securely: Ensure your backups are stored in a secure location, preferably offsite or in a cloud storage service.
  3. Automate backups: Set up a cron job to automate the backup process, ensuring you always have a recent backup available.

Cleaning Up Logs and Temporary Files

Over time, logs and temporary files can accumulate and consume significant disk space. Regular cleanup helps maintain optimal performance. Follow these steps:

  1. Identify large files: Use the command sudo du -sh /var/log/gitlab/* to identify large log files.
  2. Delete old logs: Remove old log files using sudo rm /var/log/gitlab/*.log.
  3. Clear temporary files: Clean up temporary files with sudo gitlab-rake gitlab:cleanup:tmp.

Note: Regular maintenance tasks like these help ensure your GitLab instance remains reliable and efficient. Neglecting these tasks can lead to performance issues and potential data loss.

By following these steps, you can keep your GitLab instance running smoothly and avoid common issues that arise from neglecting regular maintenance.


Setting up GitLab on an Ubuntu server might seem like a complex task, but with this step-by-step guide, you should now have a fully functional GitLab instance up and running. From updating your repository and installing dependencies to configuring HTTPS and setting up your firewall, each step is crucial for a smooth installation. Now that your GitLab server is operational, you can dive into its myriad features to enhance your development workflow. Should you encounter any issues or have questions, feel free to reach out in the comments section. Happy coding!

Frequently Asked Questions

What are the system requirements for installing GitLab on Ubuntu?

To install GitLab on Ubuntu, you need a server with at least 2 GB of RAM, 2 vCPUs, and internet connectivity. A static hostname and a sudo user with admin rights are also required.

How do I update and upgrade packages on my Ubuntu server?

You can update and upgrade packages by running the commands: `sudo apt-get update` and `sudo apt-get upgrade` in the terminal.

How can I set up a static hostname for my Ubuntu server?

You can set up a static hostname by editing the `/etc/hostname` and `/etc/hosts` files with your desired hostname and then rebooting the server.

What dependencies are required for installing GitLab?

Dependencies include packages like `curl`, `openssh-server`, `ca-certificates`, and `postfix`. These can be installed using the command: `sudo apt-get install -y curl openssh-server ca-certificates postfix`.

How do I configure GitLab to use HTTPS with Let’s Encrypt?

You can configure HTTPS by generating SSL certificates using Let’s Encrypt and then editing the GitLab configuration file to include the SSL certificate paths. Finally, reconfigure GitLab using `sudo gitlab-ctl reconfigure`.

How can I manage GitLab services?

You can manage GitLab services using commands like `sudo gitlab-ctl start`, `sudo gitlab-ctl stop`, and `sudo gitlab-ctl restart` to start, stop, and restart GitLab services, respectively.

What should I do if I encounter SSL certificate issues?

If you encounter SSL certificate issues, verify that the certificate paths are correctly specified in the GitLab configuration file and that the certificates are not expired. Re-run `sudo gitlab-ctl reconfigure` to apply changes.

How do I back up GitLab data?

You can back up GitLab data using the built-in backup utility by running the command: `sudo gitlab-rake gitlab:backup:create`. This will create a backup file in the default backup directory.

You may also like...