Use a LetsEncrypt SSL certificate with Docker

When deploying Retool using Docker Compose, an https-portal service is included in the docker-compose.yaml file which provides SSL automatically. This setup uses LetsEncrypt to provision a certificate.

🚧

Note

If you deploy Retool on a VPC, LetsEncrypt can't provision certificates automatically. You need to manually add certificates instead.

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