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 retool.yourcompany.com to the Retool server. Next, open the docker.env file and update DOMAINS with the new domain.

DOMAINS=retool.yourcompany.com -> http://api:3000

Update Docker Compose​

Open the compose.yaml file and set STAGE to production:

...
  https-portal:
    ...
    environment:
      STAGE: 'production'
    networks:
      - 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.

If you are using Retool Mobile or hosting your deployment behind a firewall, concatenate your primary certificate file and intermediate certificate file. This ensures that the server presents the full chain of certificates and the root issuer is validated.

Modify HTTPS configuration​

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

nginx:
  image: nginx:latest
  ports:
    - "80:80"
    - "443:443"
  command: [nginx-debug, "-g", "daemon off;"] # Improve error logging in the container
  volumes:
    - ./nginx:/etc/nginx/conf.d
    - ./certs:/etc/nginx/certs
  links:
    - api
  depends_on:
    - api
  networks:
    - 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 retool.yourcompany.dev; # <- Change this to your subdomain

    location / {
        return 301 https://$host$request_uri;
    }
}
server {
    listen 443 ssl;
    server_name retool.yourcompany.dev; # <- 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_set_header Host $host;
        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.

sudo 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 compose.yaml and docker.env files.
version: '2'
services:
api:
image: tryretool/backend:latest
env_file: ./docker.env
...
volumes:
  - ./ssh:/retool_backend/autogen_ssh_keys
  - ./ca:/retool_backend/ca

db-connector:
...
volumes:
  - ./ca:/retool_backend/ca
NODE_ENV=production
...
NODE_EXTRA_CA_CERTS=/retool_backend/ca/cert.pem
...