Note: Setting up a self-hosted Gitpod instance needs some Kubernetes experience. Detailed guidance on how to setup and maintain a Kubernetes cluster is behind the scope of these docs. See also Prerequisites to Install Gitpod Self-Hosted.
Gitpod is a Kubernetes application that uses Kubernetes internally to provision workspaces as Kubernetes pods. Before you can start installing Gitpod, you need to create a compatible Kubernetes cluster. Since the steps that are needed to create a proper cluster differ between the cloud providers, it’s up to you to setup a cluster that meets the proper requirements. We have created a list of examples and scripts that will help you to get started with your favorite cloud provider.
Once you have created your Kubernetes cluster you need to install cert-manager. cert-manager is needed in any case even when you bring your own TLS certificate for your domain. Please consider the cert-manager documentation on how to install it.
Creating TLS certs for your domain with cert-manager
cert-manager provides the Gitpod installation with certificates for internal communication. Besides this, cert-manager can also create a TLS certificate for your domain. Since Gitpod needs wildcard certificates, you must use the DNS-01 challenge. Please consult the cert-manager documentation for instructions. You can use either an
Following the cert-manager instructions, you will have an
ClusterIssuer with a configured
dns01 solver (most probably with a proper secret with credentials for your DNS provider) as well a
Certificate with the following
example.com with your Gitpod domain)
To install Gitpod you need a domain with a TLS certificate. The DNS setup to your domain needs to be configured such that it points to the ingress of your Kubernetes cluster. You need to configure your actual domain (say
example.com) as well as the wildcard subdomains
*.example.com as well as
At this point, you should have:
- a running Kubernetes cluster
- cert-manager installed in this cluster
- a TLS certificate for your domain (incl. wildcard subdomains) or a configured
- a domain with proper DNS setup
To start with installing Gitpod, you need a terminal where you can run
kubectl to access your cluster. At first, install the KOTS kubectl plugin:
$ curl https://kots.io/install | bash
Now, you are ready to install Gitpod. Run the following command in your terminal:
$ kubectl kots install gitpod
You will be asked for the namespace you want to install Gitpod to as well as a password for the admin console. After some time, you will see the following output:
• Press Ctrl+C to exit • Go to http://localhost:8800 to access the Admin Console
Open your favorite browser and go to
8800 is opened on your node on
localhost only—you may want to forward the port to your workstation in order to access the admin console).
The first page will ask you to upload your Gitpod license. We provide a community license for free (right click and save link as here). To get an enterprise license, fill out this form. For more information about our licenses and respective pricing plans, please visit our self-hosted pricing page.
After uploading the license, you will be forwarded to the config page. On this page, you need to enter your domain name for your Gitpod installation. You can also configure to use external components (by default internal ones are installed) as well as your TLS certs setup. Click “Continue” to proceed with the installation.
In the next step, the installer runs a preflight check. This validates your cluster to meet the minimum requirements. Everything is green? Awesome! Click “Continue” to proceed.
Now, you are seeing the installation admin page. Once the installation has been finished successfully, you will see the status “Ready” with a small green indicator next to the Gitpod logo. You see which version you installed and which license you are using.
Open your Gitpod domain in your browser to access your running Gitpod instance.
On this page