alee/rutster
0
0
Fork 0
Code Issues Pull Requests 2 Actions Packages Projects Releases Wiki Activity

deploy slice G (docs + ADR-0011): docs/deploy/ tree + ADR-0011 Proposed #23

Merged
alee merged 8 commits from deploy-g/docs-adr-0011 into docs/deployment-topology-spec 2026-07-06 04:07:27 +00:00
Conversation 0 Commits 8 Files Changed 8 +912
alee commented 2026-07-06 03:15:54 +00:00
Owner
Copy Link

What lands

  • ADR-0011 (deployment topology, Status: Proposed) drafted verbatim-faithful to spec section 2-4 in the house ADR format established by ADR-0007/0008 (bullet-list header -> Context -> Decision -> Consequences -> References).
  • 6-file docs/deploy/ tree: topologies.md + quickstart-docker.md + homelab.md + aws.md + reverse-proxies.md + certificates.md. Sourced from the spec + the TLS brief; every factual third-party claim cites the brief's external source URL inline.
  • docs/QUICKSTART.md minimal-diff pointer to the new Docker fast path (5 insertions, 0 deletions).
  • Spec section 10 acceptance bar: every topology doc contains a copy-paste path from zero to first call OR the honest statement of what cannot work there (e.g. CGNAT WebRTC for homelab.md users behind a CGNAT).

ADR-0011 Status: Proposed (not Accepted)

  • Ratification is a separate maintainer step. This slice ships ADR-0011 Proposed; the maintainer promotes to Accepted in a separate commit after epoch review.

Cross-check step

  • At the start of each doc task ran 'ls deploy/' in the worktree. deploy/ was absent on this branch (Plan B not landed here) for all 8 tasks; docs stand on spec section 6.1 names (already reconciled to git.adlee.work/alee/rutster-*). If Plan B lands before merge a follow-up reconciliation pass can run.

Citation discipline

  • Every docs/deploy/ file's factual third-party claim cites the TLS brief's external source URL inline (Twilio errors 31910/11237, Twilio security page, Twilio SSL-termination blog, LE rate-limits, Caddy #6420/#7222, cloudflared #1465/#1282, livekit/agents #3379, ngrok pricing, HAProxy #2280, Traefik #10601/#11405). Brief URL gaps: none.

Seam invariant

  • Plan G is docs-only. git diff main --name-only | grep -E 'crates/rutster-media/src/(loop_driver|rtc_session).rs' -> 'seam intact' (verified in final sweep). Files touched: docs/QUICKSTART.md + docs/adr/0011-deployment-topology.md + docs/deploy/{topologies,quickstart-docker,homelab,aws,reverse-proxies,certificates}.md only.

Repo gates

  • cargo fmt --all --check: green. cargo clippy --all --all-targets -- -D warnings: green. cargo test --all: green. cargo deny check: deferred to CI (local cargo-deny 0.18.3 has pre-existing deny.toml:84 TOML parse failure on GPL-3.0-or-later; CI runs cargo-deny 0.19.x via EmbarkStudios/cargo-deny-action@v2 which parses fine -- PM has surfaced to user separately).

8 commits (all DCO signed off)

  • 538b059 docs(adr): ADR-0011 deployment topology (Proposed) (slice-G)
  • 285f205 docs(deploy): topologies.md three blessed shapes + decision guide (slice-G)
  • 1be6112 docs(deploy): quickstart-docker.md T1 docker run + T2 compose zero to first call (slice-G)
  • 33c3a14 docs(deploy): homelab.md CGNAT truth PSTN-only + VPS+WireGuard graduation (slice-G)
  • a0b3e24 docs(deploy): aws.md ALB appendix three mandatory overrides never NLB-TLS (slice-G)
  • 6c8c754 docs(deploy): reverse-proxies.md BYO nginx/HAProxy/Traefik tuned-timeout configs (slice-G)
  • 0e415c7 docs(deploy): certificates.md ACME paths /data persistence wildcard traps (slice-G)
  • 5546613 docs: QUICKSTART points at deploy/quickstart-docker.md as the fast path (slice-G)

Merge instructions

  • squash-merge (independent branch, no stacked-branches case in this epoch)
  • DCO signoff every commit (8/8 confirmed)
  • after merge: maintainer tags docs/deployment-topology-spec: deploy-g-docs-adr-0011-merged; separately promotes ADR-0011 Proposed -> Accepted after epoch review
## What lands - ADR-0011 (deployment topology, Status: Proposed) drafted verbatim-faithful to spec section 2-4 in the house ADR format established by ADR-0007/0008 (bullet-list header -> Context -> Decision -> Consequences -> References). - 6-file docs/deploy/ tree: topologies.md + quickstart-docker.md + homelab.md + aws.md + reverse-proxies.md + certificates.md. Sourced from the spec + the TLS brief; every factual third-party claim cites the brief's external source URL inline. - docs/QUICKSTART.md minimal-diff pointer to the new Docker fast path (5 insertions, 0 deletions). - Spec section 10 acceptance bar: every topology doc contains a copy-paste path from zero to first call OR the honest statement of what cannot work there (e.g. CGNAT WebRTC for homelab.md users behind a CGNAT). ## ADR-0011 Status: Proposed (not Accepted) - Ratification is a separate maintainer step. This slice ships ADR-0011 Proposed; the maintainer promotes to Accepted in a separate commit after epoch review. ## Cross-check step - At the start of each doc task ran 'ls deploy/' in the worktree. deploy/ was absent on this branch (Plan B not landed here) for all 8 tasks; docs stand on spec section 6.1 names (already reconciled to git.adlee.work/alee/rutster-*). If Plan B lands before merge a follow-up reconciliation pass can run. ## Citation discipline - Every docs/deploy/ file's factual third-party claim cites the TLS brief's external source URL inline (Twilio errors 31910/11237, Twilio security page, Twilio SSL-termination blog, LE rate-limits, Caddy #6420/#7222, cloudflared #1465/#1282, livekit/agents #3379, ngrok pricing, HAProxy #2280, Traefik #10601/#11405). Brief URL gaps: none. ## Seam invariant - Plan G is docs-only. git diff main --name-only | grep -E 'crates/rutster-media/src/(loop_driver|rtc_session).rs' -> 'seam intact' (verified in final sweep). Files touched: docs/QUICKSTART.md + docs/adr/0011-deployment-topology.md + docs/deploy/{topologies,quickstart-docker,homelab,aws,reverse-proxies,certificates}.md only. ## Repo gates - cargo fmt --all --check: green. cargo clippy --all --all-targets -- -D warnings: green. cargo test --all: green. cargo deny check: deferred to CI (local cargo-deny 0.18.3 has pre-existing deny.toml:84 TOML parse failure on GPL-3.0-or-later; CI runs cargo-deny 0.19.x via EmbarkStudios/cargo-deny-action@v2 which parses fine -- PM has surfaced to user separately). ## 8 commits (all DCO signed off) - 538b059 docs(adr): ADR-0011 deployment topology (Proposed) (slice-G) - 285f205 docs(deploy): topologies.md three blessed shapes + decision guide (slice-G) - 1be6112 docs(deploy): quickstart-docker.md T1 docker run + T2 compose zero to first call (slice-G) - 33c3a14 docs(deploy): homelab.md CGNAT truth PSTN-only + VPS+WireGuard graduation (slice-G) - a0b3e24 docs(deploy): aws.md ALB appendix three mandatory overrides never NLB-TLS (slice-G) - 6c8c754 docs(deploy): reverse-proxies.md BYO nginx/HAProxy/Traefik tuned-timeout configs (slice-G) - 0e415c7 docs(deploy): certificates.md ACME paths /data persistence wildcard traps (slice-G) - 5546613 docs: QUICKSTART points at deploy/quickstart-docker.md as the fast path (slice-G) ## Merge instructions - squash-merge (independent branch, no stacked-branches case in this epoch) - DCO signoff every commit (8/8 confirmed) - after merge: maintainer tags docs/deployment-topology-spec: deploy-g-docs-adr-0011-merged; separately promotes ADR-0011 Proposed -> Accepted after epoch review
alee added 8 commits 2026-07-06 03:16:00 +00:00
docs(adr): ADR-0011 deployment topology — one binary, three blessed shapes (Proposed) (slice-G) 538b059f76 
Drafted from the 2026-07-05 deployment-topology spec §2–§4: T1 solo /
T2 modular / T3 fleet (paper), the edge doctrine (bundled Caddy; rustls
Phase 1 now, Phase 2 behind four named triggers), the fleet cert story
(wildcard vs per-node; on-demand TLS rejected), node-addressed placement
via Valkey presence (routing tier + distinguished control node rejected),
and the rejected shapes (FOB decomposition, serverless, tunnels-in-prod,
NLB-TLS, k8s manifests). Status Proposed — ratification per repo process.
Closes the topology ADR reserved by ADR-0008's worked example.

Signed-off-by: Aaron D. Lee <himself@adlee.work>
docs(deploy): topologies.md — three blessed shapes + decision guide (slice-G) 285f2055ba 
The docs/deploy/ tree entry point. T1/T2 process+service tables, the
grace-exceeds-drain rule, the honest T3 statement (paper only, no
copy-paste deploy exists), the not-supported list, and the shared
ports/volumes reference. Acceptance bar: copy-paste paths delegate to
quickstart-docker.md; T3 states plainly what cannot be done today.

Signed-off-by: Aaron D. Lee <himself@adlee.work>
docs(deploy): quickstart-docker.md — T1 docker run + T2 compose, zero to first call (slice-G) 1be6112148 
The acceptance-bar doc: a copy-paste path from a bare Linux host with a
domain to (1) a browser WebRTC call and (2) a real PSTN call via the
Twilio webhook. Volumes marked non-negotiable with the LE-lockout reason;
all-or-none RUTSTER_TWILIO_* contract stated (matches config.rs); host
networking recommended for direct media UDP.

Signed-off-by: Aaron D. Lee <himself@adlee.work>
docs(deploy): homelab.md — CGNAT truth: PSTN-only behind tunnels, VPS+WireGuard graduation (slice-G) 33c3a145b0 
Acceptance bar honored by honesty: the doc leads with what cannot work
(no tunnel carries inbound UDP -> WebRTC unreachable behind CGNAT). Three
tiers: ngrok blessed dev path with the free-tier arithmetic (~140 MB/
call-hour -> ~7 call-hours/month), Tailscale Funnel single-user demo
(ciphertext-only), and the VPS+WireGuard graduation with TLS terminating
at home (forwarder physically cannot read audio; media UDP DNAT restores
WebRTC). cloudflared explicitly excluded even for dev (#1465, #1282).

Signed-off-by: Aaron D. Lee <himself@adlee.work>
docs(deploy): aws.md — ALB appendix: three mandatory overrides, never NLB-TLS (slice-G) a0b3e248f5 
Docs-only appendix per ADR-0011 (never a shipped artifact). The three
mandatory ALB attribute overrides (idle_timeout=4000,
client_keep_alive=604800, preserve_host_header=true) with the telephony
reasons; the never-NLB-TLS rule with the 350s-silent-drop + no-HTTP-
context rationale; 100-target-group fleet ceiling; per-node EIPs for
direct media UDP; copy-paste aws elbv2 CLI path to first call.

Signed-off-by: Aaron D. Lee <himself@adlee.work>
docs(deploy): reverse-proxies.md — BYO nginx/HAProxy/Traefik tuned-timeout configs (slice-G) 6c8c754cb1 
The universal 60s idle-timeout footgun stated up front; the five-point
contract any proxy must honor (incl. RUTSTER_TRUSTED_PROXIES + honest
X-Forwarded-* for signature validation); complete snippets: nginx
(explicitly not-recommended, snippet-only support), HAProxy (timeout
tunnel in defaults per #2280; hard-stop-after warning), Traefik (pin the
exact version — #10601 / v2.11.2 / #11405 WS-breaking patch history).

Signed-off-by: Aaron D. Lee <himself@adlee.work>
docs(deploy): certificates.md — ACME paths, /data persistence, wildcard traps (slice-G) 0e415c7480 
The availability-critical subsystem: no-self-signed-path (Twilio 31910),
the /data-loss -> LE 5/week duplicate-cert lockout -> total-inbound-outage
chain (31910 streams + 11237 webhooks) with backup command; HTTP-01 vs
DNS-01 (bundled plugin set: cloudflare/route53/porkbun/hetzner/desec,
duckdns excluded) vs BYO-cert rustls Phase 1 (RUTSTER_TLS_CERT/KEY,
hot-reload); Caddy renewal-vs-reload distinction with the #6420/#7222
caveat; fleet patterns (central wildcard vs per-node certs) with the
identical-wildcard trap and the on-demand-TLS rejection.

Signed-off-by: Aaron D. Lee <himself@adlee.work>
docs: QUICKSTART points at deploy/quickstart-docker.md as the fast path (slice-G) 55466130a5 
Minimal diff: one blockquote after the status note. The from-source page
stays the developer path; the Docker quickstart is now the operator fast
path (slice-G docs tree).

Signed-off-by: Aaron D. Lee <himself@adlee.work>
alee merged commit 0c307acdb5 into docs/deployment-topology-spec 2026-07-06 04:07:27 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
alee
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: alee/rutster#23
Delete Branch "deploy-g/docs-adr-0011"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?