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:
1 parent
e432895080
commit
3636053a35
8 files changed
+47
-14
No files matched your search
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
@@ -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"
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
@@ -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.**
|
||||
|
||||
Reference in new issue
Block a user