How to Self Host GitLab in 2026 (and Keep It Running)

GitLab self hosted, which GitLab calls GitLab Self-Managed, means running GitLab (Community or Enterprise Edition) on a server you control. The install is the easy part: one container, one config file, and about ten minutes until the sign-in page answers.

Self hosted GitLab at a glance (GitLab 19, checked October 2026)

What goes wrong comes later. A clone link that starts with http:// behind your proxy. A half-added email config that stops GitLab from starting. A restore that brings back every repository but leaves 2FA and CI/CD secrets unreadable. An upgrade that skipped a version GitLab required.

We run Selfhost.dev, where GitLab is a one-click template, and building it taught us that the install was never the hard part. Five things GitLab doesn’t set safely for you by default decide whether it survives the first restart, the first email, and the first upgrade. This guide does each of them by hand, then covers the two habits that keep GitLab recoverable.

Or skip the setup: GitLab hosting in one click applies the proxy, email, memory, and root-password settings before the first boot and keeps its config across restarts.

Before you self host GitLab: is it worth it, and which route?

User count is only one factor. Self hosting GitLab becomes the better fit when you need control of the infrastructure, code that stays where you choose, your own CI machines, or admin control GitLab.com doesn’t give. GitLab.com Free also stops at five users per top-level group. The ongoing cost is mostly time.

That time ranges from minutes to hours a month, depending on team size and how much you automate:

GitLab ships a new minor version on the third Thursday of every month, with patch releases twice a month in between (GitLab maintenance policy), so the upgrade window is a standing appointment rather than a one-off. The same time-versus-money question comes up with self hosting Supabase.

Four routes to the same GitLab

Every route runs the same bundle, the Linux package (or Omnibus): PostgreSQL, Redis, Gitaly (Git storage), Puma (the web server), Sidekiq (background jobs) and NGINX. On Kubernetes, GitLab says “you should not plan to deploy the GitLab Docker image” because “it creates a single point of failure” (Docker install docs); use the Helm chart. This guide uses Docker Compose: every setting in one file you can read, back up and copy.

Rather skip the setup? The proxy, email, memory and root-password settings in section 3 are applied before first boot on our GitLab template, on your own European 8 GB server with root SSH and HTTPS from the first boot, at $0.03/hr. See GitLab hosting in one click →

How to self host GitLab, step by step

To self host GitLab with Docker Compose, prepare an 8 GB server with a real hostname, free port 22 for Git, write a Compose file with a pinned version and the five settings, start it, and sign in as root. The five steps below take about ten minutes of waiting and a few of typing.

1. Prepare the server: 8 GB of RAM, a hostname that resolves to it, Docker with Compose.
2. Free port 22: move the server’s own SSH to another port so Git can use 22.
3. Write the Compose file: pinned version, shm_size, and the five settings (below).
4. Start it and wait: docker compose up -d, then let the first boot finish.
5. Sign in, then lock it down: root password, remove the password secret, close sign-up.

GitLab self hosted requirements: what you need first

• 8 GB of RAM. GitLab’s requirements set a 16 GB, 8 vCPU baseline and say GitLab “can run with at least 8 GB of memory” when constrained. With the memory settings below, 4 vCPU suits a small team. More: what GitLab needs to run.
• A hostname that resolves to the server. GitLab needs “a valid, externally accessible hostname”, not localhost.
• Port 22 free for Git. GitLab recommends moving the server’s own SSH (sshd) to another port, such as 2424, so clone URLs stay plain [email protected]:group/project.git. Reconnect on the new port before you close the old session.
• Docker with Compose on Linux. GitLab doesn’t support Docker for Windows.
• A mail relay, eventually. “The GitLab images don’t include an MTA.” Setting 2 covers when to add one.

The GitLab Docker Compose file, with the five settings in it

Adapted from GitLab’s official example. The comments explain each setting; sections 3 and 4 go deeper.

