How to Install GitLab on CentOS 8 Stream for Your Projects
Got a fresh CentOS 8 Stream box and want the full‑blown, self‑hosted GitLab you can run from your own rack? This guide shows you the exact steps I use in production, plus a few quick hacks if something goes wrong.
1. Prerequisites: What You’ll Need
- A clean CentOS 8 Stream installation (bare or minimal).
- Root privileges or sudo access.
- A static IP or at least a resolvable hostname; GitLab will complain if it can’t figure out its own name.
- 4 GB of RAM minimum, but the more the merrier—GitLab is memory hungry.
2. Disable SELinux and Configure the Firewall
GitLab’s omnibus packages don’t play well with the default SELinux policy on CentOS 8 Stream, so I turn it off for the install. If you’re a hardcore security fan, you can keep it enabled but be prepared to write a ton of custom policies.
# Temporarily set SELinux to permissive sudo setenforce 0 # Make the change permanent sudo sed -i 's/^SELINUX=enforcing/SELINUX=permissive/' /etc/sysconfig/selinux
Next, open the ports GitLab will use. If you’re running a firewall (which you should), add these rules:
sudo firewall-cmd --add-service=http --permanent sudo firewall-cmd --add-service=https --permanent sudo firewall-cmd --reload
3. Install the Dependencies That GitLab Needs
CentOS 8 Stream ships with dnf, but we’ll use it just like yum. The packages below cover networking, database, and Ruby runtime that GitLab’s internal services require.
sudo dnf install -y curl policycoreutils-python-utils openssh-server postfix
I’ve seen this exact line fail on a minimal install because postfix pulls in a lot of unnecessary dependencies. If you’re tight on space, swap it out for ssmtp or skip mail entirely (GitLab will still run).
4. Add the GitLab Repository and Install
The easiest way to get GitLab is via its official omnibus package. Just tell CentOS where to fetch it.
# Grab the install script curl -sS https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.rpm.sh | sudo bash
That script configures the repo and does a quick check that your system can reach the GitLab mirrors. Once you’re back at the prompt, spin up GitLab:
sudo dnf install -y gitlab-ce
During installation it will create /etc/gitlab/ and install all of GitLab’s binaries under /opt. The default config is fine for a test machine, but I always tweak these two lines right away:
sudo editor /etc/gitlab/gitlab.rb # Change the external URL to your hostname or IP: external_url 'https://gitlab.example.com'
5. Configure DNS and Restart
If you’re using a custom domain, make sure it points at the CentOS box. For a quick local test, just edit /etc/hosts:
127.0.0.1 gitlab.local
Now reconfigure GitLab so it reads your new settings and rebuilds its internal config.
sudo gitlab-ctl reconfigure
This command can take 5‑10 minutes the first time. While it runs, keep an eye on the output; any “ERROR” line is usually a missing dependency or mis‑set hostname.
6. Verify the Installation
Once gitlab-ctl reports “running,” you should be able to hit your server in a browser:
https://gitlab.local/
You’ll see the GitLab welcome screen and be prompted to set an admin password. If you get a 502 Bad Gateway, it’s usually because the app is still booting or the firewall blocked port 443—double‑check those settings.
7. Optional: Harden GitLab Post‑Install
If you’re going to keep this in production, consider:
- Switching SELinux back to enforcing and adding targeted policies (I’ve written a small guide on that elsewhere).
- Enabling automatic updates for the omnibus package via yum update.
- Setting up a regular backup with the built‑in rake tasks.
There you go—a fresh GitLab instance running on CentOS 8 Stream in under an hour. I’ve been stuck with broken installs that blamed “missing libffi” or “invalid config file” after a bad OS upgrade, but following these steps sidesteps those headaches. If you hit any snags, feel free to drop a comment—I’ll see if I can help troubleshoot.
