How to Integrate Retool with Docker

On your server, clone Retool's official Docker repository or download the docker-compose.yml file directly from Retool's GitHub repository (github.com/tryretool/retool-onpremise). The repository contains the docker-compose.yml and a .env.template file. Copy .env.template to .env — this file contains all configuration variables for the deployment. The critical required variables are: DEPLOYMENT_TEMPLATE_TYPE (set to 'docker-compose'), JWT_SECRET (generate a random 64-character string using: openssl rand -hex 32), ENCRYPTION_KEY (generate another random 64-character string using: openssl rand -hex 32), POSTGRES_DB (Retool's internal database name, typically 'hammerhead_production'), POSTGRES_PASSWORD (a strong password for the internal Postgres database), and LICENSE_KEY (your Retool license key from the Retool team). The JWT_SECRET signs user session tokens and ENCRYPTION_KEY encrypts stored credentials — both must be preserved if you ever need to restore from a backup. If these keys are lost, all stored resource credentials must be re-entered.

1# Key environment variables in .env file:
2
3# Security keys (generate random values, NEVER share or lose these)
4JWT_SECRET=your_64_char_random_string
5ENCRYPTION_KEY=your_64_char_random_string
6
7# Internal Postgres database
8POSTGRES_DB=hammerhead_production
9POSTGRES_PASSWORD=strong_internal_db_password
10
11# Retool configuration
12COOKIE_INSECURE=false
13NODE_ENV=production
14FORCE_DEPLOYMENT_SPECIFIC_ROTATION=false
15
16# License
17LICENSE_KEY=your_retool_license_key
18
19# Optional: base domain for OAuth callbacks
20BASE_DOMAIN=https://retool.yourcompany.com

With the .env file configured, start all Retool services by running docker compose up -d from the directory containing docker-compose.yml. Docker pulls the Retool images from Docker Hub (retool/retool) on first run — this may take 5-10 minutes depending on network speed. After the pull completes, Docker starts four containers: retool-api (the main application), retool-db_connector (database proxy), retool-jobs-runner (background tasks), and retool-postgres (internal metadata database). Monitor startup logs with docker compose logs -f api to watch for any startup errors. The api container is ready when you see a log line containing 'Listening on port 3000'. By default, Retool is accessible on port 3000 of your server. Set up a reverse proxy (nginx or Caddy) or load balancer in front of port 3000 to handle SSL termination and serve Retool on port 443.

1# Start all containers in detached mode
2docker compose up -d
3
4# Check container status
5docker compose ps
6
7# Watch api container startup logs
8docker compose logs -f api
9
10# Check all containers are healthy:
11# retool-api       running
12# retool-db_connector  running
13# retool-jobs-runner   running
14# retool-postgres      running

For production, place nginx or Caddy in front of Retool to handle SSL termination. The simplest approach uses Caddy, which automatically provisions Let's Encrypt certificates. Install Caddy on your server and create a Caddyfile that proxies traffic to Retool's port 3000. If you use nginx, configure it with an SSL certificate from Let's Encrypt (using certbot) or your organization's certificate authority. The nginx or Caddy server listens on port 443 and forwards traffic to Retool's docker container on port 3000. Set the BASE_DOMAIN environment variable in Retool's .env to the HTTPS URL you will use (e.g., https://retool.yourcompany.com) — this is required for OAuth callback URLs to work correctly. After configuring SSL, update COOKIE_INSECURE=false in the .env file (the default) to ensure session cookies are marked as Secure and SameSite.

1# Caddyfile configuration for Retool:
2retool.yourcompany.com {
3    reverse_proxy localhost:3000
4}
5
6# Or nginx configuration:
7# /etc/nginx/sites-available/retool
8server {
9    listen 443 ssl;
10    server_name retool.yourcompany.com;
11
12    ssl_certificate /etc/letsencrypt/live/retool.yourcompany.com/fullchain.pem;
13    ssl_certificate_key /etc/letsencrypt/live/retool.yourcompany.com/privkey.pem;
14
15    location / {
16        proxy_pass http://localhost:3000;
17        proxy_http_version 1.1;
18        proxy_set_header Upgrade $http_upgrade;
19        proxy_set_header Connection 'upgrade';
20        proxy_set_header Host $host;
21        proxy_set_header X-Real-IP $remote_addr;
22        proxy_cache_bypass $http_upgrade;
23    }
24}

The primary benefit of self-hosted Retool is direct database connectivity without IP whitelisting. In the Retool admin panel (Resources → Create New), create database Resources using internal hostnames or private IP addresses. For an RDS database, use the private DNS endpoint (yourdb.xxxxxxxx.us-east-1.rds.amazonaws.com) rather than the public endpoint — this only works if Retool runs in the same VPC. For a database running on the same server as Retool, use the Docker network hostname. By default, Retool containers run on a Docker bridge network, so 'localhost' from inside the container does not reach the host. Use the special hostname 'host.docker.internal' (on Docker Desktop) or the host's Docker bridge IP (typically 172.17.0.1) to reach services on the host machine. For security, configure the database to accept connections only from the Retool container's IP or Docker subnet, restricting access further.

1# Database connection examples for self-hosted Retool:
2
3# RDS in same VPC (use private DNS endpoint):
4# Host: mydb.cluster-abc123.us-east-1.rds.amazonaws.com
5# Port: 5432
6# (No IP whitelisting needed - same VPC)
7
8# Database on same Docker host:
9# Host: host.docker.internal  (Docker Desktop)
10# Host: 172.17.0.1           (Linux Docker bridge default)
11# Port: 5432
12
13# Other service in Docker Compose:
14# Host: service_name  (uses Docker DNS)
15# Example: adding your own postgres container
16# host: my-app-postgres

Retool releases new versions regularly. Self-hosted instances use Docker image tags to manage versions. Retool's docker-compose.yml specifies the image version as a tag on the retool/retool image. To update, change the image tag to the new version number, run docker compose pull to download the new images, then docker compose up -d to restart containers with the new version. Retool's database migrations run automatically on startup — the api container applies any required schema changes to the internal Postgres database before accepting traffic. Always take a backup of the internal Postgres database before major version updates. The Retool release notes at docs.retool.com/changelog document breaking changes between versions. Self-hosted instances trail Cloud by approximately 2 weeks (Edge channel) or 13 weeks (Stable quarterly releases) — choose your update cadence based on your team's risk tolerance.

1# Update steps:
2
3# 1. Check current version
4docker compose exec api cat /usr/local/lib/node_modules/retool/package.json | grep version
5
6# 2. Backup internal Postgres before updating
7docker compose exec postgres pg_dump -U postgres hammerhead_production > retool_backup_$(date +%Y%m%d).sql
8
9# 3. Update version tag in docker-compose.yml:
10# image: tryretool/backend:3.XX.X
11
12# 4. Pull new images
13docker compose pull
14
15# 5. Restart with new version (brief downtime)
16docker compose up -d
17
18# 6. Watch migration logs
19docker compose logs -f api