Certificates and internal certificate authorities

Connect to Retool with HTTPS

When deploying Retool using Docker Compose, an https-portal service is included in the docker-compose.yml file which provides SSL automatically. This setup uses LetsEncrypt to provision a certificate. You can also manually add your own certificate if you don't want to use LetsEncrypt.

Use a LetsEncrypt SSL certificate with Docker

1. Configure DNS

Set up a DNS so that retool.yourcompany.com points to the Retool server.
Then, open the docker.env file and update the DOMAIN.

# Before

DOMAINS=XX.XXX.XXX.XXX -> http://api:3000

# After

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

2. Update the docker-compose.yml file

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

# Before

...
  https-portal:
    ...
    environment:
      STAGE: 'local'
    networks:
      - frontend-network
...

# After
...
  https-portal:
    ...
    environment:
      STAGE: 'production'
    networks:
      - frontend-network
...

Manually add certificates

If you deploy Retool on a VPC without access to the public internet, LetsEncrypt can't provision certificates. In this case, you need to manually add your certificates.

1. Modify https-portal 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

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

3. Configure NGINX

To set up NGINX, you need to create a .conf file.

1. Create an nginx directory if it doesn't exist.
2. In the nginx directory, create a configuration file. You can name it anything as long as you use the .conf extension.
3. Add the following to your .conf file.

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;
    }
}

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

Connecting to APIs

If your API's SSL certificates are signed by an internal CA, Retool refuses to connect over HTTPs unless you configure Retool 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.