Reference architecture: up to 1,000 users (FREE SELF)

This page describes GitLab reference architecture for up to 1,000 users. For a full list of reference architectures, see Available reference architectures.

If you are serving up to 1,000 users, and you don't have strict availability requirements, a standalone single-node solution with frequent backups is appropriate for many organizations.

Users Configuration GCP AWS Azure
Up to 500 4 vCPU, 3.6 GB memory n1-highcpu-4 c5.xlarge F4s v2
Up to 1,000 8 vCPU, 7.2 GB memory n1-highcpu-8 c5.2xlarge F8s v2

The diagram above shows that while GitLab can be installed on a single server, it is internally composed of multiple services. As a GitLab instance is scaled, each of these services are broken out and independently scaled according to the demands placed on them. In some cases PaaS can be leveraged for some services (for example, Cloud Object Storage for some file systems). For the sake of redundancy some of the services become clusters of nodes storing the same data. In a horizontal configuration of GitLab there are various ancillary services required to coordinate clusters or discover of resources (for example, PgBouncer for PostgreSQL connection management, Consul for Prometheus end point discovery).


Before starting, see the requirements for reference architectures.

Setup instructions

To install GitLab for this default reference architecture, use the standard installation instructions.

You can also optionally configure GitLab to use an external PostgreSQL service or an external object storage service for added performance and reliability at an increased complexity cost.

Configure advanced search (PREMIUM SELF)

You can leverage Elasticsearch and enable advanced search for faster, more advanced code search across your entire GitLab instance.

Elasticsearch cluster design and requirements are dependent on your specific data. For recommended best practices about how to set up your Elasticsearch cluster alongside your instance, read how to choose the optimal cluster configuration.

Cloud Native Hybrid reference architecture with Helm Charts

Cloud Native Hybrid Reference Architecture is an alternative approach where select stateless components are deployed in Kubernetes via our official Helm Charts, and stateful components are deployed in compute VMs with Omnibus.

The 2k GitLab Cloud Native Hybrid (non HA) and 3k GitLab Cloud Native Hybrid (HA) reference architectures are the smallest we recommend in Kubernetes. For environments that serve fewer users, you can lower the node specs. Depending on your user count, you can lower all suggested node specs as desired. However, it's recommended that you don't go lower than the general requirements.