RFC: Caddy as an opt-in web server provider — two architectures, a request for direction

[masonjames]

Caddy support has been requested since January 2025 (#1246, steady +1s since). Two implementations now exist, built on fundamentally different architectures. Before more code gets written, this RFC asks the maintainers for a direction call.

The two architectures

A. Label-driven (caddy-docker-proxy) — @Siumauricio's feat/caddy branch (April 2025, ~354 lines). Caddy runs with the caddy-docker-proxy module; routes come from container labels, mirroring how Dokploy already drives Traefik's docker provider.

B. Central config generation — PR #4534. Dokploy's database stays the source of truth; the server generates a complete Caddy JSON config (one fragment per domain), validates it, and reloads via Caddy's admin API. Includes guarded Traefik→Caddy migration tooling with dry-run/apply/rollback.

Honest comparison

Dimension	A: label-driven	B: central config generation
Config ownership	Distributed across container labels; runtime assembles config	Dokploy DB → deterministic generated artifact; diffable, inspectable before reload
Code footprint	Very small (~354 lines prototyped); most logic lives in the caddy-docker-proxy module	Large (~11k source lines incl. migration tooling + UI); ~200 tests
External dependency	Depends on third-party caddy-docker-proxy plugin staying maintained/compatible	Vanilla caddy image only
Swarm support	Supported by the plugin; cross-node behavior depends on plugin event handling	Explicit upstream service-name generation; running on a 2-node swarm in production (below)
Existing Traefik installs	No migration story for Dokploy's file-provider dynamic configs (middlewares, manual fragments) — labels can't express them	Migration translates dynamic files + compose labels, with preflight, blocking warnings, and rollback snapshots
Cert handling	Caddy automatic HTTPS (same either way)	Same, plus custom-cert path (proposal: additive column rather than reusing customCertResolver)
Blast radius if buggy	Small surface, but failures occur at runtime inside the plugin (harder to pre-validate)	Larger surface, but config is validated as an artifact before reload; fail-closed guards
Maintenance cost for Dokploy team	Lowest — clear win for A	Higher; offset by tests, but real

A is genuinely simpler and matches Dokploy's existing label mental model. B's bet is that for a provider switch (not greenfield), correctness lives in the migration path — and that a generated, validated artifact is easier to support than emergent label state. Both are defensible; that's exactly why this needs a maintainer call.

"Why Caddy at all?" — answering @russorat directly

Fair question, asked on #1246. Concrete answers from running PR #4534's provider in production since 2026-06-01 (2-node swarm, ~30 services, ~40 domains, Cloudflare in front):

• Automatic HTTPS with fewer moving parts — no ACME resolver/entrypoint/router wiring; cert sharing works without Traefik Enterprise (the original pain in caddy support #1246).
• HTTP/3 out of the box.
• Observability — native Prometheus metrics (we scrape :2020, internal-only) and a queryable admin API showing the exact live config.
• Debuggability — one generated JSON artifact per state; we diff configs across deploys.

Honest caveats: the Coolify note russorat linked is about support burden, not a technical defect — and that concern is valid here too. So: Traefik stays the default, untouched. Caddy is opt-in behind a guarded migration. Our own first cutover attempt (2026-05-23) failed and rolled back — unresolved swarm DNS names, a portless upstream, an IP-allowlist route going public — which is precisely why the migration tooling is now fail-closed (live upstream preflight, blocking warnings, rollback snapshots). Second cutover succeeded; no provider-caused edge incidents since.

Current state of PR #4534

120 files / +27,881 looks unreviewable, but: ~8.5k is a generated Drizzle snapshot, ~7.8k is tests (29 new test files), ~500 is docs. Real source is ~11k — still large, hence the split below. (The size:XS auto-label is wrong; the labeler appears to have mis-sized it.) CI has never run — first-time-contributor workflow approval was never granted.

Proposed stacked split

Rather than asking anyone to review #4534 as-is:

1. PR 1 — provider-neutral web-server abstraction + domain lifecycle fixes (~2–3k lines). Zero behavior change, Traefik-only. Extracts the ~900-line settings-router additions into a webServerRouter, and fixes two existing upstream bugs found during this work: compose domains bypassing route refresh, and preview-deployments hardcoding the provider path. Valuable even if Caddy is rejected.
2. PR 2 — fail-closed runtime Drizzle migrations (~80 lines + test). Standalone correctness fix.
3. PR 3 — Caddy core (opt-in, no UI; additive cert column instead of reusing customCertResolver).
4. PR 4 — migration tooling (dry-run/apply/rollback/preflight).
5. PR 5 — UI, trusted proxies, request analytics.

PRs 3–5 only proceed if the answer to the architecture question is B (or "B, modified").

The ask

1. Direction: label-driven (A), central generation (B), a hybrid, or "no Caddy" — any clear answer lets everyone stop guessing.
2. CI: approve workflow runs on feat: add Caddy web server provider #4534 so there's a green/red signal to discuss against.
3. Plan review: does the stacked split above fit how you'd want this reviewed? Happy to open PR 1 first and park the rest.

I'll keep running this in production either way and can share configs, metrics, or failure reports on request.