Reverse Proxy Setup

📋 Before You Begin

🔀 Why a Reverse Proxy?

Tymeslot listens on port 4000 over plain HTTP. A reverse proxy sits in front of it and handles three things:

• HTTPS termination with free Let's Encrypt certificates from Caddy or Certbot. Without HTTPS nobody can sign in: production session cookies are marked Secure, so browsers send them only over HTTPS.
• WebSocket proxying so the browser can keep its WebSocket connection open. Phoenix LiveView uses it to push updates to the page; without it, the page loads but nothing on it responds.
• OAuth compatibility for providers that accept only HTTPS callback URLs. Google and Microsoft reject plain HTTP callbacks for anything other than localhost.

1 Option A: Caddy (Recommended)

Caddy obtains and renews Let's Encrypt certificates on its own, with no configuration and no renewal jobs to schedule.

Install Caddy

Run the following on your server (Ubuntu/Debian):

apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' \
  | gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' \
  | tee /etc/apt/sources.list.d/caddy-stable.list
apt update && apt install caddy

You should see Setting up caddy in the output, and the Caddy service is enabled automatically.

Create the Caddyfile

Open /etc/caddy/Caddyfile in your editor and replace its contents with:

tymeslot.yourdomain.com {
    reverse_proxy localhost:4000
    encode gzip
}

Reload Caddy to apply the configuration:

sudo systemctl reload caddy

Within about 30 seconds, Caddy contacts Let's Encrypt, obtains a certificate and starts serving your domain over HTTPS. The first request may take a moment while the certificate is issued.

2 Option B: Nginx + Certbot (Alternative)

Use this if Nginx is already installed on your server or required by your infrastructure team.

Install Nginx and Certbot

apt install nginx certbot python3-certbot-nginx

You should see both nginx and certbot listed as newly installed packages.

Create the site configuration

Create the file /etc/nginx/sites-available/tymeslot with the following contents. The Upgrade and Connection headers in the location block are essential: they tell Nginx to forward WebSocket upgrade requests to Tymeslot rather than dropping them:

server {
    listen 80;
    server_name tymeslot.yourdomain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name tymeslot.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/tymeslot.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/tymeslot.yourdomain.com/privkey.pem;

    location / {
        proxy_pass http://localhost:4000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 86400;
    }
}

Enable the site and obtain a certificate

# Symlink the config into sites-enabled
ln -s /etc/nginx/sites-available/tymeslot /etc/nginx/sites-enabled/

# Obtain a Let's Encrypt certificate (Certbot edits the config automatically)
sudo certbot --nginx -d tymeslot.yourdomain.com

# Test the config and reload
nginx -t && systemctl reload nginx

After certbot completes, you should see Congratulations! and the path to your new certificate. The nginx -t command should return syntax is ok and test is successful.

3 Update Environment Variables

Now that Tymeslot is behind HTTPS, update your .env file so the application generates correct URLs for emails, OAuth callbacks and links. https is already the default for URL_SCHEME; setting it makes the choice explicit:

URL_SCHEME=https
PHX_HOST=tymeslot.yourdomain.com

Recreate the container so it picks up the change:

docker-compose down && docker-compose up -d

The containers should start cleanly. Check docker-compose logs tymeslot if the application does not come up within 15 seconds.

⚡ WebSocket Support Explained

When a visitor opens Tymeslot, Phoenix LiveView opens a WebSocket connection alongside the page. The server uses it to push updates (booking confirmations, availability changes, form validation) without the browser polling.

The connection starts as an HTTP request with the header Upgrade: websocket. Nginx, by default, treats it as a normal request and drops that header, so you must tell it to pass the header through. Caddy and Traefik do this automatically.

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

⚖️ Running Behind a Load Balancer or CDN

Behind AWS ALB, Cloudflare or a similar layer, each inner proxy must pass on the headers the outer one adds. Tymeslot reads the visitor's address from X-Forwarded-For or X-Real-IP for rate limiting. It does not read X-Forwarded-Proto: generated URLs take their scheme from URL_SCHEME, however many proxies sit in front.

If you use Cloudflare, go to [SSL/TLS] in the Cloudflare dashboard and set the mode to Full (strict). Using Flexible makes Cloudflare connect to your origin over HTTP while the browser sees HTTPS, which produces redirect loops between Cloudflare and Caddy or Nginx.

❓ Frequently Asked Questions

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

docker-compose ps
docker-compose logs tymeslot

URL_SCHEME=https
PHX_HOST=tymeslot.yourdomain.com

Verify Your Setup

• HTTPS loads without a certificate warning. Visit https://tymeslot.yourdomain.com in your browser. The address bar should show a padlock icon.
• HTTP redirects to HTTPS. Visit http://tymeslot.yourdomain.com and check that it redirects to the HTTPS version.
• A booking page opens and loads fully. Open any public booking link. The page should render completely, with no spinner stuck on screen.
• Real-time updates work. Log in and open the dashboard calendar. Type in its search box: results that update as you type confirm the WebSocket connection is live.
• The health endpoint returns 200. Visit https://tymeslot.yourdomain.com/healthcheck in a browser. It should return a short JSON report with "status": "ok".