How to Set Up a GitLab Server on Debian 12 Bookworm

GitLab is a powerful, web-based DevOps lifecycle tool that provides a Git repository manager, CI/CD pipeline features, issue tracking, and more. Self-hosting GitLab gives you full control over your data and can be ideal for organizations that prioritize privacy, compliance, or internal customization.

In this guide, we will walk through the step-by-step process of setting up a GitLab server on a Debian 12 Bookworm system. This setup is intended for users with basic knowledge of the Linux command line and administrative privileges on a VPS, dedicated server, or virtual machine.

🧾 Prerequisites

Before diving in, ensure you have the following:

• A Debian 12 Bookworm system (either bare metal or virtualized).
• A non-root user with sudo privileges.
• At least 4GB of RAM (8GB+ recommended for production).
• At least 2 CPU cores.
• A fully qualified domain name (FQDN) pointed to your server’s public IP address.
• Root access or a user with full sudo permissions.
• An open HTTP (80) and HTTPS (443) port on the firewall.
• Optional but recommended: A valid SSL certificate, or use Let’s Encrypt via GitLab’s built-in integration.

🛠 Step 1: Update Your System

First, update your system to ensure all packages are current.

sudo apt update && sudo apt upgrade -y

Install some essential tools:

sudo apt install -y curl ca-certificates gnupg lsb-release

🔐 Step 2: Set the Hostname and DNS

Set your server’s hostname if you haven’t already:

sudo hostnamectl set-hostname gitlab.example.com

Ensure your domain (e.g., gitlab.example.com) points to your server’s public IP in DNS settings.

Edit /etc/hosts and add:

127.0.1.1 gitlab.example.com gitlab

Replace gitlab.example.com with your actual domain.

📦 Step 3: Install Dependencies

GitLab provides an official package for Debian. First, install required dependencies:

sudo apt install -y curl openssh-server tzdata perl

If you intend to use email notifications (recommended), also install Postfix or another MTA:

sudo apt install -y postfix

During the Postfix installation, choose Internet Site, then enter your domain name when prompted.

🔑 Step 4: Add the GitLab Repository

Import the GitLab package repository:

curl https://packages.gitlab.com/install/repositories/gitlab/gitlab-ee/script.deb.sh | sudo bash

⚠️ This installs the Enterprise Edition (EE), which includes both free and paid features. You can still use the free tier. If you want the Community Edition (CE), make adjustments accordingly.

📥 Step 5: Install GitLab

Install GitLab with the following command, replacing the URL with your domain:

sudo EXTERNAL_URL="https://gitlab.example.com" apt install gitlab-ee

This process may take several minutes depending on your server’s specs. It installs GitLab and configures Nginx, PostgreSQL, Redis, GitLab Workhorse, Sidekiq, and more.

🔧 Step 6: Configure GitLab

GitLab is configured via /etc/gitlab/gitlab.rb. After installation, you can edit this file to fine-tune settings.

Open it using your preferred editor:

sudo nano /etc/gitlab/gitlab.rb

Some settings you might want to configure:

• external_url: Make sure it reflects your actual domain.
• gitlab_rails['gitlab_email_from']: Set the email address used for outgoing mail.
• letsencrypt['enable']: Set to true if you want GitLab to handle SSL for you via Let’s Encrypt.

After making changes, reconfigure GitLab:

sudo gitlab-ctl reconfigure

This process may take a few minutes. It regenerates GitLab’s configuration and restarts necessary services.

🌐 Step 7: Access GitLab Web Interface

Once installed and configured, open a web browser and visit:

https://gitlab.example.com

On the first visit, you’ll be prompted to set a password for the root user.

If you missed this screen or want to reset the root password, run:

sudo gitlab-rake "gitlab:password:reset"

After setting the password, log in with:

• Username: root
• Password: The one you just set

From there, you can begin creating users, projects, groups, CI pipelines, and more.

🔐 Step 8: Enable HTTPS with Let’s Encrypt (Optional but Recommended)

If you didn’t configure SSL during installation, you can do so now using Let’s Encrypt.

Edit GitLab’s config file:

sudo nano /etc/gitlab/gitlab.rb

Ensure these lines are set:

external_url "https://gitlab.example.com"

letsencrypt['enable'] = true
letsencrypt['contact_emails'] = ['admin@example.com']  # Optional

Then reconfigure GitLab:

sudo gitlab-ctl reconfigure

This will automatically obtain and install a free SSL certificate from Let’s Encrypt.

📤 Step 9: Configure Email (Optional but Highly Recommended)

To enable email notifications (important for issues, password resets, etc.), edit the GitLab config file again:

sudo nano /etc/gitlab/gitlab.rb

Set the SMTP configuration:

gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = "smtp.mailgun.org"
gitlab_rails['smtp_port'] = 587
gitlab_rails['smtp_user_name'] = "postmaster@example.com"
gitlab_rails['smtp_password'] = "your_password"
gitlab_rails['smtp_domain'] = "example.com"
gitlab_rails['smtp_authentication'] = "login"
gitlab_rails['smtp_enable_starttls_auto'] = true

Replace values based on your SMTP provider. Then reconfigure GitLab again:

sudo gitlab-ctl reconfigure

📈 Step 10: Monitor and Manage GitLab

GitLab provides several useful commands to manage the server:

• Check service status:

  sudo gitlab-ctl status
  

• Restart all services:

  sudo gitlab-ctl restart
  

• Tail logs:

  sudo gitlab-ctl tail
  

• Run built-in health checks:

  sudo gitlab-rake gitlab:check SANITIZE=true
  

🧹 Maintenance and Backups

Backups are vital. GitLab allows you to configure automated or manual backups.

To create a manual backup:

sudo gitlab-backup create

By default, backups are stored in /var/opt/gitlab/backups/.

You can also schedule backups in /etc/gitlab/gitlab.rb:

gitlab_rails['backup_keep_time'] = 604800  # Keep backups for 7 days

Don’t forget to back up:

• /etc/gitlab/ – Configuration files
• /var/opt/gitlab/ – Application data
• /var/log/gitlab/ – Logs

For automation, consider using cron jobs and off-site storage solutions.

🚀 Post-Installation Tips

• Set up CI/CD Pipelines: GitLab has built-in CI/CD support with .gitlab-ci.yml.
• Integrate with Kubernetes: GitLab can manage clusters and deployments.
• Configure LDAP or SAML: For enterprise environments with centralized authentication.
• Use Runners: Deploy GitLab Runners on separate servers for scalable CI/CD.

🧩 Conclusion

Setting up a GitLab server on Debian 12 Bookworm is straightforward if you follow the correct steps. With a few commands and some configuration, you’ll have a powerful code collaboration and CI/CD platform up and running in no time.

Whether you’re a small team, an enterprise, or an open-source community, GitLab provides the flexibility and feature set to manage your development lifecycle securely and efficiently. Hosting your own GitLab instance also allows full control over your infrastructure, ensuring your data remains private and customizable.