How to Install GitLab on Ubuntu Server: Step-by-Step Guide

 

Introduction

GitLab is a web-based platform that provides a comprehensive set of tools for the entire software development lifecycle. It serves as a centralized hub for managing repositories, integrating tools, features for DevOps, project planning, code review, CI/CD pipelines deployment, issue tracking, security and monitoring.

GitLab offers flexibility in being hosted on the user’s infrastructure, providing more control and ownership of the data and environment. GitLab is an open-source application and offers a free version suitable for small and personal projects, and a premium plan is also available for advanced features. If you are looking to install GitLab on Ubuntu, this step-by-step guide walks you through the process from start to finish. In this tutorial, we'll cover the complete GitLab installation on Ubuntu Server using the official package. At the end, you have a fully functional Ubuntu GitLab setup ready for your projects.

System Requirements for GitLab Community Edition on Ubuntu

•   UbuntuServer 25.04 LTS

•   Minimum RAM 8 GB, Maximum for Better performance

•   Storage 100 GB, storage requirement depends on your organization's team strength and workload

•   Root User or non-root user with sudo Privileges

Step 1 - Installation of Dependencies before GitLab Installation

Dependencies are packages, modules or libraries installed to help the program run smoothly and efficiently. Sometimes dependencies are not installed automatically; these dependencies are essential before installing the actual program. We will install the dependencies using the Ubuntu default package repository.

Refresh the local package stack with this command

#sudo apt update

Now run the following command to install the dependencies for GitLab installation. Some of the dependencies may already be installed, but this command will install the remaining ones.

#sudo apt install ca-certificates curl openssh-server perl postfix

During the dependencies installation, it prompts for Postfix to select the mail server configuration. Select it according to your environment's needs and requirements.

Next, it will prompt for the mail name, same is the case. Select it according to your environment requirements and needs. If you have a mail server in your environment, then configure it properly as per your environment.

After selecting this, your dependencies installation is complete.

Step 2 - GitLab Installation

After dependencies installation next step is to install GitLab on the system. Now download the GitLab script for installation on your system. Just go to the directory where you want to download this script with the cd command.

#cd /opt

Now download the GitLab installation script to this directory with this command.

After downloading the script, it's time to run the script with this command. Sometimes this script throws an error OS is not supported, or not added to packagecloud.io. So, to remove this error, use these options as shown below in the command.

#sudo os=Ubuntu dist=trusty bash script.deb.sh

Basically, this script sets up the environment for GitLab on your system by checking the required dependencies and libraries before the installation of GitLab. As you can see from the final message, the repository is set up. Now follow the command to install GitLab on the system.

#sudo apt install gitlab-ce

You will see the message on this screen. Thanks for installing GitLab!

Step 3 - GitLab Configuration

Update the configuration file for application settings according to your environment and reconfigure it. Open the GitLab configuration file with your favorite editor. Nano is used here.

#sudo nano /etc/gitlab/gitlab.rb

Now search for the external_url line and change it according to your domain name and change the http to https to redirect the users automatically to the site protected by the Let’s encrypt certificate.

Next search for letsencrypt[ ‘contact_emails’] settings and provide the email address accordingly to be informed about any issues.  To enable this setting, remove the # at the start and write the email address.

Save the changes, press CTRL + X, then Y and enter. After making these changes in settings, run the reconfigure command.

#sudo gitlab-ctl reconfigure

This will reconfigure the GitLab with your provided information about external_url and contact_mail. After this you didn’t answer anything; this will complete it automatically with the given information.

Step 4 - Firewall Rule Adjustment for GitLab

If you have configured a firewall to manage web traffic, then you must allow some ports to allow traffic of these ports. It is optional in case of test environment, but for the production environment, it is necessary.

Verify the status of your firewall by this command

#sudo ufw status

The firewall is active and now you can allow traffic of HTTP, HTTPS and OpenSSH on the firewall by following this.

#sudo ufw allow http

#sudo ufw allow https

#sudo ufw allow openssh

After allowing the rules, check the status of the firewall by the command

#sudo ufw status

Now your web traffic will not be blocked by the firewall.

Step 5 - Post-Install Tuning for GitLab on Ubuntu Server