# docker-compose.yml: GitLab Community Edition
services:
  gitlab:
    # Pin an exact version. GitLab offers :latest "for testing purposes" only.
    image: gitlab/gitlab-ce:{{GV_EXAMPLE}}
    container_name: gitlab
    restart: always
    hostname: gitlab.example.com

    # Docker's 64 MB /dev/shm default is too small for GitLab. Keep this line.
    shm_size: '256m'

    ports:
      - '80:80'        # remove 80 and 443 if a reverse proxy on this host serves GitLab
      - '443:443'
      - '22:22'        # Git over SSH: move the server's own sshd off 22 first

    volumes:
      - ./config:/etc/gitlab      # gitlab.rb and gitlab-secrets.json: back these up
      - ./logs:/var/log/gitlab
      - ./data:/var/opt/gitlab    # repositories, database, uploads, backups

    secrets:
      - gitlab_root_password      # remove after your first sign-in (see below)

    environment:
      # Setting 5: these lines live in this file, not in gitlab.rb.
      GITLAB_OMNIBUS_CONFIG: |
        # Setting 1: the URL people use. https:// turns on GitLab's own TLS and Let's Encrypt.
        external_url 'https://gitlab.example.com'

        # Behind a reverse proxy that already terminates TLS? Uncomment all three,
        # remove the 80/443 ports above, and put GitLab on your proxy's Docker network.
        # GitLab 19 key names; on GitLab 18 use nginx['listen_port'] and nginx['listen_https'].
        # gitlab_rails['nginx']['listen_port'] = 80
        # gitlab_rails['nginx']['listen_https'] = false
        # letsencrypt['enable'] = false

        # Setting 2: email stays off until every SMTP value exists.
        gitlab_rails['smtp_enable'] = false

        # Setting 3: memory. Monitoring off, fewer Sidekiq threads, Puma left at 2 workers.
        prometheus_monitoring['enable'] = false
        puma['worker_processes'] = 2
        sidekiq['concurrency'] = 10

        # Setting 4: root password from a file you control (8+ characters, GitLab's minimum).
        # Delete this line and both secrets blocks after your first sign-in.
        gitlab_rails['initial_root_password'] = File.read('/run/secrets/gitlab_root_password').gsub("\n", "")

secrets:
  gitlab_root_password:
    file: ./root_password.txt

From our template build: GitLab’s Docker troubleshooting page blames metrics files outgrowing Docker’s 64 MB shared-memory default. We hit a second reason: GitLab’s bundled PostgreSQL also failed on it. Keep the line.

Start GitLab: what the first boot and the 502 mean

Run docker compose up -d and watch docker logs -f gitlab. GitLab runs gitlab-ctl reconfigure and its migrations before the web interface answers (“it might take a while”, per GitLab). A 502 page now means it’s still starting. If it fails on port 22, the server’s sshd still holds it.

Don’t restart the container while it works. An interrupted reconfigure can leave GitLab half-migrated and needing manual recovery.

Find the GitLab root password, then lock it down

Sign in as root with the password from root_password.txt. Then, before anything else:

1. Remove the password secret. Delete the gitlab_rails[‘initial_root_password’] line and both secrets: blocks from docker-compose.yml, run docker compose up -d, and only then delete root_password.txt. Deleting the file first breaks the next start: Compose refuses to run with a missing secret file, and GitLab reads that line on every boot.
2. Close public sign-up (setting 4).

If you skipped the secret, GitLab wrote a random password to a file instead:

sudo docker exec -it gitlab grep ‘Password:’ /etc/gitlab/initial_root_password

GitLab deletes that file “in the first container restart after 24 hours”, so change the password straight away.

On Ubuntu or Debian with the Linux package, the same settings go in /etc/gitlab/gitlab.rb and apply with sudo gitlab-ctl reconfigure.

The 5 settings that decide whether self hosted GitLab keeps working

GitLab’s defaults get it running; these five keep it running. They’re the five our template has to get right before GitLab’s first boot, and each has a symptom that surfaces later: after the first restart, the first email, or the first stranger who finds the URL. Four are config lines; the fifth is a rule about where config lives.

1. The URL behind your proxy

