Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 36 ยท Administration and Best Practices

Self-Managed GitLab: Installation, Backups, Upgrades

Run your own GitLab: Linux package, Docker and Helm installs, key components, gitlab.rb and reconfigure, backups with gitlab-backup, secrets, restore tests and safe upgrades.

GitLab.com is the quickest way to start, but many organizations run their own server: for data location rules, network isolation or custom integration. That is called a self-managed instance. It gives you full control, and it makes you responsible for installing, securing, backing up and upgrading it.

This lesson is an administrator's overview: the components, installation methods, the configuration file, backups (and what they do not contain), restore practice and upgrades. It cannot run on this site, so commands are read-only; the examples model retention planning and an upgrade-path check. Always follow the official documentation for your exact version, because commands and requirements change.

What a GitLab instance is made of

GitLab is not one program but several cooperating services:

Component Job
Puma / Rails application The web interface and API
Workhorse A front proxy that handles large uploads and downloads
Gitaly Stores and serves the Git repositories
PostgreSQL Metadata: users, issues, merge requests, settings
Redis Caching, sessions and job queues
Sidekiq Background jobs (e-mails, mirroring, pipeline processing)
Registry, Pages, KAS Optional: container registry, static sites, agent for Kubernetes
NGINX Web server in front

The GitLab Runner is separate: it runs on other machines and connects to the instance (see the Runners and Jobs chapter of this course). Your data lives in two places: Git repositories (Gitaly) and the database, plus uploads, artifacts, packages and registry files in object storage or on disk.

Installation methods

  1. Linux package (Omnibus): a .deb or .rpm that contains everything. The recommended method for most servers: simple, well tested, easy to upgrade.
  2. Docker image: the same bundle in a container; you mount volumes for configuration, logs and data.
  3. Helm chart / operator: for Kubernetes; components run as separate pods, and stateful parts (database, Gitaly) are usually kept outside the cluster or carefully configured.
  4. Source install: only for special cases, with the most work.

Size matters. A small team can run everything on one machine; thousands of users need the reference architectures published by GitLab, which split components across servers and show the CPU, memory and storage to plan. Start from the reference size closest to your user count.

Configuring with gitlab.rb

On the Linux package, settings live in one Ruby file, /etc/gitlab/gitlab.rb:

Ruby
external_url "https://gitlab.example.com"
gitlab_rails['gitlab_email_from'] = "[email protected]"
gitlab_rails['backup_keep_time'] = 604800   # seconds: 7 days
registry_external_url "https://registry.example.com"

After each change you apply it with:

Terminal
sudo gitlab-ctl reconfigure

reconfigure rewrites the underlying service configuration and restarts what changed. Never edit generated files in /var/opt/gitlab directly, since the next reconfigure overwrites them. Useful companions: sudo gitlab-ctl status (service health), sudo gitlab-ctl tail (logs) and sudo gitlab-rake gitlab:check (a configuration check).

Set up TLS (HTTPS) from the first day, configure outgoing e-mail, and connect authentication (LDAP, SAML or OpenID Connect) so that users and their offboarding are managed centrally.

Backups

The built-in tool is:

Terminal
sudo gitlab-backup create

It writes a .tar file named like 1717243200_2026_06_01_17.0.0_gitlab_backup.tar into the backup directory (by default /var/opt/gitlab/backups). It contains the database, repositories, uploads, artifacts, packages and more, unless you skip parts.

What is not in that file is the most common cause of failed restores:

  • /etc/gitlab/gitlab-secrets.json: the keys that encrypt CI variables, two-factor secrets and runner tokens in the database. Without it, a restored database has secrets nobody can decrypt.
  • /etc/gitlab/gitlab.rb and the TLS certificates.

Back up the /etc/gitlab directory separately, and store it apart from the data backup, since together they give full access to everything.

Good backup practice:

  1. Automate with cron or a timer, and copy the files off the server (object storage, another site).
  2. Keep several generations (backup_keep_time), including some older ones, since a problem may only be noticed days later.
  3. Encrypt the copies; they contain all your code and secrets.
  4. For large instances use repository snapshots or the incremental options; the plain command gets slow as data grows.
  5. Test restores regularly. A backup that has never been restored is only a hope.

A restore needs the same GitLab version as the backup (same edition and patch version), then gitlab-backup restore BACKUP=<timestamp prefix> followed by gitlab-ctl reconfigure and gitlab-ctl restart. Object storage data is not always part of the archive: when artifacts or uploads live in a bucket, you must protect the bucket with its own versioning and backup.

Upgrades

GitLab publishes a monthly minor release and frequent patch releases. Upgrading is routine but must follow rules:

  • Read the release notes and the upgrade path. You cannot jump from any version to any other. Some versions are required stops, where background database migrations must finish before the next step. GitLab publishes an upgrade path tool that lists the versions to install in order.
  • Back up first, then upgrade a staging copy if possible.
  • On a single server, upgrade by installing the new package (apt install gitlab-ee=<version>) and let it reconfigure; multi-node installs have a documented order (database, Gitaly, then application nodes).
  • After the upgrade, check gitlab-rake gitlab:check, the Admin > Background migrations page, and a sample pipeline.
  • Upgrade often. A jump of many versions is slower and riskier than small steps, and security fixes only land in supported releases.

Monitoring and care

Monitor disk space (repositories, artifacts and registry grow constantly), memory, Sidekiq queue length and the health endpoints (/-/health, /-/readiness). The bundled Prometheus and Grafana can be enabled, and metrics can be scraped by your own monitoring. Set artifact expiry and registry cleanup so storage does not fill silently (see Container Registry and Pipeline Efficiency Best Practices).

Stand-in: planning backup retention

The first example answers "how much space do my backups need?" for a daily plan with a retention rule, using invented sizes.

JS Backup space planning

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The second example checks an upgrade path against a list of required stops. The version numbers are invented for the example; the real list comes from GitLab's upgrade path tool.

JS Upgrade path with required stops

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which file must you back up separately because the GitLab backup archive does not contain it?

    gitlab-secrets.json holds the keys that decrypt CI variables, two-factor secrets and runner tokens. Without it a restore leaves unusable secrets.
  2. 2. What must you do after editing /etc/gitlab/gitlab.rb?

    reconfigure applies the settings and restarts the services that changed.
  3. 3. Which component stores and serves Git repositories?

    Gitaly is the Git storage service. Redis caches and queues, Sidekiq runs background jobs, Workhorse proxies large requests.
  4. 4. Why test restores regularly?

    Missing secrets, version mismatches or unreachable buckets only show up when you try to restore.
  5. 5. A restore needs which version of GitLab?

    Backups are tied to the version that wrote them; restore on the same version, then upgrade afterwards.

Summary

  • A GitLab instance is several services: Rails, Workhorse, Gitaly, PostgreSQL, Redis, Sidekiq and optional extras.
  • The Linux package is the usual install; configure gitlab.rb and run gitlab-ctl reconfigure.
  • Back up with gitlab-backup, plus /etc/gitlab separately, copy backups off-site, and test restores.
  • Upgrade often, follow the upgrade path and required stops, and back up before every step.

Next: Groups, Subgroups and Governance