From 3636053a35de94e46af5a289a5f3a0b957e2769e Mon Sep 17 00:00:00 2001 From: Noel Sabia Date: Wed, 14 Oct 2026 21:54:33 +0200 Subject: [PATCH] docs(okf): replace Cloudflare Tunnel with own nginx reverse proxy direction change: own nginx proxy (Terraform-installed, certbot TLS) is the only public entry; add own-proxy decision; update system, gateway SSE notes, server budget and accepted-downtime docs --- architecture/gateway.md | 7 ++++--- architecture/index.md | 1 + architecture/server-budget.md | 2 +- architecture/system.md | 4 ++-- decisions/accept-downtime-v1.md | 2 +- decisions/index.md | 3 +++ decisions/own-proxy.md | 28 ++++++++++++++++++++++++++++ overview.md | 14 +++++++------- 8 files changed, 47 insertions(+), 14 deletions(-) create mode 100644 decisions/own-proxy.md diff --git a/architecture/gateway.md b/architecture/gateway.md index f0b9b8a..9fee4ce 100644 --- a/architecture/gateway.md +++ b/architecture/gateway.md @@ -38,10 +38,11 @@ The same stream feeds the life map and the developer view. - **Global limit:** `golang.org/x/time/rate`, for example 1 fall per second with burst 3. - Knockdowns are shared state on purpose: every viewer sees "someone just knocked down X". -# Cloudflare Tunnel and SSE +# nginx proxy and SSE -- Send `Content-Type: text/event-stream` and flush after every message. -- Send a comment line (`: ping`) every 30 seconds so idle connections are not closed. +- Terminate SSE at the gateway; nginx proxies it per-connection with buffering off (`proxy_buffering off`). +- Send a comment line (`: ping`) every 30 seconds so idle connections are not closed + through nginx's default read timeout. # Tracker diff --git a/architecture/index.md b/architecture/index.md index 4353fd8..16fdc9c 100644 --- a/architecture/index.md +++ b/architecture/index.md @@ -6,4 +6,5 @@ * [Frontend](frontend.md) - Nuxt site generated to static files and served by the gateway, with three audience layers fed by one SSE stream. * [Server and memory budget](server-budget.md) - The CV shares a 2 vCPU, 4 GB server with Gitea and a small webapp, so every workload gets a hard memory cap. * [Delivery](delivery.md) - Gitea Actions on the home server scan, build, push to the Gitea registry, deploy with kubectl, and version with release-please. +* [Terraform provisioning](terraform.md) - Terraform rebuilds the server, swap, k3s, nginx and DNS from nothing; nothing inside the cluster. * [In-browser language model](language-model.md) - A tiny language model trained by Noel that runs entirely in the visitor's browser and shows its internals live. diff --git a/architecture/server-budget.md b/architecture/server-budget.md index 351ee06..2ce5173 100644 --- a/architecture/server-budget.md +++ b/architecture/server-budget.md @@ -62,7 +62,7 @@ spec: `/etc/rancher/k3s/config.yaml`: ```yaml -disable: [traefik, servicelb] # Cloudflare Tunnel replaces both +disable: [traefik, servicelb] # nginx (Terraform) replaces both kubelet-arg: - "system-reserved=memory=1300Mi" # measured 1143 MB plus margin - "eviction-hard=memory.available<200Mi" diff --git a/architecture/system.md b/architecture/system.md index ba39eac..f5a5d03 100644 --- a/architecture/system.md +++ b/architecture/system.md @@ -11,7 +11,7 @@ generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z } | Component | Runs as | Job | |---|---|---| -| Cloudflare Tunnel | `cloudflared` on the home server | Only way in from the internet. Points at the gateway. | +| nginx (reverse proxy) | Terraform-installed, on the home server | Only way in from the internet. TLS via certbot. Points at the gateway. | | [Gateway](/architecture/gateway.md) | 1 Deployment, Go | Serves the static site, streams states, forwards knockdowns, counts visits into SQLite. The only public service. | | [Frontend](/architecture/frontend.md) | Static files inside the gateway image | Nuxt, built with `nuxt generate`. | | [Chapter service](/architecture/chapter-service.md) | One Deployment or Job per chapter | Behaves healthy, not-ready, crashing, or completed, set by env. | @@ -32,7 +32,7 @@ cmd/chapter → image `chapter` # Flow: page load -1. Visitor opens the apex domain. Cloudflare Tunnel forwards to the gateway Service. +1. Visitor opens the apex domain. DNS points at the home server. nginx (TLS via certbot) forwards to the gateway Service. 2. Gateway returns prerendered Nuxt HTML. The first screen works without JavaScript. 3. The page opens `GET /api/events` (SSE) and receives the current state of every chapter, then every change. diff --git a/decisions/accept-downtime-v1.md b/decisions/accept-downtime-v1.md index 2ad5681..c661a56 100644 --- a/decisions/accept-downtime-v1.md +++ b/decisions/accept-downtime-v1.md @@ -17,7 +17,7 @@ Accept the risk. No off-box hosting, no snapshot persistence in v1. - Off-box hosting (Cloudflare Pages, GitHub Pages) is new tooling and needs approval. - A snapshot fallback only helps when the server is up but the gateway is not, which the static Nuxt data file already covers. -- If the server is down, visitors see Cloudflare's error page. HR may hit it. +- If the server is down, visitors see the reverse proxy's error page. HR may hit it. # Revisit when diff --git a/decisions/index.md b/decisions/index.md index d73ae39..5004a79 100644 --- a/decisions/index.md +++ b/decisions/index.md @@ -5,6 +5,9 @@ * [Static Nuxt served by the gateway](static-nuxt-in-gateway.md) - Nuxt is generated to static files and embedded in the gateway image instead of running as its own pod. * [Own analytics tracker on SQLite](own-tracker.md) - Analytics are counted by Noel's own code in the gateway and stored as daily totals in SQLite; no third-party tracker, no Postgres. * [CI/CD on Gitea Actions](ci-on-gitea.md) - The existing Gitea instance and runner on the home server build, scan, deploy and version the project. +* [Own nginx reverse proxy](own-proxy.md) - The apex domain points straight at the home server; an nginx reverse proxy installed by Terraform is the only entry. +* [Provision the server with Terraform](provision-with-terraform.md) - Packages, swap, k3s, nginx and DNS are Terraform code; workloads inside the cluster stay with kustomize. +* [Own nginx reverse proxy](own-proxy.md) - The apex domain points straight at the home server; an nginx reverse proxy installed by Terraform is the only entry. * [Knowledge bundle lives at the repository root](bundle-at-root.md) - The repository root is the OKF bundle root; any other markdown file there needs frontmatter to stay conformant. # Open diff --git a/decisions/own-proxy.md b/decisions/own-proxy.md new file mode 100644 index 0000000..9a33a1a --- /dev/null +++ b/decisions/own-proxy.md @@ -0,0 +1,28 @@ +--- +type: Decision +title: Own nginx reverse proxy instead of Cloudflare Tunnel +description: The apex domain points straight at the home server; an nginx reverse proxy installed by Terraform is the only entry. +tags: [decision, networking, nginx, terraform] +status: stable +generated: { by: claude-code/claude-opus-5-5, at: 2026-10-14T00:00:00Z } +verified: { by: human:noel, at: 2026-10-14T00:00:00Z } +--- + +# Decision + +No tunnel, no managed entry service. A DNS A record points the apex domain at +the home server directly; nginx (installed and configured by Terraform, with a +certbot certificate) terminates TLS and forwards to the gateway Service. + +# Why + +- A managed tunnel outsources exactly the part Noel wants to learn: DNS, TLS, + proxies and what happens between a browser and a container. +- No dependency on a third party. The entry path is Noel's own code and config. +- nginx on the same 4 GB server costs a few MB, well inside the budget. + +# Consequences + +Inbound ports 80 and 443 must be reachable at the home server (router +port-forward, static IP or DDNS). This is a solved-but-open question — see +[open questions](/decisions/open-questions.md). diff --git a/overview.md b/overview.md index 4f70c6c..d1a9e69 100644 --- a/overview.md +++ b/overview.md @@ -36,12 +36,12 @@ Full mapping: [chapter states](/chapters/state-mapping.md). # How it works, high level ``` -Visitor ─► Cloudflare Tunnel ─► Go gateway ─┬─ serves the Nuxt site (static files) - ├─ streams live chapter states (SSE) - └─ forwards "push" to a chapter's /fall - │ - chapter services in namespace `cv` - (one Go image, behavior set by env) +Visitor ─► nginx (TLS, Terraform) ─► Go gateway ─┬─ serves the Nuxt site (static files) + ├─ streams live chapter states (SSE) + └─ forwards "push" to a chapter's /fall + │ + chapter services in namespace `cv` + (one Go image, behavior set by env) ``` When a chapter is pushed, its process exits, Kubernetes restarts it, and the @@ -58,7 +58,7 @@ page shows the real recovery time next to the story of how Noel recovered. - **Learning project, ship small.** Each release is a few days of work. - **No tooling beyond the stack without Noel's approval.** The stack is Nuxt, - Go, k3s, Snyk, Gitea Actions, release-please, Cloudflare Tunnel, and k6. + Go, k3s, Terraform, Docker, Snyk, Gitea Actions, release-please, nginx and k6. - **Small server.** 2 vCPU, 4 GB, shared with Gitea. The whole CV is capped at 384Mi. See [server budget](/architecture/server-budget.md). - **Nobody gets Kubernetes API access.** Visitors and agents only talk to the gateway. - **Failures are lessons, never bugs.**