gitpod/docs/self-hosted/install/configure-ingress.md

url
/docs/self-hosted/latest/install/configure-ingress/

Ingress, Domain and HTTPS

There are several modes of ingress into your Gitpod installation. They mostly hinge on the fact which kind of certificate are available:

• noDomain requires no domain nor certificate but offers HTTP only
• hosts enables all features and full HTTPS support but requires wilcard HTTPS certificates
• pathAndHost is a tradeoff that works with non-wildcard HTTPS certificates Compare values.yaml for details.

IngressMode: noDomain

Custom Docker registry For this mode to work you need to configure a custom Docker registry with valid HTTPS certificates.

1. Create a file values.ingress.yaml with the following content:

   hostname: "123-123-123-123.ip.mygitpod.com"
   

   Replace 123-123-123-123 with the external IP of your cluster.

   Afterwards, do an helm upgrade --install -f values.ingress.yaml gitpod . to apply the changes.

   If you don't know the external IP of your cluster try running kubectl describe svc proxy | grep -i ingress.

2. Now your installation is available at https://123-123-123-123.ip.mygitpod.com

#####TODO

IngressMode: pathAndHost

IngressMode: hosts

Domain

Gitpod requires a domain resolvable by some nameserver (typically a public domain name, e.g. your-domain.com). 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

Installing Gitpod on a subdomain works as well. For example:

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

HTTPS

While we highly recommend operating Gitpod using HTTPS, Gitpod is able to run on insecure HTTP. If you use Gitpod's internal Docker registry, the downside of not using HTTPS is that Kubernetes won't be able to pull images from the registry because it considers the registry insecure. You can either resort to using an external registry or use HTTPS. For running Gitpod on insecure HTTP, no HTTPS certificates are needed and you can skip this section.

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

To use the HTTPS certificates for your domain

• echo values/https.yaml >> configuration.txt
• place your certificates in secrets/https-certificates/ like so:

 secrets/https-certificates:
  |- cert.pem
  |- chain.pem
  |- fullchain.pem
  |- privkey.pem

Generate the dhparams.pem file using

openssl dhparam -out secrets/https-certificates/dhparams.pem 2048

Using Let's Encrypt

The most accessible means of obtaining HTTPS certificates is using Let's Encrypt which provides free certificats to anybody who can prove ownership of a domain. Gitpod requires wildcard certificates (e.g. *.ws.your-domain.com) which can be obtained via Let's Encrypt but require proof of ownership via DNS. There is a plethora of tutorials how to generate wildcard certificates using Let's Encrypt. Things get considerably easier when your domain is registered with a service for which a Certbot DNS plugin exists.

Assuming you have certbot installed, the following script will generate and configure the required certificates (notice the placeholders):

export DOMAIN=your-domain.cm
export EMAIL=your@email.here
export WORKDIR=/workspace/letsencrypt

certbot certonly \
    --config-dir $WORKDIR/config \
    --work-dir $WORKDIR/work \
    --logs-dir $WORKDIR/logs \
    --manual \
    --preferred-challenges=dns \
    --email $EMAIL \
    --server https://acme-v02.api.letsencrypt.org/directory \
    --agree-tos \
    -d *.ws.$DOMAIN \
    -d *.$DOMAIN \
    -d $DOMAIN

# move them into place
mkdir secrets/https-certificates
find $WORKDIR/config/live -name "*.pem" -exec cp {} secrets/https-certificates \;

# Generate dhparams
openssl dhparam -out secrets/https-certificates/dhparams.pem 2048

# Enable HTTPS
echo values/https.yaml >> configuration.txt