Docs

HTTPS certificates

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

Still Have Questions?

Please reach out. We’re happy to answer them.