👍 What we like
- No CI minute quota: only your machine limits your pipelines
- Container Registry, CI/CD, wiki and Pages built into the same tool
- Sign-in through an external OAuth provider such as Discord, using the generic OAuth2 provider
- Official Omnibus package: the PostgreSQL database and the bundled NGINX are installed and configured along with GitLab
👎 What to watch
- 8 GB of RAM at the very least, 16 GB to be comfortable
- Behind a reverse proxy, HTTPS and the registry need manual configuration
- Discord only returns an avatar identifier: profile pictures do not come through as is
- Mandatory upgrade stops; backups do not include the secrets
📑 Contents ▾
- 01 What this guide covers
- 02 Self-host or stay on gitlab.com
- 03 Hardware: memory first
- 04 Installing GitLab with Omnibus
- 05 HTTPS behind a reverse proxy
- 06 Git over SSH on port 22
- 07 Signing in with Discord (generic OAuth2)
- 08 Container Registry
- 09 The runner in Docker mode
- 10 Backups and restore
- 11 Upgrades
- 12 Homelab VM or VPS
- 13 Frequently asked questions
- Our picks
Self-hosting GitLab CE is worth it when you want CI/CD, a container registry and merge requests in one tool, and you can give it 8 GB of RAM at the very least, 16 GB to be comfortable, according to GitLab’s documentation. Installing the official Omnibus package takes two commands; the work comes afterwards: HTTPS behind a reverse proxy, user sign-in, a CI runner, backups and upgrades. For solo use without heavy CI, Gitea or Forgejo do the job with far less memory.
What this guide covers
The guide follows the order of an install: the official Omnibus package on a dedicated machine or a VM, HTTPS behind a reverse proxy, Git over SSH on port 22, user sign-in through Discord, the Container Registry, a GitLab runner in Docker mode, then backups and upgrades.
Each piece comes with generic examples, using the made-up domain git.example.com, and the figures quoted are not measurements. For the steps that change from one GitLab version to the next, the page points to the official documentation rather than freezing a procedure.
Self-host or stay on gitlab.com
- CI minutes. The free tier of gitlab.com includes 400 CI compute minutes per month. A 10-minute pipeline run 10 times a day uses them up in four days. With your own runner there is no quota: only the machine limits you.
- Privacy. Code, issues and container images stay on a machine you control, not with a third party.
- The registry. The Container Registry is built in: no need for Harbor or a Docker Hub account on the side.
- The price you pay. You become the administrator: updates, backups, monitoring, and a machine that keeps several GB of memory busy at all times.
CE or EE? For a small team, the Community Edition (CE) covers the essentials: repositories, merge requests, CI/CD and the registry. The Enterprise Edition (EE) becomes relevant for larger teams, mostly for portfolio management (epics, group-level value stream analytics). Before relying on a specific feature, check on GitLab’s website that it is actually part of CE.
Hardware: memory first
- RAM: 16 GB is the baseline for a single-node instance according to GitLab’s documentation, which says it can run with at least 8 GB in a memory-constrained environment. At idle, the Rails application and the Sidekiq workers already take a significant share of memory, and usage climbs with background jobs. With little memory, plan on swap and see GitLab’s documentation page on memory-constrained environments.
- CPU: 8 vCPU is the baseline for a single-node instance, according to GitLab’s documentation.
- Disk: an SSD. Repositories, the PostgreSQL database and the registry generate lots of small reads and writes; on a hard drive, the interface and pipelines slow down noticeably.
- The runner: on the same machine as GitLab, a heavy build competes with it for memory and CPU. If RAM is tight, put it elsewhere (see below).
Installing GitLab with Omnibus
On Ubuntu, the install takes two commands:
curl -sS https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash
sudo EXTERNAL_URL="https://git.example.com" apt install gitlab-ce
The first adds GitLab’s package repository, the second installs GitLab CE. EXTERNAL_URL sets the instance’s public address; you change it later in /etc/gitlab/gitlab.rb, with the external_url directive. Any change to that file is applied with:
sudo gitlab-ctl reconfigure
The first reconfigure, run automatically by the installer, takes several minutes. The Linux package installation page in GitLab’s documentation lists the system prerequisites for your distribution and tells you where to find the initial administrator password: change it on first sign-in.
HTTPS behind a reverse proxy
With an external_url starting with https://, the NGINX bundled with Omnibus tries to issue a Let’s Encrypt certificate by itself. On a directly exposed machine, that automatic certificate can be enough. But if a reverse proxy (Caddy, Traefik…) already terminates TLS in front of GitLab, the two clash: turn off the bundled Let’s Encrypt in /etc/gitlab/gitlab.rb and make the bundled NGINX listen on plain HTTP.
external_url 'https://git.example.com' # the public URL stays HTTPS
letsencrypt['enable'] = false
nginx['listen_https'] = false
nginx['listen_port'] = 80
The catch: the public URL stays https://, even though the bundled NGINX now only listens on HTTP. The proxy terminates TLS and forwards traffic to port 80 on the GitLab machine; our Caddy with Docker tutorial shows the proxy side. The page of GitLab’s documentation on SSL behind a proxy details the extra settings for your proxy.
Git over SSH on port 22
By default, Omnibus relies on the system’s OpenSSH. SSH clones (git@git.example.com:group/project.git) use the keys each person adds to their GitLab profile.
For a forge hosted at home, the most direct method is a NAT rule on the firewall (pfSense, OPNsense or the ISP router) that exposes port 22 and forwards it to the GitLab machine. Clone URLs then carry no port number. With another public port, clone URLs have to include that number; GitLab’s documentation explains how to declare it so the interface shows correct URLs. Our pfSense on a mini PC tutorial covers installing the firewall itself.
Exposing port 22 also makes the machine’s administration SSH reachable, since the same OpenSSH server answers: accept key-based authentication only.
Signing in with Discord (generic OAuth2)
GitLab has no dedicated Discord connector, but its generic OAuth2 provider (oauth2_generic) can be wired to Discord’s OAuth2 API.
- In the Discord developer portal, create an application and, in its OAuth2 section, register your GitLab instance’s OAuth callback address as the redirect URL; its exact form is given in GitLab’s OmniAuth documentation. Note the client ID and secret.
- In
/etc/gitlab/gitlab.rb:
gitlab_rails['omniauth_block_auto_created_users'] = true
gitlab_rails['omniauth_providers'] = [
{
name: 'oauth2_generic',
label: 'Discord',
app_id: 'DISCORD_APP_ID',
app_secret: 'DISCORD_APP_SECRET',
args: {
client_options: {
site: 'https://discord.com',
authorize_url: '/api/oauth2/authorize',
token_url: '/api/oauth2/token',
user_info_url: '/api/users/@me'
},
user_response_structure: {
root_path: [],
id_path: ['id'],
attributes: {
nickname: 'username',
first_name: 'global_name',
email: 'email'
}
},
authorize_params: {
scope: 'identify email'
},
strategy_class: "OmniAuth::Strategies::OAuth2Generic"
}
}
]
- Apply with
sudo gitlab-ctl reconfigure: a “Discord” button appears on the sign-in page.
Automatically creating a GitLab account on first sign-in with Discord is a separate setting, among the OmniAuth options described in GitLab’s documentation. omniauth_block_auto_created_users = true is the default, written out here to make it visible: accounts created through Discord stay blocked until an administrator approves them. Setting it to false would let any Discord account in. The email scope passes the Discord account’s email address to GitLab.
That leaves the avatar. Discord does not return an image URL, only an identifier (a hash) from which the image address has to be rebuilt. GitLab does not do that transformation, which is why the example has no image attribute: accounts keep the default avatar. To show Discord avatars, you need a scheduled task that rebuilds the URL, downloads the image and uploads it through GitLab’s admin API.
Container Registry
Behind a reverse proxy, the registry follows the same logic as the web interface: a public HTTPS URL, and a bundled NGINX listening on plain HTTP on a dedicated port.
registry_external_url 'https://registry.git.example.com'
registry_nginx['listen_https'] = false
registry_nginx['listen_port'] = 5050
The proxy terminates TLS for registry.git.example.com and forwards traffic to port 5050 on the GitLab machine. Once that is in place, a pipeline builds and pushes an image with no credentials to manage: the job authenticates with the CI_REGISTRY_USER, CI_REGISTRY_PASSWORD and CI_REGISTRY variables that GitLab provides.
# .gitlab-ci.yml
docker:build:
stage: build
image: docker:<version>-cli # same version for both
services:
- docker:<version>-dind
script:
- echo "$CI_REGISTRY_PASSWORD" | docker login -u "$CI_REGISTRY_USER" --password-stdin "$CI_REGISTRY"
- docker build -t "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA" .
- docker push "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA"
Replace <version> with a specific Docker version, the same for both images, rather than a moving tag. This job uses Docker-in-Docker (the dind service): the runner must be allowed to start privileged containers, and the link between the job and the Docker service needs some settings, TLS in particular. The Docker-in-Docker page of GitLab’s documentation gives the job and runner settings for your version.
The runner in Docker mode
GitLab Runner is a separate program that picks up jobs from the instance and runs them, here inside Docker containers (the docker executor). It is installed on the machine that hosts it and registers with the instance using a token provided by GitLab; the GitLab Runner documentation details installation and registration for your version.
Privileged mode is only needed for Docker-in-Docker jobs like the registry one: if you do not need it, leave it off, because a privileged container has broad access to the host.
For a static site like this one, an Astro build job fits in a few lines. A minimal example, not this site’s own configuration:
build:
stage: build
image: node:lts
script:
- npm ci
- npm run build
artifacts:
paths:
- dist/
Where to put the runner. On the same machine as GitLab, a heavy build competes with the instance for memory and CPU: GitLab is what slows down, or even gets OOM-killed. If RAM is tight, a second machine dedicated to runners solves it, and a low-power mini PC fits the bill. The Beelink Mini S12 Pro (Intel N100, 4 cores, up to 16 GB of DDR4 according to its spec sheet) or the Beelink EQ14 (Intel N150, 16 GB maximum, two 2.5 GbE ports, built-in power supply) are two common examples. They are entry-level processors, more at ease with light builds than with large compilations. Other models are compared in our guide to the best mini PCs for a homelab.
Backups and restore
sudo gitlab-backup create STRATEGY=copy
# archive created in /var/opt/gitlab/backups/<timestamp>_<version>_gitlab_backup.tar
STRATEGY=copy copies the data before archiving it, which avoids errors when files change during the backup, at the cost of more temporary disk space.
The archive contains neither /etc/gitlab/gitlab.rb nor /etc/gitlab/gitlab-secrets.json. Without the latter, a restored instance can no longer decrypt its own secrets (CI variables, runner tokens, two-factor authentication secrets). Copy those two files separately, encrypted, and not in the same place as the data archive.
Schedule the backup in root’s crontab, daily for instance, and ship the archives off the machine, with rclone to another server or to object storage; our restic 3-2-1 tutorial details another method.
To restore, follow the restore procedure in GitLab’s documentation: it specifies which services to stop and which GitLab version to use, and putting gitlab.rb and gitlab-secrets.json back in place is part of it. Run a test restore on a spare machine before you need it.
Upgrades
GitLab enforces upgrade stops: you cannot jump straight from an old version to the latest one, you have to go through mandatory intermediate versions. A database schema migration can also stretch the downtime beyond what you expect. Before each upgrade:
- read the release notes and the list of upgrade stops in GitLab’s documentation;
- take a full backup,
gitlab.rbandgitlab-secrets.jsonincluded; - install a specific version, one stop at a time, rather than the latest available;
- after each stop, check that the instance works and run the checks the documentation asks for before moving to the next one.
Homelab VM or VPS
Hosting GitLab on a homelab VM avoids a monthly rent and keeps the data at home. In return you have to expose the forge (NAT for SSH, an HTTPS certificate served by GitLab or by a reverse proxy), and availability depends on your connection and your power supply.
On a VPS, there is no port forwarding or hardware to manage. Aim for a plan with 8 GB of RAM and 4 vCPU for GitLab alone, more if the runner shares the machine. PlanetHoster offers VPS plans with root access, hosted in France and Canada.
Frequently asked questions
How much does GitHub Enterprise cost by comparison?
GitHub Enterprise, which gives access to the self-hosted GitHub Enterprise Server, costs about $21 per user per month. GitLab CE is free: you only pay for the machine.
Can you leave gitlab.com for a self-hosted instance?
Yes. Project export through GitLab’s API produces an archive you import into your instance. Read GitLab’s export and import documentation first: it states what the archive carries over and the conditions for the import.
Is GitLab Pages easy to set up?
Not behind an external reverse proxy: Pages expects wildcard DNS (such as *.pages.example.com) and a matching wildcard certificate. To publish a single static site, a CI job that deploys to separate hosting is often simpler.
Key facts
Our picks
Affiliate links · same price for youPlanetHoster — VPS for GitLab CE
- VPS with root access: pick a plan with 8 GB of RAM for GitLab CE
- Datacenters in France and Canada, according to the host
- 24/7 support advertised
Beelink Mini S12 Pro (Intel N100)
- Intel N100, 4 cores / 4 threads, 6 W TDP (spec sheet)
- DDR4, 16 GB maximum in a single slot
- One M.2 PCIe 3.0 slot and one 2.5-inch SATA bay
Amazon · price and availability on the listing
Beelink EQ14 (Intel N150)
- Intel N150, 4 cores / 4 threads (manufacturer spec)
- DDR4 SO-DIMM, 16 GB maximum; 500 GB SSD included
- Two M.2 PCIe 3.0 slots, built-in power supply
Amazon · price and availability on the listing
See all our recommended gear in the shop.