How to Set Up Custom Domains for Retool Apps

1# Example DNS record configuration (varies by registrar UI):
2# Type: CNAME
3# Name: tools
4# Value: abc123.retool.com
5# TTL: 3600 (1 hour)
6
7# For AWS Route 53:
8# Record type: CNAME
9# Record name: tools.yourcompany.com
10# Value: abc123.retool.com
11# TTL: 300
12
13# Verify DNS propagation (run in terminal or use online tools):
14# dig CNAME tools.yourcompany.com
15# Expected output: tools.yourcompany.com CNAME abc123.retool.com

1# Check for CAA records that might block SSL:
2# dig CAA yourcompany.com
3
4# If you see a CAA record like:
5# yourcompany.com CAA 0 issue "sectigo.com"
6# You need to add Let's Encrypt to the allowed issuers:
7# yourcompany.com CAA 0 issue "letsencrypt.org"
8
9# Verify HTTPS is working after certificate provisioning:
10# curl -I https://tools.yourcompany.com
11# Expected: HTTP/2 200 (not SSL error)

1# /etc/nginx/sites-available/retool
2
3server {
4    listen 80;
5    server_name tools.yourcompany.com;
6    
7    # Redirect HTTP to HTTPS
8    return 301 https://$host$request_uri;
9}
10
11server {
12    listen 443 ssl http2;
13    server_name tools.yourcompany.com;
14    
15    # SSL certificates from Let's Encrypt
16    ssl_certificate /etc/letsencrypt/live/tools.yourcompany.com/fullchain.pem;
17    ssl_certificate_key /etc/letsencrypt/live/tools.yourcompany.com/privkey.pem;
18    
19    # Modern SSL settings
20    ssl_protocols TLSv1.2 TLSv1.3;
21    ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384;
22    ssl_prefer_server_ciphers on;
23    ssl_session_cache shared:SSL:10m;
24    
25    # Security headers
26    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
27    add_header X-Frame-Options SAMEORIGIN;
28    
29    # Proxy to Retool container
30    location / {
31        proxy_pass http://localhost:3000; # Retool's default port
32        proxy_http_version 1.1;
33        proxy_set_header Upgrade $http_upgrade;
34        proxy_set_header Connection 'upgrade';
35        proxy_set_header Host $host;
36        proxy_set_header X-Real-IP $remote_addr;
37        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
38        proxy_set_header X-Forwarded-Proto $scheme;
39        proxy_cache_bypass $http_upgrade;
40        proxy_read_timeout 86400; # 24h for long-running operations
41    }
42}

1# docker-compose.yml addition:
2# (Add to your existing Retool docker-compose)
3
4services:
5  https-portal:
6    image: steveltn/https-portal:1
7    ports:
8      - '80:80'
9      - '443:443'
10    environment:
11      DOMAINS: 'tools.yourcompany.com -> http://retool:3000'
12      STAGE: 'production'  # Use 'local' for testing, 'production' for Let's Encrypt
13      # FORCE_RENEW: 'true'  # Uncomment to force certificate renewal
14    volumes:
15      - https-portal-data:/var/lib/https-portal
16    depends_on:
17      - retool
18    restart: always
19
20volumes:
21  https-portal-data:
22
23# Note: In STAGE: 'production', Let's Encrypt rate limits apply.
24# Use STAGE: 'staging' first to test the setup without hitting rate limits.

1# In Retool's .env or docker-compose.yml environment section:
2BASE_DOMAIN=tools.yourcompany.com
3COOKIE_INSECURE=false  # Set to false when using HTTPS
4
5# If using OAuth (Google, GitHub, etc.) for Retool login,
6# update your OAuth app's authorized redirect URIs to include:
7# https://tools.yourcompany.com/oauth/callback
8
9# Restart Retool after changing BASE_DOMAIN:
10# docker-compose down && docker-compose up -d