Add docs/dns-and-tls.md: castle's DNS + TLS approach

A conceptual companion to registry.md's field-level gateway reference. Covers the
two questions (resolve / trust) an internal-only LAN service must answer:

- DNS: gateway-as-ingress, path-prefix vs host routes, LAN name resolution,
  wildcard records, split-horizon (internal names, no public A records), and the
  private-TLD vs public-subdomain zone styles with the worked router/wild-central
  topology.
- TLS: the three gateway.tls modes (off / internal / acme) with when-to-use, the
  internal-CA distribution pain vs the acme DNS-01 "no client setup" win, the
  secure-context (WebCrypto) rationale, the put-a-service-on-HTTPS recipe,
  operational prerequisites (443/80 bind, plugin caddy, DNS token, staging), and a
  decision table.

Linked from CLAUDE.md's docs list.
This commit is contained in:
2026-06-30 19:08:34 -07:00
parent d7c84e8d81
commit fa3a646064
2 changed files with 211 additions and 0 deletions

View File

@@ -41,6 +41,7 @@ verb commands and scaffold, but a program stands on its own via its declared
Stack guides (for writing *new* code, AI-facing):
- @docs/registry.md — Registry architecture, castle.yaml structure, lifecycle
- @docs/dns-and-tls.md — DNS + TLS approach: gateway routing, LAN name resolution, the three `gateway.tls` modes (off/internal/acme)
- @docs/stacks/python-fastapi.md — FastAPI service patterns (config, routes, models, testing)
- @docs/stacks/python-cli.md — CLI tool patterns (argparse, stdin/stdout, piping, testing)
- @docs/stacks/react-vite.md — React/Vite/TypeScript frontend patterns