The installation of GitLab and basic configuration is just the beginning. After installation, the next step is to optimize the performance, security, and reliability of your GitLab instance. Here are some fundamental post-installation activities that every administrator should consider.

Optimize System Performance

Optimizing resource allocation will help to avoid slow performance issues. 

Optimally configuring Puma workers involves setting them based on the number of CPU cores available. While increasing workers will improve multitasking abilities, it will also consume more memory.

Lastly, Sidekiq manages background processes like Continuous Integration/ Continuous Delivery (CI/CD). Set the jobs to run simultaneously based on the CPU and memory on your system.

Puma (Web Server)

Puma handles web requests (UI, API).

Settings are in /etc/gitlab/gitlab.rb as shown above.

How to choose values for Puma:

CPU-bound → workers = ~half to 2/3 of CPU cores.

Example:

4 cores → worker_processes = 2

8 cores → worker_processes = 4

Threads: usually 4 is stable. If you have more RAM, you can raise to 5–6. 

Rule of thumb: workers × threads = total concurrency.

Each worker = ~250MB RAM usage.

You can set the Puma values as per the available resources on your system.

Sidekiq (Background Jobs)

Sidekiq handles background jobs: CI pipelines, emails, and repo updates.

Settings in /etc/gitlab/gitlab.rb as shown below

sidekiq['concurrency'] = x

How to choose values for Sidekiq:

Memory is key: each job ~100MB.

Small server (4GB RAM) → concurrency = 5

Medium server (8GB RAM) → concurrency = 10

Large server (16GB+) → concurrency = 20

GitLab docs suggest:

4GB RAM = 5 concurrency

8GB RAM = 10 concurrency

16GB RAM = 25 concurrency

Reconfigure GitLab after changes:

sudo gitlab-ctl reconfigure

sudo gitlab-rake gitlab:env:info

Configure Email Notifications

Email is critical for account verification, password resets, and project updates.

Edit GitLab’s SMTP settings in /etc/gitlab/gitlab.rb. Example for Gmail:gitlab_rails['smtp_enable'] = true

gitlab_rails['smtp_address'] = "smtp.gmail.com"

gitlab_rails['smtp_port'] = 587

gitlab_rails['smtp_user_name'] = "your-email@gmail.com"

gitlab_rails['smtp_password'] = "your-app-password"

gitlab_rails['smtp_domain'] = "gmail.com"

gitlab_rails['smtp_authentication'] = "login"

gitlab_rails['smtp_enable_starttls_auto'] = true

Reconfigure GitLab and test by sending a test email.

How to Take Backup and Restore in GitLab

In case of failure, or during migration, you’d want to recover quickly. GitLab has an inbuilt backup tool to help you do that. This tool will let you back up your repositories, database and config files.

The backup files are saved in /var/opt/gitlab/backups

The filename looks like

This includes repositories, uploads, builds, artifacts, and more.

Backup Configuration Files

Repositories and database backups aren’t enough — you also need config and SSL certificates:

#sudo cp -a /etc/gitlab /var/opt/gitlab/backups/gitlab_config_backup

#sudo cp -a /etc/gitlab/gitlab-secrets.json /var/opt/gitlab/backups/

Store these along with your regular backups.

Schedule Automatic Backups

To automate backups, set up a cron job.Open the cron editor:

#sudo crontab -e

Add a job for daily backups at 2 AM:

0 2 * * * /opt/gitlab/bin/gitlab-rake gitlab:backup:create CRON=1

This ensures your GitLab instance is always backed up without manual effort.

How to Restore from a Backup

If you need to recover GitLab:

Stop GitLab:

#sudo gitlab-ctl stop unicorn

#sudo gitlab-ctl stop sidekiq

Restore using the backup timestamp:

Restart GitLab:

#sudo gitlab-ctl restart

Best Practices

·         Store backups on remote storage (AWS S3, external disk, or another server).

·         Test restores regularly to ensure backups actually work.

·         Encrypt sensitive backups for security.

·         Rotate old backups to save disk space.

Step 6 - Web Interface of GitLab and Initial Configuration

As the initial configuration is done and GitLab is ready to get its web interface.

First Login 

To access the interface, type the URL of GitLab in your browser as http://gitlab.seeklinux or the IP address of this host.

At first login, it will ask to set a new password as shown below.

