GitLab, when self-managed, is less a single application and more a complex distributed system where the "installation" is just the first handshake.
Let’s see it in action. Imagine you’ve got a fresh Linux VM, say Ubuntu 22.04. You’re not just installing gitlab-ce; you’re setting up an entire stack. The GitLab package orchestrates this, but understanding the pieces is key.
First, you need a solid PostgreSQL database. GitLab relies heavily on it for storing project data, user information, and more. You’ll typically see it running on port 5432.
Then there’s Redis, used for caching and background job queues. This is crucial for keeping the UI snappy and ensuring that asynchronous tasks like CI/CD pipeline runs don’t block the main application. It usually hums along on port 6379.
The core GitLab application server itself, powered by Ruby on Rails, handles most of the web requests. This is what you interact with through your browser.
Nginx is the web server and reverse proxy that sits in front of the Rails application. It handles SSL termination, serves static assets, and forwards dynamic requests to the Rails process. You’ll configure its listening ports, typically 80 and 443.
Sidekiq is GitLab’s background job processor. It picks up tasks from Redis queues and executes them, freeing up the main Rails application to handle user requests.
Finally, there’s Gitaly, GitLab’s distributed Git RPC service. Instead of applications directly accessing Git repositories on disk, they talk to Gitaly, which then handles the Git operations. This is vital for scalability and performance, especially with large repositories or many users.
Here’s how you’d typically start with a fresh install on Ubuntu:
sudo apt update
sudo apt install -y curl openssh-server ca-certificates postfix
sudo curl -sS https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash
sudo EXTERNAL_URL="http://gitlab.example.com" apt install gitlab-ce
The EXTERNAL_URL is your first major configuration lever. It tells GitLab what hostname to use in all its generated links, API responses, and email notifications. Setting this correctly from the start prevents a world of pain later when links are broken.
After this initial install, you run sudo gitlab-ctl reconfigure. This command is the conductor. It reads your configuration files (primarily /etc/gitlab/gitlab.rb) and applies the necessary changes to all the components – PostgreSQL, Redis, Nginx, Sidekiq, etc. It ensures they are running, configured correctly, and can talk to each other.
The gitlab.rb file is your central nervous system. Let’s say you want to enable HTTPS. You’d edit /etc/gitlab/gitlab.rb like this:
external_url 'https://gitlab.example.com'
letsencrypt['enable'] = true
letsencrypt['contact_emails'] = ['admin@example.com']
Then, you run sudo gitlab-ctl reconfigure again. GitLab will automatically obtain a Let’s Encrypt certificate, configure Nginx to use it, and redirect HTTP traffic to HTTPS.
Consider tuning Sidekiq for performance. If your CI/CD is slow, you might increase the number of concurrent workers:
sidekiq['concurrency'] = 25
This tells Sidekiq to run up to 25 jobs simultaneously, rather than the default (which is often much lower, like 10). After sudo gitlab-ctl reconfigure, Sidekiq will restart with the new worker count.
The one thing many people overlook is the interaction between GitLab’s internal services and external network configurations. For instance, if you’re using an external PostgreSQL or Redis, you need to ensure gitlab.rb is configured to point to those external services, and that firewall rules on both the GitLab server and the external service hosts allow the necessary communication. For PostgreSQL, this means setting postgresql['enable'] = false and then specifying gitlab_rails['db_host'], gitlab_rails['db_port'], gitlab_rails['db_password'], etc.
Once you’ve got the basics running, you’ll likely be looking into integrating it with other tools, such as external authentication providers like LDAP or SAML, or setting up robust backups.