skip to content

For a GitLab Self-Managed instance serving about 3,000 users, how do you decide between a standalone node with backups, the high-availability reference architecture and adding Geo?

level: principalimportance: nice to knowfreq 8%

answer

  1. requests per second, not head count
  2. 3,000 users is the HA line
  3. HA multiplies every component
  4. Geo is recovery, not availability

basics

~20 s

Size from peak requests per second, then decide availability separately: up to about 2,000 users GitLab recommends standalone with backups, from 3,000 users or critical uptime the HA architecture, and Geo only for site-level disaster recovery.

solid answer

~50 s

GitLab's reference architectures size by **peak requests per second**; user counts are only a proxy (3,000 users maps to 60 API, 6 web, 6 Git pull and 1 Git push RPS). **Availability** is a separate decision: GitLab generally recommends HA at 3,000 users or more, or when GitLab being down would critically hurt the business; at 2,000 users or fewer it recommends a standalone, non-HA instance with backups, and finds backups sufficient for many customers under 3,000. The 3,000-user architecture is the smallest with HA built in, and HA means three-node quorums, Gitaly Cluster with its own database and multiple Rails nodes; it is also the prerequisite for zero-downtime upgrades. **Geo** answers a different question, losing a site: it is a warm standby with manual failover, not HA, and GitLab does not support stretching one environment across regions. With heavy automation or monorepos, start one size larger, monitor, and scale down.

go deeper

for a junior

Know that GitLab publishes reference architectures by size, and that high availability and backups are different protections.

for a middle

Explain why requests per second, not user count, sizes the environment, and what the 3,000-user HA architecture contains.

for a senior

Recommend standalone, HA or HA plus Geo from load, the outage tolerance and the team's ability to operate quorums and Gitaly Cluster.

for a principal

Own the trade-off: price the outage against the node count and staffing HA demands, and decide whether site-level recovery justifies a Geo secondary.

## Two separate decisions Planning a GitLab Self-Managed environment means answering two questions that are easy to blur: 1. **How much load must it carry?** That sets the size. 2. **What happens when part of it fails?** That decides between standalone, high availability (**HA**) and disaster recovery with **Geo**. ## Size from requests per second GitLab's reference architectures treat **peak requests per second (RPS)** as the primary sizing metric. User counts are an equivalent for when RPS is unknown, derived from real customer data that includes CI and other automation. | Architecture | API RPS | Web RPS | Git pull RPS | Git push RPS | |---|---|---|---|---| | 2,000 users | 40 | 4 | 4 | 1 | | 3,000 users | 60 | 6 | 6 | 1 | | 5,000 users | 100 | 10 | 10 | 2 | Measure before you trust the user count: GitLab's Prometheus metrics, its RPS analyser, or load balancer statistics. Heavy automation, hundreds of concurrent CI jobs on large repositories, server hooks or AI agent workflows push load above what the head count suggests. GitLab's guidance is to **start larger, monitor, then scale down**: a 3,000-user organisation with heavy automation might start on the 5,000-user (100 RPS) environment. ## Do you need high availability? GitLab's guidance is blunt about the cost. - **At 2,000 users or fewer**, a **standalone** (non-HA) single- or multi-node environment with **automated backups** is generally recommended, and GitLab finds a backup strategy sufficient, even preferable, for many customers under 3,000. Recovery is slower, but the environment is far smaller and cheaper to run. - **At 3,000 users or more**, or when an outage would **critically impact** the business, HA is recommended. The 3,000-user architecture is the **smallest one with HA built in**; a smaller organisation that still needs HA uses it with supported reductions. What HA costs, in the 3,000-user Linux package architecture: - three nodes each for PostgreSQL, the database connection poolers, Redis and service discovery; the voting components among them (Redis Sentinel, service discovery, Praefect) need an odd number, at least three; - **Gitaly Cluster (Praefect)**: three Gitaly nodes, three Praefect nodes and a Praefect database, which the Linux package cannot itself make highly available; - three Rails nodes, two Sidekiq nodes, internal and external load balancers, a monitoring node and object storage. Supported reductions exist: combine Sidekiq onto the Rails nodes, run two PostgreSQL nodes instead of three, or use managed PostgreSQL and Redis, which removes some supporting nodes. **Zero-downtime upgrades** are only available on an HA environment, so a hard "no maintenance window" requirement is itself an argument for HA. ## Where Geo fits **Geo** (Premium and Ultimate) replicates an entire GitLab instance to one or more **secondary sites**. It serves distributed teams and provides a **warm standby** for disaster recovery, with **manual** failover and eventual consistency. GitLab states plainly that Geo is not an out-of-the-box HA solution. It is also the answer to multi-region: GitLab does not support stretching **one** environment across regions, because components that vote or replicate synchronously, such as Redis Sentinel and Praefect, suffer from the latency and risk split brain. ## A decision path 1. Establish peak RPS and the workload's shape; pick the nearest size, or one larger if unsure. 2. Ask what an hour of outage costs. If it is tolerable, run standalone with tested backups, and keep `gitlab.rb` and `gitlab-secrets.json` copied outside the backup. 3. If it is not, take the 3,000-user HA architecture, reduced where supported; decide whether repository failover needs Gitaly Cluster on VMs or whether the Cloud Native layout's sharded Gitaly is acceptable. 4. If a regulator or the business requires surviving a lost site, add a Geo secondary in another location, sized as its own decision. ## Judgement, not a formula Two regulated organisations with the same 3,000 users can rightly choose differently. One accepts a restore-from-backup RTO because developers can wait; the other cannot ship a fix while GitLab is down and pays for HA plus Geo. The interview answer that lands names the load metric, the business cost of downtime and the operating staff each option demands.

  • A 1,500-user team insists on high availability. What does GitLab offer short of the full 3,000-user architecture?
    The 3,000-user architecture with its supported reductions: lower node specs, Sidekiq combined onto the Rails nodes, two PostgreSQL and two connection-pooler nodes, and managed PostgreSQL or Redis. Quorum components still need three nodes, because the architecture's makeup is what HA requires.
  • Why not get disaster recovery by stretching one GitLab environment across two data centres?
    GitLab does not support a single environment across regions. Components that replicate synchronously or vote, such as Redis Sentinel and Praefect, suffer from cross-region latency and risk split brain when the link fails. Geo, a separate secondary site with its own environment, is the supported route.

  • Size the environment from the number of licensed users alone
  • A Geo secondary gives high availability with automatic failover
  • Every GitLab instance with more than 500 users needs high availability
  • Stretch one GitLab environment across two regions for resilience
  • HA only means adding a second Rails node behind a load balancer