Configure SSL and custom certificates

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.

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 so that retool.yourcompany.com points 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 docker-compose.yml 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.

Modify HTTPS configuration

Update the https-portal service in the docker-compose.yml file to match the following configuration. This creates two Docker volumes that NGINX uses for certificates.

https-portal:
  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_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.

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'
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
...

Configure Kubernetes and other deployment infrastructures

The process for Kubernetes and other deployment options are similar to Docker Compose, but you might have different options depending on your infrastructure. For example, with Kubernetes you can use Kubernetes Secrets, and with Heroku you can extend the Dockerfile to copy the certificate into the container.