docs: document shared PK01 Caddy blocks

2026-06-13 14:26:15 +00:00
parent b1ff102e1d
commit c324200ecf
4 changed files with 18 additions and 2 deletions
@@ -91,6 +91,10 @@ App-specific transforms are allowed only as isolated named transform functions.

 Public exposure must be declared as an edge topology, including DNS expectation, public base URL, bridge settings, edge host route and target service. The existing FRP/Caddy path is a reusable public-service primitive. New public exposure code should extend that primitive instead of adding per-service Caddy or FRP scripts.

+When several YAML owners render into the same Caddyfile, each owner must write only its own managed site block and merge it with the existing file. A shared writer must preserve other `# BEGIN unidesk managed <owner>` blocks, remove only legacy unmanaged blocks for the domains owned by the current operation, validate the merged Caddyfile before install, and then reload Caddy. A domain CLI must not replace a shared Caddyfile with a file rendered from its own YAML alone.
+
+Shared Caddyfile operations belong in a common helper module under `scripts/src/`. Service-specific CLIs should pass YAML-resolved domains, upstreams and marker names to that helper, then report the managed-block counts and validation result. Full-file Caddy installs are allowed only for a host or file that the command exclusively owns and whose exclusivity is documented in the owning reference.
+
 ### Database Blocks

 External database consumers must reference the YAML-owned platform database source and exported Secret shape. A consumer should not deploy a new database, copy connection strings by hand, or derive credentials from live runtime objects unless the owning database YAML declares that export.
@@ -122,6 +126,7 @@ Avoid these patterns:
 - hard-coding node ids, service ids, namespaces, ports, URLs, Secret names or workload names in code
 - deriving live state by string conventions when YAML can declare the object directly
 - keeping repeated `kubectl apply`, Caddy edits, FRP edits or rollout restarts as runbook shell snippets
+- replacing a shared Caddyfile from one YAML owner without preserving other managed blocks
 - printing secret values, complete env files, full `DATABASE_URL` values or reusable API keys
 - writing long-term docs that duplicate current YAML values as prose
 - using contract tests or hidden guards to freeze policy values that should remain YAML-controlled