docs: capture hwlab opencode public edge lessons

2026-06-30 01:06:35 +00:00
parent c9c5b5eaf7
commit c53b3a770a
2 changed files with 10 additions and 0 deletions
@@ -203,6 +203,8 @@ PK01 `/etc/caddy/Caddyfile` is a shared edge artifact for multiple YAML owners,

 Do not render and install a whole PK01 Caddyfile from a single service YAML. Sub2API, LangBot, n8n, HWLAB and future public services must coexist by distinct `# BEGIN unidesk managed <owner>` blocks. When the same service exposes multiple public targets at once, the Caddy owner must be target-scoped unless an existing legacy owner is intentionally preserved for backward compatibility; for Sub2API, D601 keeps the legacy `sub2api` block and non-default targets use owners such as `sub2api-d518`. A public exposure closeout should verify the service's own public URL and, when the operation touched PK01 Caddy, confirm that unrelated managed blocks are still present or that the apply output reports they were preserved.

+When one Caddy site has both path-specific upstreams and a catch-all upstream, render the path routes inside `handle @matcher { ... }` blocks and put the default upstream in a final `handle { ... }` block. Do not rely on `reverse_proxy @matcher ...` followed by an unqualified `reverse_proxy ...`: the catch-all route can still capture matcher paths after Caddy adapts the file. Validation must include both `caddy adapt`/`validate` and loopback HTTPS or local-port probes for at least one matcher path and one catch-all path; if a matcher path returns the catch-all service's response, treat it as an edge routing bug rather than an application health failure.
+
 ## Availability And Probes

 Kubernetes readiness is not the same as pool availability: