Skip to content

GitLab installation requirements

DETAILS: Tier: Free, Premium, Ultimate Offering: Self-managed

This page contains information about the system requirements to install GitLab.

Storage

The necessary storage space largely depends on the size of the repositories you want to have in GitLab. As a guideline, you should have at least as much free space as all your repositories combined.

The Linux package requires about 2.5 GB of storage space for installation. For storage flexibility, consider mounting your hard drive through logical volume management. You should have a hard drive with at least 7,200 RPM or a solid-state drive to reduce response times.

Because file system performance might affect the overall performance of GitLab, you should avoid using cloud-based file systems for storage.

CPU

CPU requirements depend on the number of users and expected workload. The workload includes your users' activity, use of automation and mirroring, and repository size.

For a maximum of 20 requests per second or 1,000 users, you should have 8 vCPU. For more users or higher workload, see reference architectures.

Memory

Memory requirements depend on the number of users and expected workload. The workload includes your users' activity, use of automation and mirroring, and repository size.

For a maximum of 20 requests per second or 1,000 users, you should have 16 GB of memory. For more users or higher workload, see reference architectures.

In some cases, GitLab can run with at least 8 GB of memory. For more information, see running GitLab in a memory-constrained environment.

PostgreSQL

PostgreSQL is the only supported database and is bundled with the Linux package. You can also use an external PostgreSQL database which must be tuned correctly.

Depending on the number of users, the PostgreSQL server should have:

  • For most GitLab instances, at least 5 to 10 GB of storage
  • For GitLab Ultimate, at least 12 GB of storage (1 GB of vulnerability data must be imported)

For the following versions of GitLab, use these PostgreSQL versions:

GitLab version Minimum PostgreSQL version Maximum PostgreSQL version
18.x 16.x (proposed in epic 12172) To be determined
17.x 14.x 16.x (tested against GitLab 16.10 and later)
16.x 13.6 15.x (tested against GitLab 16.1 and later)
15.x 12.10 14.x (tested against GitLab 15.11 only), 13.x

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.

You must also ensure some extensions are loaded into every GitLab database. For more information, see managing PostgreSQL extensions.

GitLab Geo

For GitLab Geo, you should use the Linux package or validated cloud providers to install GitLab. Compatibility with other external databases is not guaranteed.

For more information, see requirements for running Geo.

Locale compatibility

When you change locale data in glibc, PostgreSQL database files are no longer fully compatible between different operating systems. To avoid index corruption, check for locale compatibility when you:

  • Move binary PostgreSQL data between servers.
  • Upgrade your Linux distribution.
  • Update or change third-party container images.

For more information, see upgrading operating systems for PostgreSQL.

GitLab schemas

You should create or use databases exclusively for GitLab, Geo, Gitaly Cluster, or other components. Do not create or modify databases, schemas, users, or other properties except when you follow:

  • Procedures in the GitLab documentation
  • The directions of GitLab Support or engineers

The main GitLab application uses three schemas:

  • The default public schema
  • gitlab_partitions_static (created automatically)
  • gitlab_partitions_dynamic (created automatically)

During Rails database migrations, GitLab might create or modify schemas or tables. Database migrations are tested against the schema definition in the GitLab codebase. If you modify any schema, GitLab upgrades might fail.

PostgreSQL tuning

Here are some required settings for externally managed PostgreSQL instances.

Tunable setting Required value More information
work_mem minimum 8MB This value is the Linux package default. In large deployments, if queries create temporary files, you should increase this setting.
maintenance_work_mem minimum 64MB You require more for larger database servers.
shared_buffers minimum 2GB You require more for larger database servers. The Linux package default is set to 25% of server RAM.
statement_timeout maximum 1 min A statement timeout prevents runaway issues with locks and the database rejecting new clients. One minute matches the Puma rack timeout setting.

Puma

The recommended Puma settings depend on your installation. By default, the Linux package uses the recommended settings.

To adjust Puma settings:

Workers

The recommended number of Puma workers largely depends on CPU and memory capacity. By default, the Linux package uses the recommended number of workers. For more information about how this number is calculated, see puma.rb.

A node must never have fewer than two Puma workers. For example, a node should have:

  • Two workers for 2 CPU cores and 8 GB of memory
  • Two workers for 4 CPU cores and 4 GB of memory
  • Four workers for 4 CPU cores and 8 GB of memory
  • Six workers for 8 CPU cores and 8 GB of memory
  • Eight workers for 8 CPU cores and 16 GB of memory

By default, each Puma worker is limited to 1.2 GB of memory. You can adjust this setting in /etc/gitlab/gitlab.rb.

You can also increase the number of Puma workers, provided enough CPU and memory capacity is available. More workers would reduce response times and improve the ability to handle parallel requests. Run tests to verify the optimal number of workers for your installation.

Threads

The recommended number of Puma threads depends on total system memory. A node should use:

  • One thread for an operating system with a maximum of 2 GB of memory
  • Four threads for an operating system with more than 2 GB of memory

More threads would lead to excessive swapping and lower performance.

Redis

Redis stores all user sessions and background tasks and requires about 25 kB per user on average.

In GitLab 16.0 and later, Redis 6.x or 7.x is required. For more information about end-of-life dates, see the Redis documentation.

For Redis:

  • Use a standalone instance (with or without high availability). Redis Cluster is not supported.
  • Set the eviction policy as appropriate.

Sidekiq

Sidekiq uses a multi-threaded process for background jobs. This process initially consumes more than 200 MB of memory and might grow over time due to memory leaks.

On a very active server with more than 10,000 billable users, the Sidekiq process might consume more than 1 GB of memory.

Prometheus

By default, Prometheus and its related exporters are enabled to monitor GitLab. These processes consume approximately 200 MB of memory.

For more information, see monitoring GitLab with Prometheus.

Supported web browsers

GitLab supports the following web browsers:

GitLab supports:

  • The two most recent major versions of these browsers
  • The current minor version of a supported major version

Running GitLab with JavaScript disabled in these browsers is not supported.

Related topics