doc/install/requirements.md
{{< details >}}
{{< /details >}}
GitLab Self-Managed has specific hardware, component, and infrastructure requirements that vary based on your deployment size and workload. For larger or distributed deployments, use the sizing guide to determine the right specifications for your environment.
You can deploy GitLab a single node or distributed across multiple nodes. The minimum hardware requirements for a single-node installation are listed below. For distributed deployments, requirements are allocated per component type and scale with load. Use the sizing guide to determine the right specifications based on expected load and workload composition.
For a single-node installation, 8 vCPU is the baseline. ARM-based processors are supported. For distributed deployments, CPU is allocated per component type and scales with load.
[!note] Burstable instance types are not recommended due to inconsistent performance.
For a single-node installation, 16 GB is the baseline. For distributed deployments, memory is allocated per component type and scales with load.
For single-node installations in memory-constrained environments, GitLab can run with at least 8 GB of memory. For more information, see running GitLab in a memory-constrained environment.
[!note] Disable swap where possible. Swap can cause significant performance degradation under load. If swap cannot be disabled, provision sufficient memory so GitLab never uses it.
Storage requirements are component-specific. For single-node installations, total all requirements on one machine. For distributed deployments, apply each to the relevant node type:
| Component | Minimum storage | Notes |
|---|---|---|
| Application nodes (Rails, Sidekiq, Puma) | 40 GB | Package installation (~2.5 GB) plus OS, logs, and temporary files. |
| Repository storage (Gitaly) | At least as much as all repositories combined | See Gitaly disk requirements. |
| Database (PostgreSQL) | 5-12 GB | See PostgreSQL storage requirements. |
Avoid network file systems such as NFS, Amazon EFS, and Azure Files, as they can significantly affect performance. For more information, see avoiding cloud-based file systems.
[!note] For best performance, use SSD-backed storage. This is particularly important for Gitaly, which is I/O intensive. Burstable disk types are not recommended due to inconsistent performance.
GitLab runs on a range of infrastructure types. The following sections cover supported platforms and high availability requirements.
GitLab runs on cloud providers and self-managed infrastructure, provided the underlying environment meets the hardware and component requirements described in this guide. Commonly used cloud providers include AWS, GCP, and Azure. GitLab Support covers GitLab itself; issues with the underlying infrastructure or platform are outside its scope.
For Cloud Native deployments, GitLab runs on any Kubernetes distribution meeting the GitLab Helm chart prerequisites. Kubernetes platform-specific behavior such as networking, storage classes, and authentication is outside the scope of GitLab Support.
HA deployments have specific network requirements:
[!warning] A single GitLab instance must not span multiple geographic regions. For multi-region deployments, use GitLab Geo, which is designed for geographically distributed installations. Infrastructure-related issues in multi-data-center deployments might be outside the scope of GitLab Support.
PostgreSQL is the only supported database and is available:
For external instances, see:
For the following versions of GitLab, use these PostgreSQL versions:
| GitLab version | Helm chart version | Minimum PostgreSQL version | Maximum PostgreSQL version |
|---|---|---|---|
| 19.x | 10.x | 17.x | 17.x |
| 18.x | 9.x | 16.5 | 17.x (tested against GitLab 17.10 and later) |
| 17.x | 8.x | 14.14 | 16.x (tested against GitLab 16.10 and later) |
| 16.x | 7.x | 13.6 | 15.x (tested against GitLab 16.1 and later) |
Minor PostgreSQL releases include only bug and security fixes. Always use the latest minor version to avoid known issues in PostgreSQL. For more information, see issue 364763.
To use a later major version of PostgreSQL than specified, check if a later version is bundled with the Linux package.
Depending on the number of users, the PostgreSQL server should have:
To install extensions, PostgreSQL requires superuser privileges. For instructions, see Manage PostgreSQL extensions.
| Extension | Minimum GitLab version | Type | Database |
|---|---|---|---|
amcheck | 18.4 | Required | Main |
btree_gist | 13.1 | Required | Main |
pg_trgm | 8.6 | Required | Main |
plpgsql | 11.7 | Required | Main, Geo secondary tracking databases (minimum version 9.0) |
pg_stat_statements | - | Recommended | All |
Gitaly Cluster requires a dedicated PostgreSQL instance separate from the main GitLab database. For full HA, use a third-party PostgreSQL solution. A non-HA PostgreSQL instance using the Linux package is sufficient for environments that don't require database-level redundancy for Gitaly.
Redis or Valkey stores all user sessions and background tasks.
The supported versions of Redis or Valkey are:
| Datastore | Recommended version | Minimum version |
|---|---|---|
| Redis | 7.2 | 7.0<sup>1</sup> |
| Valkey | 7.2 | 7.2 |
<sup>1</sup> Redis 7.0 has reached end-of-life (EOL) upstream, but in some cases is actively maintained by vendors. For example, Amazon ElastiCache for Redis 7.1 uses its own version number but is built on Redis 7.0.
For more information about end-of-life dates for Redis, see the Redis documentation.
The recommended Puma settings depend on your installation. By default, the Linux package uses the recommended settings.
To adjust Puma settings:
webservice chart.For worker and thread sizing guidance, see Puma worker and thread sizing.
Sidekiq processes background jobs using multiple threads. Each process requires at least 200 MB of memory and can grow significantly under load. For environments with more than 10,000 users, allocate at least 1 GB per Sidekiq process.
Object storage is required for distributed deployments and recommended for all installations. It stores binary data including LFS objects, CI/CD artifacts, uploads, container registry data, and backups.
Use any S3-compatible object storage service. For configuration and a list of tested providers, see object storage.
These components are not required for a core GitLab installation but have separate infrastructure or resource requirements when used.
GitLab Container Registry stores Docker and OCI images for GitLab projects and requires:
For high-traffic environments, the registry can run on dedicated infrastructure separate from the main GitLab instance.
GitLab Pages hosts static websites for projects and groups. It runs as a separate daemon and requires a wildcard DNS record. Custom domain support requires a secondary IP address and TLS certificates.
Advanced search powers faster and more capable search across GitLab content. It requires a separate Elasticsearch or OpenSearch cluster. Cluster size depends on the volume of indexed data.
Prometheus monitoring is bundled with the Linux package and enabled by default. For information on configuring or disabling it, see monitoring GitLab with Prometheus.
Zoekt provides exact code search across repositories and runs as a separate service. For resource requirements, see Zoekt administration.
ClickHouse is an open-source column-oriented database used for product analytics features. It runs as a separate database service. For resource requirements, see ClickHouse configuration.
AI Gateway provides the backend service for GitLab Duo AI features. It runs as a standalone service deployable on Docker or Kubernetes. For resource requirements, see the installation guide.
GitLab Secrets Manager provides native secrets management powered by OpenBao. It runs as a separate Kubernetes service and requires a dedicated PostgreSQL database and load balancer.
GitLab supports the following web browsers:
GitLab targets the Baseline Widely available browser set. These are the browser versions that support web platform features stable across all core browsers. A feature reaches Widely available status after at least 30 months. The Widely available browser set includes both desktop and mobile versions of these browsers.
Running GitLab with JavaScript disabled in these browsers is not supported.