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
This commit is contained in:
Noel Sabia committed 2026-10-14 21:54:33 +02:00
1 parent e432895080
commit 3636053a35
8 files changed
+47 -14

No files matched your search

+4 -3
View File
@@ -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
+1
View File
@@ -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.
+1 -1
View File
@@ -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"
+2 -2
View File
@@ -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.
+1 -1
View File
@@ -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
+3
View File
@@ -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
+28
View File
@@ -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).
+7 -7
View File
@@ -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.**