proposal(deploy): Switch to Caddy from Traefik and enable localhost run support

[lorenjohnson]

Summary

This PR extends the previous work of separating out the reverse proxy (Traefik) into a docker-compose.override.yml file so that it still runs by default, but the docker-compose.yml in the deploy directory can be used without a reverse proxy without modifying the file such that it can be kept on a viable upgrade path.

It further replaces Traefik with Caddy as the default reverse proxy.

The default docker compose up run, which always uses the docker-compose.override.yml if it exists, is currently in this branch set to run Caddy. Currently Traefik configuration and support is unchanged but requires to use it instead of Caddy requires:

docker compose -f docker-compose.yml -f docker-compose.traefik.yml

We could choose to simply deprecate Traefik, maintain optional support for it, or keep it as the default option with Caddy as the optional choice. We have options, but my recommendation is that we only maintain one reverse proxy option, and that we switch to Caddy.

Reasons for choosing Caddy:

• Simpler configuration — shorter and (arguably) clearer than Traefik’s.
• Easy certificate mode switching — Caddy makes it straightforward to toggle between using local development certificates and automatically generated Let’s Encrypt certificates.
• Lower runtime memory footprint — roughly half the size (~50 MB for Caddy vs. 100 MB+ for Traefik), though not benchmarked formally. This difference won’t heavily impact most servers, but is still worth noting.

New Feature: Local Certificate Generation (enables localhost support)

A new helper script, create-local-certs.sh, has been added to the root of the deploy directory.

Behavior:

• Reads WIKIBASE_PUBLIC_HOST and WDQS_PUBLIC_HOST from the local .env file.
• Requires mkcert. If mkcert is missing, the script will exit with instructions to the user with a link to installation instructions.
• Exits early with an explanation if .env is missing or either variable is unset, prompting the user to complete the WBS Deploy configuration step first.
• Exits early with an explanation if either host name doesn't end in the .test tld as this is the only reliable cross-platform localhost tld we support (see https://datatracker.ietf.org/doc/html/rfc2606)
• Automatically installs the mkcert local CA if needed.
• Generates properly named certificates in config/certs:
  • config/certs/<domain>.crt
  • config/certs/<domain>.key
• Automatically appends

  CADDY_TLS_FILE_PATH=./config/Caddyfile.files.tls

  to .env (only if not already present) so that Caddy switches to local certs mode.

Benefits

• Simpler reverse proxy configuration — Caddy configuration is more concise and easier to read/maintain.
• Potentially more efficient — lower memory usage than Traefik.
• Reverse proxy remains optional — the separation means other deployment environments can run without it.
• Streamlined local OAuth testing — with the new script, a user can run a fully functional local instance (including QuickStatements OAuth through MediaWiki) with only two additional steps beyond the normal configuration.
• Automatic domain-based cert generation — no manual domain entry required; the script uses the configured public host values.

How to Use

1. Add the .test domains from your .env to your /etc/hosts file so they resolve locally.
   These can be any .test domains you choose, as long as they match what is set in .env.
   For example:

   127.0.0.1 wikibase.test query.wikibase.test
   

2. Complete the WBS Deploy configuration step so .env contains:

   WIKIBASE_PUBLIC_HOST=wikibase.test
   WDQS_PUBLIC_HOST=query.wikibase.test

3. Install mkcert if not already installed.
4. From the deploy directory, run:

   ./create-local-certs.sh

5. Start your services:

   docker compose up

6. Caddy will automatically use the generated local certificates.

Remaining TODOs:

• Decide what to do with Traefik vs Caddy for reverse proxy in our Deploy product
• Update deploy/README.md to include instructions for running on localhost
• Update test code config if needed
• Consider changing default domains for Deploy to *.test from *.example (not at all sure this is correct, but it might be)
• Note: Includes Deploy local images dev helper in feat(deploy): Adds dev-centric option for using local builds #890

[rti]

I agree that one proxy is enough. I see no value but more work in maintaining two.

Additional cost of switching the proxy is the exploration and documentation of the migration path for our users. Before deciding I would also like to understand what it takes to implement the "local dev cert" mechanism on traefik. I suppose a mechanism similar to the one proposed in this PR for caddy would work for traefik too.