GitLab decides how to serve itself from external_url. Per GitLab’s SSL docs, installations “auto-detect whether to use SSL if external_url contains https://“, and Let’s Encrypt switches on with it. That’s right when GitLab is alone on the server. When Traefik, Caddy or nginx already terminates TLS in front of it, GitLab tries to do the same job twice.

Keep external_url as the public https:// address, so every link GitLab generates is correct, and tell its bundled NGINX to serve plain HTTP to your proxy:

# GitLab 19 key names. 
On GitLab 18: nginx['listen_port'] and nginx['listen_https'].
gitlab_rails['nginx']['listen_port'] = 80
gitlab_rails['nginx']['listen_https'] = false
letsencrypt['enable'] = false

Stop publishing 80 and 443 from the container; some proxies also need to forward Host, X-Forwarded-Ssl and X-Forwarded-For. Get it wrong and you see http:// clone URLs, a redirect loop, or certificate errors, since GitLab “attempts to renew any Let’s Encrypt certificate with every reconfigure.”

2. Email: all of it or none of it

Without mail, GitLab can’t send password resets, invitations or notifications. With it half configured, GitLab may not start at all. GitLab’s SMTP docs give this block; add it only when every value is real:

gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = "smtp.example.com"
gitlab_rails['smtp_port'] = 465
gitlab_rails['smtp_user_name'] = "[email protected]"
gitlab_rails['smtp_password'] = "your-smtp-password"
gitlab_rails['smtp_domain'] = "example.com"
gitlab_rails['smtp_authentication'] = "login"
gitlab_rails['smtp_enable_starttls_auto'] = true
gitlab_rails['smtp_openssl_verify_mode'] = 'peer'
gitlab_rails['gitlab_email_from'] = '[email protected]'

Port and TLS mode depend on your provider (465 or 587); GitLab’s docs have provider examples. The same page warns that smtp_password “should not contain any String delimiters used in Ruby or YAML (f.e. ‘)”. Test from gitlab-rails console with Notify.test_email('[email protected]', 'Test', 'It works').deliver_now.

What we found building Gitlab template: a Compose file that fills this block from environment variables is convenient until one variable is empty. The empty value lands inside GitLab’s Ruby config as a syntax error, and GitLab stops booting. Our template leaves email off for exactly this reason, so nothing half set can take GitLab down; you add a relay once every value exists.

3. Memory

GitLab’s defaults are Puma (2 workers), Sidekiq (20 threads) and Prometheus monitoring on. Three kinds of evidence say how far to trim them, and they answer different questions:

What this means for you: on 8 GB, turn monitoring off and set Sidekiq around 10; keep Puma’s 2 workers. Then check health with GitLab’s health endpoints (/-/health, /-/readiness, /-/liveness, reachable from localhost by default), since Prometheus is gone.

Why our template sizes it this way: a 4 GB server can look fine idle and run short once the team starts pushing, so our template sizes GitLab at 8 GB rather than the minimum.

4. The first login

GitLab’s random root password lives in a file that disappears after 24 hours. A Docker secret, as in the Compose file, leaves nothing to catch in time; remove it after your first sign-in.

Sign-up needs a separate step. GitLab’s sign-up docs: “By default, any user visiting your GitLab domain can create an account”, and GitLab recommends disabling it on public-facing instances. New instances hold those accounts for administrator approval by default, but an approval queue on a public URL is still noise. It isn’t a gitlab.rb setting. Turn it off either way:

• In the UI: Admin → Settings → General → New user account restrictions → clear Allow new user accounts, then select Save changes.
• In gitlab-rails console: ::Gitlab::CurrentSettings.update!(signup_enabled: false)

5. Where your config lives

GITLAB_OMNIBUS_CONFIG is convenient, and it has a catch. GitLab’s Docker configuration docs state plainly: its settings “aren’t written to the gitlab.rb configuration file”, and with plain docker run the variable “is not preserved between subsequent runs.” Start the container once without it and those settings are gone, silently.

Compose fixes most of this, because the variable lives in the file. The rule that remains: pick one home for lasting settings, either the Compose file or /etc/gitlab/gitlab.rb (edit with sudo docker exec -it gitlab editor /etc/gitlab/gitlab.rb; GitLab “reconfigures itself each time the container starts”), and back up that home with your data.

