Reverse Proxy Setup

🔀 Why a Reverse Proxy?

Tymeslot listens on port 4000 without SSL. A reverse proxy sits in front of it and handles three critical concerns:

• HTTPS termination — automatic Let's Encrypt certificates via Caddy or Certbot. Without HTTPS, browsers will refuse to connect.
• WebSocket proxying — Phoenix LiveView uses a persistent WebSocket connection to push real-time updates to the browser. Without it, the page loads but all live updates stop working.
• OAuth compatibility — Google, Microsoft, and GitHub all require HTTPS callback URLs. OAuth integrations will not work without it.

1 Option A — Caddy (Recommended)

Caddy provisions and renews Let's Encrypt certificates with zero configuration. No cron jobs, no manual renewal commands.

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 will be 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 30 seconds, Caddy will contact Let's Encrypt, obtain a certificate, and begin serving your domain over HTTPS. The first request to your domain may take a moment while the certificate is provisioned.

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:

URL_SCHEME=https
PHX_HOST=tymeslot.yourdomain.com

Restart Tymeslot after editing the file:

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

You should see the containers 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 in their browser, Phoenix LiveView immediately upgrades the HTTP connection to a WebSocket. This persistent channel is how the server pushes instant updates — booking confirmations, availability changes, form validation — without the browser needing to poll.

The upgrade happens via a special HTTP request with the header Upgrade: websocket. By default, most reverse proxies treat this as a normal HTTP request and strip the header. You must explicitly configure the proxy to pass it through.

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

⚖️ Running Behind a Load Balancer or CDN

For AWS ALB, Cloudflare, or similar setups, the outermost proxy forwards headers that inner proxies must pass through. Tymeslot trusts X-Forwarded-Proto to determine the request scheme for URL generation.

If using Cloudflare, navigate to [SSL/TLS] in the Cloudflare dashboard and set the mode to Full (strict). Using Flexible causes Cloudflare to connect to your origin over HTTP while telling the origin it connected over HTTPS — this produces redirect loops between Cloudflare and Caddy/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 — it should automatically redirect to the HTTPS version.
• A booking page opens and loads fully. Navigate to any public booking link — the page should render completely without a spinner stuck indefinitely.
• Real-time updates work. Log in and navigate to any LiveView page (such as the dashboard). Type in a search field — results should update immediately, confirming the WebSocket connection is live.
• Health endpoint returns 200. Visit https://tymeslot.yourdomain.com/healthcheck in a browser — it should return a plain 200 OK.