Skip to content

Serve the game over HTTPS behind Caddy, harden the server, and gather the deployment docs - #57

Merged
lagergren merged 3 commits into
mainfrom
lagergren/https-deploy
Nov 7, 2026
Merged

lagergren merged 3 commits into
mainfrom
lagergren/https-deploy

Conversation

@lagergren

@lagergren lagergren commented Nov 7, 2026 •

Copy link
Copy Markdown
Owner

What

You can now put the bitmap game on the internet over HTTPS. A machine with Docker or Podman, a public address and a domain name needs one compose file and a .env; Caddy obtains and renews the certificate. The game server also gets the protections a public server needs. All deployment docs now live in one guide, deploy/README.md.

Commits

Refuse cross-site requests, limit failed logins, and know clients behind a proxy. Adds three pieces to web-common, which the bitmap server applies:

  • Same-origin check: any POST, and the /ws/play handshake, sent by another site's page is refused with 403. A request passes when it comes from the public URL, or, for other names such as a LAN address, from the Host the request was sent to.
  • Failed-login limit: after 10 failures from one client within 15 minutes, its logins get 429 with Retry-After. The block ends 15 minutes after the first failure, and a successful login clears the count.
  • Clients behind a proxy: RYLWEEN_TRUSTED_PROXIES (or --trusted-proxies) lists the proxies whose X-Forwarded-For is believed. The client is the nearest hop that isn't one of them, and it is never looked up in DNS. Requests and failed logins log it as client=.

Serve the game over HTTPS behind Caddy, with compose.https.yaml and ./deploy.sh --https.

  • deploy/compose.https.yaml runs the released image behind Caddy:
    • Caddy gets a Let's Encrypt certificate for RYLWEEN_DOMAIN, redirects HTTP to HTTPS, and adds HSTS, nosniff and no-referrer headers.
    • The game publishes no port. It gets secure cookies, its public URL, and Caddy's network as the trusted proxies.
    • Caddy runs from its reverse-proxy command, so there's no Caddyfile to manage.
  • ./deploy.sh --https pulls the latest release and starts it. It then waits up to three minutes for a valid certificate and prints the address and the commands to manage it.
  • Releases attach a compose.https.yaml pinned to their image, and the release notes link to the guide.

Plain HTTP stays the default everywhere.

Gather the deployment docs in deploy/README.md. One guide covers:

  • which way to run the game;
  • what deploy/ holds;
  • the local network over HTTP;
  • step by step, the internet over HTTPS: what the machine needs (public address and CGNAT check, domain, ports, software, certificates), setup, checking players' addresses, upgrades, backups, what it protects and what it doesn't, troubleshooting, router and IPv6 notes, other proxies, the ANSI image, and Tailscale.

It absorbs:

  • deploy/docker/README.md;
  • the bitmap runtime's deploy-script section;
  • the ANSI web runtime's production and router notes.

Those places now link to it. The root README gains one orientation line (play, host, change the game, code) and a pointer to the terminal zip in each release.

Testing

  • CI checks: all pass, with 270 tests (13 new) and none skipped. ktlint, actionlint and shellcheck are clean.
  • Live server: checked the hardening against the real launcher.
    • A cross-site login and a cross-site socket handshake get 403.
    • Ten failed logins get 401, then 429 with Retry-After: 899.
    • A forged X-Forwarded-For from an untrusted peer is ignored. Behind a trusted proxy, clients are counted and logged apart.
  • The full HTTPS stack, locally, with an image built from this branch. Caddy used its local CA for localhost, on high ports, since rootless Podman won't bind 80 and 443:
    • verified TLS over HTTP/2;
    • HTTP gets a 308 redirect to HTTPS;
    • HSTS, nosniff and no-referrer headers;
    • registering sets a Secure cookie;
    • the game page loads, and the WebSocket gets 101 through Caddy with its own origin and 403 with another;
    • a cross-site login gets 403;
    • ten failed logins, then 429.
  • Measured: the game uses about 236 MB of memory and Caddy about 13 MB.
  • Release copy: the yq rewrite of compose.https.yaml pins only the image.
  • Deploy script: ./deploy.sh --https without RYLWEEN_DOMAIN explains what to set, and it reads the name from deploy/.env, quoted or not.
  • Links: every relative link and anchor in the touched READMEs resolves.

Not tested yet: a real Let's Encrypt certificate on a public machine.

Found in testing, and documented in step 9 of the guide: rootless Podman (and Docker's userland proxy) hide players' addresses from Caddy. Every player then counts as one client for the login limit. Rootful Docker on Linux keeps the real addresses.

…ind a proxy

Three pieces in web-common, which the bitmap server now applies, for a
server on the internet:

- The same-origin check refuses, with 403, any POST and the game's
  WebSocket handshake that another site's page sends. The page must come
  from the public URL or, for other names such as a LAN address, from the
  Host the request was sent to.
- After 10 failed logins from one client within 15 minutes, its logins are
  refused with 429 and Retry-After until 15 minutes after the first. A
  successful login clears the count.
- RYLWEEN_TRUSTED_PROXIES (or --trusted-proxies) names the reverse proxies
  whose X-Forwarded-For is believed. The client is the nearest hop that is
  not one, never looked up in DNS, and every request and failed login logs
  it as client=.
…/deploy.sh --https

compose.https.yaml runs the released image behind Caddy, which gets and
renews a Let's Encrypt certificate for RYLWEEN_DOMAIN, redirects HTTP to
HTTPS, and adds HSTS, nosniff, and no-referrer. The game publishes no port;
it gets secure cookies, its public URL, and Caddy's network as the trusted
proxies.

./deploy.sh --https pulls the latest release, starts it, waits up to three
minutes for a valid certificate, and prints the address and the commands to
manage it. Each release attaches a compose.https.yaml pinned to its image,
and the release notes point to the guide.
deploy/README.md is now the one guide to running the game as a server: which
way to choose, what deploy/ holds, the local network over HTTP, and, step by
step, the internet over HTTPS, from what the machine needs (a public
address, a domain name, ports 80 and 443) to upgrades, backups, what it
protects, and troubleshooting. It takes in deploy/docker/README.md, the
deploy script's section of the bitmap runtime's README, and the production
and router notes of the ANSI web runtime's README, which now link to it. The
root README points newcomers at playing, hosting, changing the game, and the
code, and at the terminal zip in each release.
@lagergren
lagergren merged commit a1c6bc5 into main Nov 7, 2026
1 check passed
@lagergren
lagergren deleted the lagergren/https-deploy branch November 7, 2026 18:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant