nginx

A minimal nginx config to put Perch behind HTTPS. The one thing you can’t skip is passing WebSocket upgrades through, otherwise the live dashboard (/ws/live) and container log streaming (/ws/logs) won’t work. The config below proxies everything under /, so both are covered.

Config

perch.conf

server {
    listen 80;
    server_name metrics.example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name metrics.example.com;

    ssl_certificate     /etc/letsencrypt/live/metrics.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/metrics.example.com/privkey.pem;

    location / {
        proxy_pass http://localhost:8484;
        proxy_http_version 1.1;

        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;

        # WebSocket support (live dashboard + container logs)
        proxy_set_header Upgrade    $http_upgrade;
        proxy_set_header Connection "upgrade";

        # Keep WebSocket connections alive
        proxy_read_timeout 3600s;
    }
}

Forward the headers, set the base URL

Perch reads X-Forwarded-Proto and X-Forwarded-Host to build OAuth callback URLs. Forwarding them (like above) plus setting PERCH_BASE_URL keeps sign-ins working correctly behind the proxy.

Getting a certificate with Certbot

certbot.sh

apt install certbot python3-certbot-nginx
certbot --nginx -d metrics.example.com

Certbot updates your nginx config automatically and sets up auto-renewal, so you can pretty much forget about it.

Set PERCH_BASE_URL

Once Perch is behind a proxy, set PERCH_BASE_URL in your .env so OAuth callbacks resolve to the right place:

.env

PERCH_BASE_URL=https://metrics.example.com

Then restart the hub:

bash

docker compose restart hub