Networking

Traefik fronts the dev compose stack and provides TLS-terminated host-based routing. Every dev URL is https://*.dev.katforge.com:4443, mirroring the production hostname structure.

Dev URLs

hearth urls prints this list with current ports:

$ hearth urls
katforge.com   https://dev.katforge.com:4443
api            https://api.dev.katforge.com:4443
stumper        https://dev.stumper.gg:4443
lextris        https://dev.lextris.com:4443
geargoblins    https://dev.geargoblins.com:4443
mercure        https://mercure.dev.katforge.com:4443
pgadmin        https://pgadmin.dev.katforge.com:4443
traefik        https://traefik.dev.katforge.com:4443

hearth hosts apply adds these names to your hosts file so the browser resolves them locally.

Ports

Traefik binds to 4442 (HTTP) and 4443 (HTTPS) by default. HTTP requests are 301-redirected to HTTPS, so typing http://dev.katforge.com:4442 lands on https://dev.katforge.com:4443.

Why not 80/443? Both ports are routinely occupied on a dev machine — by jwilder/nginx-proxy, by other compose stacks, by anything running as root. Sequential 4442/4443 is easy to remember and conflict-free.

To drop the suffix and use bare URLs, free 80/443 on the host and override:

KATFORGE_PROXY_PORT=80 KATFORGE_PROXY_TLS_PORT=443 hearth up

TLS

HTTPS uses an mkcert-issued local certificate generated by hearth setup. The same step imports the local CA into your trust store, so browsers don't show warnings.

hearth setup covers Linux and Windows-on-WSL automatically. On macOS, drag ~/.katforge/hearth/certs/rootCA.pem into Keychain Access → System and mark it "Always Trust" for SSL. On vanilla Linux distros, copy the same file to /usr/local/share/ca-certificates/katforge-root.crt and run sudo update-ca-certificates.

Apple OAuth caveat

"Sign in with Apple" requires HTTPS on port 443 with no port suffix. The default :4443 setup won't satisfy that; Apple's authorization server refuses to redirect to a non-standard port.

Discord, Google, Steam, and everything else are unaffected. If you need Apple OAuth working locally:

sudo systemctl stop nginx       # or whatever's holding 443
KATFORGE_PROXY_TLS_PORT=443 hearth up

/etc/hosts

hearth hosts apply       # add the katforge block
hearth hosts show        # show current entries
hearth hosts remove      # remove the katforge block

hearth hosts writes a marked block (# === BEGIN katforge === / # === END katforge ===) and only touches lines inside it. Re-running apply is idempotent — it rewrites the block in place.

On WSL, it edits both the Linux /etc/hosts and the Windows hosts file (C:\Windows\System32\drivers\etc\hosts) so browsers running on the host resolve dev domains. Running on Windows requires elevation; hearth hosts apply prompts for it.

Production routing

Production routes through Traefik bundled with k3s, with Let's Encrypt for SSL via the Route53 DNS challenge. See Deployment for the production routing surface.