Self-Managed Administration: Configuration, Email, Object Storage, Backups, Restore, and Maintenance: Concepts, Architecture, and Mental Model

1. The practical problem: the Git repository is only one part of GitLab

When you operate GitLab Self-Managed, the platform itself becomes production software under your responsibility. A project can have a healthy Git repository while its database, uploads, CI artifacts, package files, encryption keys, mail delivery, registry, or background workers are unavailable. Conversely, a successful backup command can still leave you unable to restore if the target version, secrets, object storage, or repository-storage names do not match.

2. Offering boundary: who owns the platform?

3. Mental model: application state, durable data, and secret material

GitLab Rails coordinates application state with PostgreSQL; Gitaly serves Git repository storage; Redis supports caching/queues; Sidekiq executes background work; Workhorse handles large transfers; the Container Registry has its own storage lifecycle; and many object types can live locally or in object storage. Installation topology changes where these services run, but not the need to recover them coherently.

flowchart LR
  U[Users and CI clients] --> W[GitLab web / API]
  W --> R[Rails + Workhorse]
  R --> DB[(PostgreSQL)]
  R --> REDIS[(Redis)]
  R --> G[Gitaly repositories]
  R --> O[Uploads / artifacts / packages / object storage]
  R --> REG[Container Registry]
  R --> S[Sidekiq background jobs]
  CFG[Install-method configuration] --> R
  SEC[Encryption secrets / TLS / SSH keys] --> R
  B[Application backup] --> DB
  B --> G
  B --> O
  C[Separate config + secrets backup] --> CFG
  C --> SEC

The key distinction is that application data and decryption material are deliberately not one backup object. On Linux package installations, for example, gitlab-backup does not include /etc/gitlab/gitlab.rb or /etc/gitlab/gitlab-secrets.json. Losing the encryption secrets can make database values such as protected CI/CD variables or 2FA secrets undecryptable.

4. Installation method changes the administrative interface

5. Configuration is executable operational intent

Configuration defines the external URL and TLS boundary, repository storages, SMTP, object-storage endpoints/buckets, database and Redis connections, background jobs, Registry, and many feature settings. Treat configuration as reviewed infrastructure code, but never store raw production passwords or encryption keys in a public repository.

# Sanitized inventory fixture: never paste a real production gitlab.rb.
installation_method=linux-package
gitlab_version=19.3.x-ee
external_url=https://gitlab.example.invalid
repository_storages=default
object_store_mode=consolidated
smtp_mode=local-fake-relay
secrets_backup=separate-encrypted-location

6. SMTP, object storage, and repository storage are different failure domains

SMTP affects notifications, password resets, invitations, Service Desk/email features, and operational communication. Current Linux-package documentation supports encrypted settings for SMTP username/password so the cleartext credential does not need to live in gitlab.rb. Test with a local/fake relay in labs; production mail requires certificate verification and sender-domain controls.

Object storage can hold artifacts, uploads, LFS objects, packages, dependency-proxy content, Terraform state, Pages, Secure Files, and other supported objects. GitLab recommends the consolidated connection form for many object types. Repository data is still a separate Gitaly concern. A bucket name therefore does not identify a Git repository, and a Gitaly snapshot does not recover job artifacts.

7. What the application backup does—and does not—mean

The application backup can include PostgreSQL data, repositories, uploads, CI artifacts/logs, LFS, packages, Pages, Terraform state, Secure Files, and Registry data depending on installation/storage configuration. However, on Linux package, Docker, and self-compiled installations, object-storage contents are not captured by the normal backup command. Redis/queued Sidekiq work, global/file hooks, configuration files, TLS/SSH keys, and system files are also outside the application backup.

8. Health, maintenance, and housekeeping are evidence—not rituals

Read-only health endpoints separate simple process liveness from dependency readiness. /-/health only confirms the application server is responding; /-/readiness?all=1 can include dependent services such as PostgreSQL, Redis, and Gitaly. The broader /health_check endpoint is useful for diagnostics but is not the right load-balancer signal.

Maintenance Mode reduces writes during maintenance but is Premium/Ultimate on Self-Managed. A Free operator can still design safe downtime by preventing writes and stopping relevant services according to the documented procedure. Maintenance Rake tasks such as gitlab:env:info and gitlab:check SANITIZE=true provide structured pre/post evidence.

9. Inspect before changing anything

# OPTIONAL: isolated Linux-package Self-Managed instance only.
sudo gitlab-ctl status
sudo gitlab-rake gitlab:env:info
sudo gitlab-rake gitlab:check SANITIZE=true
curl -fsS http://127.0.0.1/-/health
curl -fsS http://127.0.0.1/-/readiness?all=1

Do not post the complete command output to public issues without reviewing it. Even “sanitized” diagnostics can expose hostnames, topology, versions, or integration metadata.

Knowledge check

10. Lesson summary and bridge

You now have the recovery mental model: platform topology, configuration, secrets, durable object classes, and transient services are separate boundaries. Lesson 2 turns that model into a disposable backup/restore workflow with read-before-write evidence.

Primary sources and version notes

These lessons were finalized against current official GitLab documentation on 2026-08-22 and GitLab 19.3. Self-Managed commands and file locations depend on installation method. Re-check the documentation for the exact version, topology, package/chart, and storage architecture before production administration or recovery.

• GitLab 19.3 release
• Administer GitLab
• Configure GitLab
• Back up GitLab
• Restore GitLab
• Linux package backup configuration
• Docker backup
• Helm chart backup and restore
• Object storage
• SMTP settings
• Encrypted configuration
• Health check
• Maintenance Mode
• Maintenance Rake tasks
• Integrity check Rake tasks
• Repository checks