Behind Traefik, Caddy or nginx

To serve Wharfbase on a domain with HTTPS through an existing Traefik, keep port 8480 off the internet and let Traefik route to it.

1. Install with the port bound to localhost and the public URL set:

   curl -fsSL https://fleeq.net/wharfbase/get | sh -s -- --bind 127.0.0.1 --public-url https://db.example.com

   With an https:// public URL, Wharfbase marks its session cookie Secure and sends HSTS.

2. Put a docker-compose.override.yml next to /opt/wharfbase/docker-compose.yml that joins Traefik’s network and adds the labels (adjust traefik, websecure and letsencrypt to your setup):

   services:
     wharfbase:
       environment:
         # Only Traefik can reach Wharfbase, so its X-Forwarded-For is trusted
         # (client IPs in the audit log and rate limits). A CIDR list works too.
         WB_TRUST_PROXY: "true"
       networks:
         - traefik
       labels:
         traefik.enable: "true"
         traefik.docker.network: traefik
         traefik.http.routers.wharfbase.rule: Host(`db.example.com`)
         traefik.http.routers.wharfbase.entrypoints: websecure
         traefik.http.routers.wharfbase.tls.certresolver: letsencrypt
         traefik.http.services.wharfbase.loadbalancer.server.port: "8480"
   
   networks:
     traefik:
       external: true

3. Tell compose to use it: add it at the end of COMPOSE_FILE in /opt/wharfbase/.env, then run wharfbase up:

   COMPOSE_FILE=docker-compose.yml:docker-compose.override.yml

   The installer (and wharfbase upgrade) keeps files you add to that line, and adds docker-compose.override.yml by itself when the file exists.

WebSockets (live updates at /ws) and wb shell (an HTTP upgrade at /api/v1/shells/attach) need no extra configuration in Traefik. Nothing in Wharfbase needs a path prefix: give it its own host name.

Caddy or nginx

The same idea: bind to 127.0.0.1, set WB_PUBLIC_URL and WB_TRUST_PROXY, and proxy to 127.0.0.1:8480 with WebSocket upgrades allowed:

db.example.com {
    reverse_proxy 127.0.0.1:8480
}

location / {
    proxy_pass http://127.0.0.1:8480;
    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-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    # An idle `wb shell` session would otherwise be cut after 60 s.
    proxy_read_timeout 1h;
}

Without a reverse proxy

Wharfbase can serve HTTPS itself, with a certificate you already have:

WB_TLS_CERT_FILE=/certs/fullchain.pem
WB_TLS_KEY_FILE=/certs/privkey.pem
WB_PUBLIC_URL=https://db.example.com:8480

Mount the folder into the container read-only (- /etc/letsencrypt/live/db.example.com:/certs:ro, or wherever your certificates are) and restart.

• What it checks: the files must be PEM, the certificate with its chain, and the key must match it, or Wharfbase doesn’t start (CONFIG_INVALID).
• Renewals: when the files change, the new certificate is used within 10 minutes, with no restart. A renewal that’s broken or half-written keeps the current one.
• Cookies: the session cookie is Secure.

Wharfbase doesn’t get or renew certificates itself, so a proxy with automatic certificates (Caddy, Traefik) is usually less work.