Skip to main content

Configure SSL and custom certificates

Learn how to connect to Retool with HTTPS and configure custom certificates for Docker-based deployments.

Docker Compose deployments of Self-hosted Retool include https-portal to automatically configure HTTPS. You can either provision a certificate with Let's Encrypt or manually add your own certificates.

The process for Kubernetes and other deployment types is similar to the steps for Docker Compose, but might require different settings. For example, with Kubernetes you can use Kubernetes Secrets, and with Heroku you can extend the Dockerfile to copy the certificate into the container.


https-portal requires that port 80 be available and exposed to the internet, so Retool configures this automatically. If you modify this setting, https-portal won't function correctly.

SSL with Let's Encrypt

Provisioning a certificate with Let's Encrypt is a two-step process:

  1. Configure DNS
  2. Update Docker configuration file

Configure DNS

First, set up a DNS to point to the Retool server. Next, open the docker.env file and update DOMAINS with the new domain. -> http://api:3000

Update Docker Compose

Open the docker-compose.yml file and set STAGE to production:

STAGE: 'production'
- frontend-network

Add custom certificates manually

Let's Encrypt can only provision a certificate if your Retool deployment has full internet access. If you deploy Retool on a VPC without complete access to the internet, you can manually add certificates instead.

Modify HTTPS configuration

Update the https-portal service in the docker-compose.yml file to use an nginx image, and create two Docker volumes for your certificates. Rename the https-portal service to nginx.

image: nginx:latest
- "80:80"
- "443:443"
command: [nginx-debug, "-g", "daemon off;"] # Improve error logging in the container
- ./nginx:/etc/nginx/conf.d
- ./certs:/etc/nginx/certs
- api
- api
- frontend-network

Mount certificates

To mount your certificates, create the directories these volumes point to.

In the retool-onpremise directory:

  1. Create a certs directory if it doesn't exist.
  2. Move your .crt and .key files into the certs directory.

Set up and configure nginx

To configure nginx:

  1. Create an nginx directory if it doesn't currently exist.
  2. Create a configuration file named nginx.conf.
  3. Add the following to nginx.conf and update it with your own information.
server {
listen 80;
server_name; # <- Change this to your subdomain

location / {
return 301 https://$host$request_uri;
server {
listen 443 ssl;
server_name; # <- Change this to match server_name above
ssl_certificate /etc/nginx/certs/hatch.crt; # <- Change this to your .crt file name
ssl_certificate_key /etc/nginx/certs/hatch.key; # <- Change this to your .key file name

location / {
proxy_pass http://api:3000;

Restart Docker containers

Run sudo docker-compose up -d to restart your containers.

View container logs

You can run the following commands to view container logs. These logs are helpful if you run into issues and need to troubleshoot.

docker-compose exec https-portal bash
cd /var/log/nginx
cat error.log

Connect to APIs using HTTPS

If your API's SSL certificates are signed by an internal CA, your Retool deployment cannot connect over HTTPS until you configure it to trust your CA. You do this by setting NODE_EXTRA_CA_CERTS to the absolute path of your certificate files. The files need to include one or more trusted certificates in PEM format.

If you use Source Control, set the SSL_CERT_FILE environment variable to the path of your certificate files on your api and jobs-runner containers.

Configure Docker Compose

With Docker Compose deployments, you need to store the certificate as a file on the filesystem, and then mount that file to the api container.

  1. Create a subdirectory in your retool-onpremise repo named ca.
  2. Save your internal certificate in PEM format to ./ca/cert.pem.
  3. Configure the following docker-compose.yml and docker.env files.
version: '2'
image: tryretool/backend:latest
env_file: ./docker.env
- ./ssh:/retool_backend/autogen_ssh_keys
- ./ca:/retool_backend/ca

- ./ca:/retool_backend/ca