Gitpod Self-Hosted Requirements

⚠️ Gitpod Self-hosted is no longer supported

The last update of Gitpod Self-hosted product was November 2022. Users can still request our free community license however there will be no support or updates to the product. If you are interested in an isolated, private installation of Gitpod, take a look at Gitpod Dedicated.

Gitpod has certain expectations on the characteristics of the cluster it is running on as well as the (software) components connected to it.

Please refer to the product compatibility matrix for the supported types and versions of these components.

Cluster Requirements

cluster requirements

Reference Architectures

We have created a set of reference architectures for all the major cloud providers that fulfill the requirements below. These are intended as a starting point for you to create an environment to install Gitpod into. If you wish to use K3s, please refer to the k3s guide. Please see the product compatibility matrix for the current level of k3s support.

Supported Kubernetes Versions and distributions

Please refer to the product compatibility matrix for supported Kubernetes versions and distributions.

Node Affinity Labels Requirements

Your Kubernetes cluster must have node(s) with the following labels applied to them:


It is recommended to have a minimum of two node pools, grouping the meta and ide nodes into one node pool and workspace related nodes into another. These two groups of workloads have different performance characteristics. Separating them into node pools after the fact is more difficult and incurs downtime. A further improvement is to also separate the headless workspaces (these are prebuilds) and regular workspaces into separate node pools. Prebuilds can use up a lot of compute and this might impact regular workspaces if they are running on the same node.

Node and Container Requirements

These are the components expected on each node (see product compatibility matrix for supported versions):

  • Ubuntu Linux
  • Calico for the networking overlay and network policy
  • Containerd
  • At least 4 vCPU and 16GB of RAM

Kubernetes Privilege Requirements

Your Kubernetes cluster must allow Gitpod to run privileged pods, as Gitpod depends on these privileges to provide workspace isolation.

Load Balancer Requirements

Gitpod uses LoadBalancer type services to expose the Gitpod Dashboard, browser-based IDEs, and SSH connections used by desktop IDEs. Your Kubernetes cluster must be able to provision layer 4 or layer 7 load balancers for LoadBalancer type services that can route HTTP(S) connections to Gitpod services. If you intend to use desktop IDEs or SSH to workspaces then your cluster must also be able to provision layer 4 load balancers that can route SSH connection to Gitpod services.

All supported Kubernetes distributions provide load balancers that meet Gitpod’s needs. For more information see the Kubernetes distribution documentation below:

Required Components

Gitpod relies on certain components and services for it to function. By default, most of these can be automatically installed in-cluster during installation. However, you can also configure Gitpod to use your own version of these that may or may not live inside the cluster. We recommend using external components when running Gitpod for sustained usage because this avoids the risk of data loss when the cluster goes down.

Please refer to the product compatibility matrix for the supported types and versions of these components.

Component Required?
Bucket Storage Use default or bring your own
Database Use default or bring your own
Image Registry Use default or bring your own
Source Control Management System Yes (cloud or self-hosted SCM)
Cert-manager Yes

Bucket Storage

By default, MinIO is installed in the cluster to store static content and to back an in-cluster image registry. During the installation process you can also configure Gitpod to use an external storage providers like S3.


Gitpod uses a MySQL database to store user data. By default Gitpod ships with a MySQL database built-in and data is stored using a Kubernetes PersistentVolume. For production settings, we recommend operating your own MySQL database (version v5.7 or newer). Which database is used can be configured during installation.

Image Registry

Gitpod relies on an image registry to store images used to start workspaces. By default, a docker based image registry backed by MiniIO is installed in the cluster (this can be configured during the installation). However, Gitpod is also compatible with any registry that implements the Docker Registry HTTP API V2 specification.

Source Control Management System

Gitpod expects to be connected to a Source Control Management System (SCM) such as GitLab in order to function. You can find out more about which SCMs are supported and how to connect to them in the Integrations section. You will also be guided through connecting your SCM once you access your Gitpod installation for the first time.

Cert Manager

Cert-manager must be installed in your cluster before you can install Gitpod. It is used to create and manage certificates needed to secure communication between the various internal Gitpod components. It can also be used to fetch a TLS certificate for your Gitpod instance from Let’s Encrypt for example. Please consider the cert-manager documentation on how to install it.

Was this helpful?