Install GitLab on Debian 11 or 10: A Quick‑Start Guide
If you’re looking to host a self‑managed Git repository that feels as smooth as your favorite cloud service, installing GitLab on Debian is the way to go. Below I’ll walk through the whole process – from prepping the server to getting the first repo up and running – with real‑world tips that will save you from common hiccups.
Why You’re Here
You’ve got a fresh Debian 10 or 11 box, maybe a VPS, and you want GitLab on it. That’s what we’ll do: add the official package repository, install the omnibus package, tweak a few settings, and verify that the web UI is alive and kicking. No fluff, just the steps that work.
Prep Your System
5.1 Update and Upgrade
sudo apt update && sudo apt upgrade -y
Debian’s default packages are often old; updating ensures you don’t run into “missing dependency” errors later. If this command stalls, you might have a broken mirror – try apt‑dist-upgrade or switch to a faster server.
5.2 Install Required Packages
sudo apt install -y curl openssh-server ca-certificates tzdata perl
GitLab’s omnibus installer bundles many of its own dependencies, but it still relies on these basics for networking, SSL and timezone data.
Add the Official GitLab Repository
5.3 Grab the GPG Key
curl -fsSL https://packages.gitlab.com/gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/gitlab-archive-keyring.gpg
This key protects you from tampered packages. Skipping it will make apt complain about “NO_PUBKEY”.
5.4 Register the Repo
echo "deb [signed-by=/usr/share/keyrings/gitlab-archive-keyring.gpg] https://packages.gitlab.com/gitlab/gitlab-ce/debian/ $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/gitlab_gitlab-ce.list
Pointing to the correct codename (bullseye for Debian 11, buster for Debian 10) ensures you pull in the right binaries.
Install GitLab
5.5 Update Package List Again
sudo apt update
If this spits out “Failed to fetch …” again, double‑check your /etc/apt/sources.list.d/gitlab_gitlab-ce.list. A stray space or wrong codename will break it.
5.6 Install the Omnibus Package
sudo EXTERNAL_URL="http://your.domain.com" apt install -y gitlab-ce
Replace your.domain.com with your actual host. The EXTERNAL_URL environment variable tells GitLab what URL to use in its internal links.
The omnibus package is a self‑contained bundle that installs Ruby, Nginx, Postgres (if you opt for the bundled DB), and all the gems GitLab needs. It’s far easier than building from source unless you’re hacking on the core code.
5.7 Let GitLab Configure Itself
sudo gitlab-ctl reconfigure
This command pulls in configuration files, starts services, and runs database migrations. If it hangs or fails, check /var/log/gitlab/ for details – often a permission snag on the git user’s home is the culprit.
Post‑Installation Tweaks
5.8 Open the Firewall
sudo ufw allow http sudo ufw allow https
If you’re behind Cloudflare or using SSH tunnels, make sure port 22 remains open too.
5.9 Verify Everything’s Running
gitlab-ctl status
You should see nginx, postgresql (if bundled), redis, and others listed as running. If anything is stuck at “stopped”, run:
sudo gitlab-ctl restart <service>
Common Pitfalls I’ve Seen
- Bad driver updates on a laptop – One client tried to upgrade the GPU driver before installing GitLab; the resulting kernel panic killed the entire Debian install. Always keep your base system stable before adding heavy packages.
- Missing tzdata – Without it, GitLab complains “Timezone data not found” and won’t start Nginx. That’s why I install tzdata in step 5.1.
- Wrong codename – Mixing up buster and bullseye in the repo line is a quick way to trip your head. Double‑check with lsb_release -cs.
First Things You’ll Do
Open a web browser to http://your.domain.com. The GitLab welcome screen will prompt you for an admin password. Create it, log in, and then:
1. Change the default email domain in Admin Area => Settings => General.
2. Set up an SSH key under your profile so you can push without passwords.
3. Invite your teammates via the Users page.
Need More Power?
If you want to use PostgreSQL on a separate machine or tweak Ruby settings, edit /etc/gitlab/gitlab.rb. After any change, run gitlab-ctl reconfigure again.
That’s it—GitLab is up, running, and ready for your code. If anything goes sideways, just dig into the logs under /var/log/gitlab/; they usually point straight to the problem.
