Skip to content

Deploy

HTTPS and proxies

Serve Knotworking on a domain with automatic certificates, or behind your own reverse proxy.

On a domain

Point a domain at the server and tell Caddy about it. It gets and renews a Let's Encrypt certificate by itself. HTTPS adds a second Compose file that publishes port 443.

deploy/.env
DOMAIN=knot.example.com
APP_URL=https://knot.example.com
HTTP_PORT=80
COMPOSE_FILE=compose.yaml:compose.https.yaml
terminal
docker compose --env-file deploy/.env up -d

Open ports 80 and 443. Port 80 is needed for issuing certificates and for redirects. COMPOSE_FILE makes every later command use both files; never run up with only compose.yaml on an HTTPS installation, or Caddy loses port 443. Calendar sync needs HTTPS on a real domain.

On a local network

On a local network, plain HTTP is fine. Leave DOMAIN and COMPOSE_FILE unset, and only the HTTP port is published, so a machine that already uses 443 works as it is.

Behind another proxy

Caddy records each visitor's address in X-Forwarded-For, which sign-in rate limits rely on. If you put another proxy or load balancer in front of Caddy:

  • Have it overwrite X-Forwarded-For, or raise TRUSTED_PROXIES on the web service to the number of proxies.
  • Turn off buffering and compression for /api/v1/workspaces/*/events, so live updates arrive at once (nginx: proxy_buffering off;).
  • Allow request bodies at least as large as UPLOAD_MAX_BYTES plus about 64 KB.
  • Forward /mcp with its Host header and body untouched.

If people report being locked out at random, check this first: when the client address can't be worked out, everyone shares one rate-limit bucket.

Security headers

The bundled Caddyfile sends X-Content-Type-Options, X-Frame-Options and Referrer-Policy, removes the Server header, and adds Strict-Transport-Security on HTTPS connections only. There is deliberately no Content-Security-Policy; add one in your own proxy only after testing every page, the document editor included.