That’s the checklist our GitLab template works through before GitLab first boots: HTTPS clone URLs behind the proxy, memory tuned for the server, the root password set, nothing half configured in email, and an exact version pinned. You keep root SSH, and your version stays put until you move it.

Launch GitLab with this checklist already applied → · or go straight to the console

Backups and upgrades: the 2 habits that keep self hosted GitLab running

Back up the secrets file with every archive, and upgrade through GitLab’s required stops on a pinned version, including the security patches between them. The five settings decide whether GitLab works today; these two habits decide whether you can bring it back after a bad disk or a bad upgrade, and whether it keeps receiving security fixes.

How to back up GitLab: the secrets file, not just the archive

docker exec -t gitlab gitlab-backup create

The archive covers the database, repositories, uploads, CI/CD artifacts, wikis and more. Per GitLab’s backup docs, it leaves out gitlab-secrets.json and gitlab.rb on purpose: the database holds encrypted 2FA data and CI/CD variables, and “storing encrypted information in the same location as its key defeats the purpose of using encryption in the first place.” Lose the secrets file, and GitLab “will not be able to decrypt any encrypted values in the database.”

Restores have one more rule: “You can only restore a backup to exactly the same version and type (CE/EE) of GitLab on which it was created.” Every backup should therefore leave the server as three things:

• The archive, from ./data/backups/
• ./config/gitlab-secrets.json
• Your config home: the Compose file or ./config/gitlab.rb, which also records the exact version

GitLab upgrade path: required stops and security patches

GitLab’s upgrade path docs define required upgrade stops as “versions of GitLab that you must upgrade to before upgrading to later versions.” For GitLab 19, the stops are 19.2, 19.5, 19.8 and 19.11; as of October 2026, 19.2 has shipped and the other three are planned. At each stop, let the background migrations finish before moving on; GitLab’s Upgrade Path tool lists the exact route from your version.

With Compose, each step is the same four moves (GitLab’s Docker upgrade docs):

1. Back up the database and the secrets file.
2. Change the image tag in docker-compose.yml to the next stop.
3. docker compose pull
4. docker compose up -d, then wait for background migrations to finish.

This is why the tag is pinned. With :latest, the next pull or redeploy can land you on a version past a required stop.

Security is the other half of this habit. GitLab ships patch releases twice a month, and its maintenance policy backports security fixes only to the current release and the previous two monthly releases. Fall more than two minor versions behind and your GitLab stops receiving security fixes at all.

What this means for you: book a short upgrade window every month, even when there’s no feature you want, and check GitLab’s current upgrade path before every upgrade; these stops can change as new releases arrive.

Selfhost.dev Gitlab template pins the image the same way: the version never moves on a restart or redeploy.

When self hosted GitLab breaks: symptom, cause, fix

Most self hosted GitLab failures trace back to one of the five settings or the two habits above, and each leaves a recognisable symptom. Find yours in the left column; the cause and the fix sit beside it, with a link to the setting or habit that prevents it next time.

Self host GitLab by hand, on Selfhost.dev, or stay on GitLab.com?

Choose by who will own GitLab’s upkeep: the upgrades every month, the security patches, and the backups. If nobody will, GitLab.com is the honest answer. If someone will, self host by hand. If you want your own server and data but not the setup, that’s what our template is for.

• Nobody on the team will own upgrades and backups, and you’re within five users → GitLab.com Free. It’s hosted and maintained by the people who write GitLab.
• You need Premium features → a GitLab paid plan, on GitLab.com or as a licence on your own instance.
• Someone will own the config and the upgrade calendar → the Compose route above.
• You want your own GitLab, server and data, without the setup → Selfhost.dev: the proxy, email, memory and root-password settings applied before first boot, root SSH, and a pinned version, as a template on Selfhost.dev Projects.

On our template, email stays off until you add a relay, and upgrades and security patches are yours to schedule.

Launch GitLab on an hourly European 8 GB server, check the settings yourself, and delete it if you’d rather build it by hand. Open GitLab in the console → · See what the server costs

Frequently Asked Questions