Installation requirements for Gitpod Self-Hosted

This page details the software and hardware requirements for installing Gitpod Self-Hosted on your own infrastructure.

Supported Kubernetes distributions

Gitpod Self-Hosted runs well on:

Amazon Elastic Kubernetes Service
Google Kubernetes Engine
Microsoft Azure Kubernetes Service
K3s

Incompatible Kubernetes distributions

These platforms do not currently work with Gitpod Self-Hosted but we would like to support them in the future. Gitpod is an open-source project, maybe you could contribute the required changes to help get them working sooner?

If you are considering purchasing a commerical license for Gitpod Self-Hosted and need one of the above platforms then please contact us to start discussions about making support for them happen sooner.

Minimum Kubernetes requirements

We strongly recommend deploying a dedicated kubernetes cluster just for Gitpod Self-Hosted.

Here are the minimum requirements:

Either Ubuntu 18.04 with ≥ v5.4 kernel or Ubuntu 20.04 with ≥ v5.4 kernel.
Calico for the networking overlay and network policy.
Kubernetes ≥ 1.21.
containerd ≥ 1.2.

Minimum compute resources

If you want to run Gitpod Self-Hosted at home we recommend at minimum 2vCPU’s and 8GB of memory. For a better experience we recommend at least 4vCPUs and 16GB RAM for workspace nodes. For cost efficiency, we recommend enabling cluster-autoscaling when running on a commercial cloud provider.

Runtime requirements

DNS

Gitpod requires a domain (or sub-domain on a domain) that is resolvable by your name servers. As Gitpod launches services and workspaces on additional subdomains it also needs two wildcard domains.

For example:

your-domain.com
*.your-domain.com
*.ws.your-domain.com

or

gitpod.your-domain.com
*.gitpod.your-domain.com
*.ws.gitpod.your-domain.com

Ingress

Gitpod is designed to serve traffic directly to your local network or internet.
Wrapping Gitpod Self-Hosted behind proxies such as nginx or configurations where URLs are rewritten are not supported.

SSL

Gitpod requires trusted HTTPS certificates. While there is no hard requirement on any certificate authority, we recommend using an ACME certificate issuer (such as ZeroSSL or LetsEncrypt) to automatically renew and install certificates as we do for gitpod.io.
Installation of Gitpod with SSL certificates signed with your own CA are not currently supported. This scenario is desired and we would welcome help getting this community pull-request merged.
The HTTPS certificates for your domain must include your-domain.com, *.your-domain.com and *.ws.your-domain.com. Beware that wildcard certificates are valid for one level only (i.e. *.a.com is not valid for c.b.a.com)

Storage

Either Google Cloud Storage or Amazon S3 or MinIO Storage.

Database

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).