Provide the new password and press the Change Your Password button, then a login screen will appear like this.

Just enter the username as root and provide the newly created password, and press sign in. As you can see below, we have successfully signed in to GitLab.

Now you can manage your GitLab instance.

Edit Profile

After the first login, you can edit your profile and set things accordingly. As shown below.

You can update your profile picture, change your password, set your emails, and manage your account.

Password Settings

Here you can change the password.

Change Name and Enable Two-Factor Authentication

Go to user settings, then Account, where you can change the user name and enable two-factor authentication to increase the account’s security. After changing the name, remember to log in with the new name.

All User Settings

This is the list of all user settings that can be changed according to need and requirement.

Step 7 - How to Start, Stop and Check the Status of GitLab

To start the GitLab service command is 

#sudo gitlab-ctl start

To check the status of whether GitLab is running or stopped command is 

#sudo gitlab-ctl status

To stop the GitLab service, the command is

#sudo gitlab-ctl stop

Step 8 - Monitoring and Logs in GitLab

After setting up and configuring the backups in GitLab, the next important step is to monitor your instance and manage the logs effectively. Monitoring helps you track performance, while logs provide insights into issues and errors that may affect your GitLab services.

Monitoring GitLab Services

GitLab provides a built-in command to check the health of all services:

sudo gitlab-ctl status service-name

This will show you the status of essential components such as Puma, Sidekiq, PostgreSQL, Redis, and Nginx.

To restart a specific service:

#sudo gitlab-ctl restart <service-name>

#sudo gitlab-ctl restart sidekiq, and to restart all services

#sudo gitlab-ctl restart

GitLab Logs Location

All logs are stored under:

/var/log/gitlab/

Each service has its own log file. Some important ones include:

Puma (Web server logs)

/var/log/gitlab/puma/puma_stdout.log

Useful for debugging web-related issues and performance problems.

Sidekiq (Background jobs)

/var/log/gitlab/sidekiq/current

Check here if jobs like emails, webhooks, or CI/CD pipelines fail.

PostgreSQL (Database)

/var/log/gitlab/postgresql/current

Contains queries and errors related to GitLab’s database.

GitLab Rails Logs

/var/log/gitlab/gitlab-rails/

application.log: Application-level errors and warnings.

production.log: Detailed user activity and issues.

sidekiq.log: Sidekiq job processing details.

GitLab Shell Logs

/var/log/gitlab/gitlab-shell/gitlab-shell.log

Helps debug SSH and Git repository access issues.

Real-Time Log Monitoring

To watch logs in real-time:

#sudo tail -f /var/log/gitlab/gitlab-rails/production.log

Or for Sidekiq background jobs:

#sudo tail -f /var/log/gitlab/sidekiq/current

Using GitLab Built-in Tools

GitLab provides commands for log inspection:

View recent logs (all services):

#sudo gitlab-ctl tail

Tail specific service logs:

sudo gitlab-ctl tail sidekiq

Get detailed system information:

sudo gitlab-rake gitlab:env:info

Check for background job queue:

sudo gitlab-rake gitlab:sidekiq:check

This helps quickly spot errors as they occur.

Integration with External Monitoring

For advanced monitoring, you can integrate GitLab with:

• Prometheus (built-in with GitLab Omnibus package) for metrics such as CPU, memory, and response times.
• Grafana dashboards to visualize Prometheus metrics.
• Systemd Journal (journalctl -u gitlab-runsvdir.service) for deeper system-level logging.
• ELK Stack (Elasticsearch, Logstash, Kibana) for centralized log management in large deployments.

Best Practices for Monitoring & Logs

·    Regularly rotate logs to avoid storage issues (/etc/logrotate.d/gitlab).

·     Monitor CPU, Memory, and Disk usage with tools like htop and df -h.

·     Set up alerts for service downtime or high load.

·      Review logs weekly to identify patterns of errors before they become critical.

Conclusion

This step-by-step guide about GitLab installation and configuration helps you to set it up in your test or production environment. You can go into user settings one by one and change them, and customize them as per your requirement. This guide helps you to set up a GitLab Server to manage your GitLab repositories, streamline code collaboration and implement CI/CD workflows.

keep visiting seeklinux for more updates and information.