docs: add reverse-proxy topology + external-TLS conventions

Capture the cert + edge-proxy conventions worked through deploying the
helexa-bench UI:

- external-tls.md — publicly-trusted certs via Let's Encrypt (certbot,
  Cloudflare DNS-01, ECDSA, /root/.certbot-internal); the external
  counterpart to internal-tls.md. Decision rule: public name → LE,
  *.internal → internal CA.
- reverse-proxies.md — names the per-site edge proxies (oolon for
  kosherinata, hanzalova.internal for the office) and what sits behind
  each, the public-vs-mesh access paths + the "public names don't
  hairpin from inside the mesh" gotcha, per-vhost cert choice, nginx
  conventions, and the bench (bench.helexa.ai + bench.internal) worked
  example.
- readme + generic.md §11 cross-reference both.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-06-14 15:50:57 +03:00
parent 200c41b4f1
commit 746c55fe94
4 changed files with 203 additions and 1 deletions

View File

@@ -13,6 +13,8 @@ The goal is boring consistency: the same crate layout, the same deploy flow, the
- **`generic.md`** — the baseline. Applies to every project unless that project explicitly overrides a section. Covers workspace layout, separation of concerns, configuration, secrets, deployment, service accounts, firewalld, SELinux, and code quality.
- **`deployment-gitea-actions.md`** — CI-driven deployment via a Gitea Actions workflow, as an alternative to the `deploy.sh` + `manifest.yml` flow in `generic.md` §7. The workflow is the source of infra truth; the runner deploys as a scoped `gitea_ci` user.
- **`internal-tls.md`** — provisioning and renewing per-service internal TLS certs (`<service>.internal`) for mesh-only nginx vhosts, extending the PKI conventions in `generic.md` §11.
- **`external-tls.md`** — publicly-trusted certs for WAN-facing vhosts via Let's Encrypt (certbot, Cloudflare DNS-01, ECDSA). The external counterpart to `internal-tls.md`.
- **`reverse-proxies.md`** — the per-site nginx edge proxies (`oolon` for kosherinata, `hanzalova.internal` for the office), what sits behind each, the public-vs-mesh access paths, and the per-vhost cert choice. Names the topology behind `generic.md` §11 Ingress.
More files will appear here over time as guidance that's more specific than `generic.md` gets extracted — per-stack, per-deployment-target, or per-problem-domain documents. When a project needs guidance that isn't generic, it belongs in a new file here, not buried in one project's repo.