Skip to content

Trusted HTTPS & TLS

What this is

How to put a trusted certificate and a stable public origin in front of PiHerder itself (via bundled Caddy or an outer reverse proxy).

This is PiHerder’s own edge TLS. The fleet certificate vault (Catalog → Certificates) is separate: it stores PEMs encrypted and deploys them to other hosts over SSH (and optionally to this Caddy edge via a self-managed mapping). See Managed certificates.

Why it matters

Android installable PWA and Web Push need a secure context with a trusted certificate and a stable origin. Self-signed Caddy (Caddyfile.dev / tls internal) is fine for desktop poking; it is not reliable for push on phones. Correct edge TLS also feeds accurate client IP into Audit when Caddy is the edge.

Hostname and public URL

In .env (compose loads these for web and caddy):

PIHERDER_HOSTNAME=piherder.example.com
# Include :8443 when using compose host mapping 8443→443
PIHERDER_PUBLIC_URL=https://piherder.example.com:8443
  • DNS: point PIHERDER_HOSTNAME at the host (or your outer reverse proxy).
  • Ports (default compose): HTTP 8888→80, HTTPS 8443→443. App :8000 is loopback only.
  • PIHERDER_PUBLIC_URL is also the only origin used for email password-reset links and the OIDC redirect base. Host / X-Forwarded-Host are ignored for those URLs.

Preferred: from Catalog vault (no SSH)

If the cert is already in Catalog → Certificates (NPM pull or Upload PEM):

  1. Open the cert detail.
  2. Click Apply to this PiHerder.
  3. PiHerder writes certs/fullchain.pem + certs/privkey.pem and POSTs the Caddyfile to Caddy admin /load with Cache-Control: must-revalidate so volume-mounted PEMs are re-read (an unchanged Caddyfile alone is a no-op).

This is not a fleet service map — it only updates this instance’s edge. Fleet maps still deploy to other hosts over SSH.

Renewal: a successful Apply turns on the self-managed edge mapping. While that mapping is on, scheduled NPM auto-renew (and manual Renew) re-applies to Caddy with fleet maps. Use Remove mapping on the cert page to stop edge auto re-apply without deleting files under certs/.

Manual place + restart

  1. Place PEMs in certs/ (gitignored):
File Role
certs/fullchain.pem Certificate + chain
certs/privkey.pem Private key
  1. SANs on the cert must include PIHERDER_HOSTNAME.
  2. Permissions (recommended on the host):
chmod 600 certs/privkey.pem
chmod 644 certs/fullchain.pem
  1. Restart Caddy:
docker compose up -d caddy
  1. Browser should show a trusted lock for PIHERDER_PUBLIC_URL.

Also see the repo certs/README.md and Managed certificates.

Outer reverse proxy (NPM, etc.)

You may terminate TLS at Nginx Proxy Manager (or similar) and reverse-proxy to web:8000 or to Caddy. Keep:

  • A stable public origin in PIHERDER_PUBLIC_URL
  • Correct X-Forwarded-For / client IP for API token IP allowlists and Audit trail source IP (PiHerder honours CF / XFF / X-Real-IP only when the TCP peer is in PIHERDER_TRUSTED_PROXY_CIDRS)

Bundled Caddy overwrites those headers with the true client — prefer it as the edge for accurate audit IPs.

Local development without certs

# Example: use Caddyfile.dev in compose override
# (see project Caddyfile.dev — self-signed)

Push and reliable mobile install need real trusted HTTPS.

Next

Configure PWA & Web Push after TLS works.