GitLab on Debian 11: Install and Tweak it the Right Way
If you’re looking to spin up your own source‑control hub on a fresh Debian 11 box, this is the walk‑through that gets GitLab running without the usual “it works on my machine” headaches.
What You’ll Get Out of This
You’ll learn how to add the official repo, install GitLab CE, run the first‑time configuration, and tweak the settings so your instance feels like home. We’ll flag common snags (like missing packages or low RAM) before they bite you.
Why Debian 11 is a Good Match for GitLab
Debian’s stable releases are rock solid; GitLab’s own docs say “Debian 10 or newer” and give specific instructions for 11. That means all the dependencies (curl, ca‑certificates, etc.) come pre‑packaged, so you can skip the hunt for missing libraries.
Pre‑flight Checklist
Before you start, make sure:
1. Root access – You’ll need sudo or a real root shell.
2. Enough RAM – 4 GB is the bare minimum; if your box has less, GitLab will run in “low‑memory mode” and will be sluggish.
3. Swap space – The installer warns you if there’s no swap; add a 1–2 GB swapfile if needed.
4. Enough disk – A fresh install takes about 300 MB for the package, plus at least 5 GB of free space for repositories and logs.
5. Network – If your server sits behind a firewall, open port 80/443 (or whatever external_url you pick).
Add the Official GitLab Repository
# Install prerequisites sudo apt-get update && sudo apt-get install -y curl ca-certificates gnupg # Import the official GPG key curl https://packages.gitlab.com/gpg.key | sudo gpg --dearmor > /usr/share/keyrings/gitlab-archive-keyring.gpg # Add GitLab’s repository to APT sources echo "deb [signed-by=/usr/share/keyrings/gitlab-archive-keyring.gpg] https://packages.gitlab.com/runner/gitlab-ce/debian/ $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/gitlab.list # Refresh package list sudo apt-get update
Why each step? The key is to let APT verify the packages; otherwise you’ll get “UNTRUSTED” warnings. Adding the repo gives you the latest gitlab-ce build that’s tuned for Debian.
Install GitLab CE
sudo apt-get install gitlab-ce
During installation, a prompt will ask for an external_url. If you’re just testing locally, use:
http://localhost
If you’re exposing it to the world, set your domain (e.g., https://git.example.com). The installer writes this into /etc/gitlab/gitlab.rb and then runs gitlab-ctl reconfigure.
Initial Configuration
After the install finishes, GitLab will start automatically. Open a browser to the URL you set; you’ll be greeted with a login screen.
First‑time admin user: The default password is “admin.” Change it immediately:
sudo gitlab-rake "gitlab:password:reset"
You’ll be prompted for the new password – pick something that won’t make your mother cringe.
Fine‑tuning gitlab.rb
Edit /etc/gitlab/gitlab.rb to tailor the instance. Common tweaks:
| Setting | Why it matters |
|---|---|
| external_url "https://git.example.com" | Points GitLab at a proper FQDN; also forces HTTPS if you install LetsEncrypt later. |
| gitlab_rails['time_zone'] = 'America/New_York' | Keeps logs in your local time instead of UTC. |
| postgresql['shared_buffers'] = "256MB" | Gives PostgreSQL more memory on a 4 GB machine; adjust if you’re low on RAM. |
| gitlab_rails['git_timeout'] = 300 | Extends timeout for large pushes or clones that can time out on slow networks. |
After editing, run:
sudo gitlab-ctl reconfigure
That rebuilds the config and restarts services. If anything goes sideways, check /var/log/gitlab/gitlab-rails/production.log – it’s usually a dead‑end error or missing library.
Common Pitfalls and Fixes
- “Package ‘gitlab-ce’ is not available”
Check you added the repo correctly. Run apt-cache policy gitlab-ce. If it shows no candidate, re‑add the source line; copy it from the GitLab docs if needed.
- Low memory errors during reconfigure
The installer will dump “Could not allocate enough memory.” Add swap or bump RAM. A quick swapfile:
sudo fallocate -l 2G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile && sudo swapon /swapfile
- Port 80/443 blocked
On a cloud VM, you might need to adjust security groups or firewall rules. sudo ufw allow http and sudo ufw allow https do the trick if UFW is enabled.
Keep It Running
GitLab’s services are managed by gitlab-ctl. Everyday tasks:
# Check status sudo gitlab-ctl status # Restart a single service (e.g., nginx) sudo gitlab-ctl restart nginx # View logs for a specific component sudo gitlab-ctl tail web
If you’re on the edge of memory, consider enabling gitlab_rails['postgresql']['shared_buffers'] and redis['maxmemory_policy'] = 'allkeys-lru'.
Gotchas from the Trenches
I’ve seen folks run into a weird “certificate verification failed” when installing on a corporate network with a custom CA. The fix? Import your internal CA to /etc/ssl/certs/ca-certificates.crt or add curl --cacert /path/to/ca.pem to the install script.
Another one: after an accidental reboot, some users found that GitLab stuck in “maintenance mode.” Run sudo gitlab-ctl stop && sudo gitlab-ctl start – the web UI will re‑enable automatically once services come back up.
Wrap‑up (No “in conclusion” here)
You now have a working GitLab on Debian 11, ready to host projects or act as your internal CI hub. Tweaking gitlab.rb, monitoring logs, and keeping the server healthy will keep those merge requests flowing smoothly.
That’s all folks! Happy coding, and may your repositories stay clean.
