docs(okf): switch reverse proxy to Caddy across bundle

own-proxy decision, terraform provisioner, system diagram, gateway SSE notes, server-budget comment and roadmap 0.4.0 now use Caddy with ACME-managed TLS instead of nginx plus certbot
This commit is contained in:
Noel Sabia committed 2026-10-15 14:44:49 +02:00
1 parent a1de7a5fae
commit f0a9d58cff
11 files changed
+37 -29

No files matched your search

+3 -3
View File
@@ -38,11 +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. - **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". - Knockdowns are shared state on purpose: every viewer sees "someone just knocked down X".
# nginx proxy and SSE # Caddy proxy and SSE
- Terminate SSE at the gateway; nginx proxies it per-connection with buffering off (`proxy_buffering off`). - Terminate SSE at the gateway; Caddy proxies it per-connection with buffering off (`flush_interval -1`).
- Send a comment line (`: ping`) every 30 seconds so idle connections are not closed - Send a comment line (`: ping`) every 30 seconds so idle connections are not closed
through nginx's default read timeout. through the proxy's default read timeout.
# Tracker # Tracker
+1 -1
View File
@@ -6,5 +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. * [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. * [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. * [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. * [Terraform provisioning](terraform.md) - Terraform rebuilds the server, swap, k3s, Caddy 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. * [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.
+7
View File
@@ -13,6 +13,13 @@ A from-scratch learning project on the same domain: a small transformer whose
attention patterns, next-token probabilities and temperature are visible and attention patterns, next-token probabilities and temperature are visible and
adjustable in the browser. adjustable in the browser.
# Decision (2026-10-15)
Browser-only, confirmed by Noel: the model runs in the visitor's browser.
A **server-run inference variant is cut** — the visitor's device carries the
compute and the server only serves the weights file. This is part of the
planned post-6-months stretch of the [learning contract](/decisions/learning-contract.md).
# Architecture # Architecture
No backend. A `/lm` page in the Nuxt build plus a weights file, both served No backend. A `/lm` page in the Nuxt build plus a weights file, both served
+1 -1
View File
@@ -62,7 +62,7 @@ spec:
`/etc/rancher/k3s/config.yaml`: `/etc/rancher/k3s/config.yaml`:
```yaml ```yaml
disable: [traefik, servicelb] # nginx (Terraform) replaces both disable: [traefik, servicelb] # Caddy (Terraform) replaces both
kubelet-arg: kubelet-arg:
- "system-reserved=memory=1300Mi" # measured 1143 MB plus margin - "system-reserved=memory=1300Mi" # measured 1143 MB plus margin
- "eviction-hard=memory.available<200Mi" - "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 | | Component | Runs as | Job |
|---|---|---| |---|---|---|
| nginx (reverse proxy) | Terraform-installed, on the home server | Only way in from the internet. TLS via certbot. Points at the gateway. | | Caddy (reverse proxy) | Terraform-installed, on the home server | Only way in from the internet. TLS automatic via ACME. 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. | | [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`. | | [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. | | [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 # Flow: page load
1. Visitor opens the apex domain. DNS points at the home server. nginx (TLS via certbot) forwards to the gateway Service. 1. Visitor opens the apex domain. DNS points at the home server. Caddy (automatic HTTPS) forwards to the gateway Service.
2. Gateway returns prerendered Nuxt HTML. The first screen works without JavaScript. 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. 3. The page opens `GET /api/events` (SSE) and receives the current state of every chapter, then every change.
+4 -4
View File
@@ -10,7 +10,7 @@ commands.
|---|---|---| |---|---|---|
| Server, packages, swap, k3s install | Terraform (SSH provisioner, cloud-init or shell) | `fallocate`, `mkswap`, k3s service with trimmed config | | Server, packages, swap, k3s install | Terraform (SSH provisioner, cloud-init or shell) | `fallocate`, `mkswap`, k3s service with trimmed config |
| DNS records | Terraform provider for the DNS zone | A/AAAA record for the apex domain | | DNS records | Terraform provider for the DNS zone | A/AAAA record for the apex domain |
| Reverse proxy | Terraform-installed nginx + certbot, config templated | server block to the gateway | | Reverse proxy | Terraform-managed Caddy, Caddyfile templated | reverse_proxy block to the gateway |
| Workloads inside k3s | kustomize, applied by CI or hand | Namespace `cv`, Deployments, Jobs, Services, quota | | Workloads inside k3s | kustomize, applied by CI or hand | Namespace `cv`, Deployments, Jobs, Services, quota |
Terraform does not manage anything inside the cluster. Kubernetes already Terraform does not manage anything inside the cluster. Kubernetes already
@@ -20,7 +20,7 @@ describes its own state; Terraform and kubectl would fight over it.
``` ```
terraform/ terraform/
main.tf server: packages, swap, k3s, nginx, certbot main.tf server: packages, swap, k3s, Caddy
dns.tf A record for the apex domain dns.tf A record for the apex domain
variables.tf server IP, SSH key, domain variables.tf server IP, SSH key, domain
outputs.tf server IP, proxy URL outputs.tf server IP, proxy URL
@@ -31,8 +31,8 @@ Plan output for one run:
``` ```
+ swapfile 2 GB + swapfile 2 GB
+ k3s service (traefik, servicelb disabled) + k3s service (traefik, servicelb disabled)
+ nginx server block -> http://127.0.0.1:8080 (gateway NodePort) + Caddy reverse_proxy block -> http://127.0.0.1:8080 (gateway NodePort)
+ certbot certificate for noelsabia.dev + certificate for noelsabia.dev
``` ```
## Why ## Why
+3 -4
View File
@@ -1,13 +1,12 @@
# Decisions # Decisions
* [Learning contract with PreZero](learning-contract.md) - 2 hours of company time per week plus evenings during a 6-month learning phase; one German one-pager per finished module; the repo goes public.
* [v1 scope](v1-scope.md) - What the first public version keeps and what moves to later phases. * [v1 scope](v1-scope.md) - What the first public version keeps and what moves to later phases.
* [Accept home-server downtime in v1](accept-downtime-v1.md) - v1 serves everything from the home server; if it is down, the whole site is down. * [Own Caddy reverse proxy](own-proxy.md) - The apex domain points straight at the home server; a Caddy reverse proxy provisioned by Terraform is the only entry, with automatic HTTPS.
* [Provision the server with Terraform](provision-with-terraform.md) - Packages, swap, k3s, Caddy and DNS are Terraform code; workloads inside the cluster stay with kustomize.
* [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. * [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. * [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. * [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. * [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 # Open
+8 -6
View File
@@ -1,8 +1,8 @@
--- ---
type: Decision type: Decision
title: Own nginx reverse proxy instead of Cloudflare Tunnel title: Own Caddy 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. description: The apex domain points straight at the home server; a Caddy reverse proxy installed by Terraform is the only entry.
tags: [decision, networking, nginx, terraform] tags: [decision, networking, caddy, terraform]
status: stable status: stable
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-14T00:00:00Z } generated: { by: claude-code/claude-opus-5-5, at: 2026-10-14T00:00:00Z }
verified: { by: human:noel, at: 2026-10-14T00:00:00Z } verified: { by: human:noel, at: 2026-10-14T00:00:00Z }
@@ -11,15 +11,17 @@ verified: { by: human:noel, at: 2026-10-14T00:00:00Z }
# Decision # Decision
No tunnel, no managed entry service. A DNS A record points the apex domain at 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 the home server directly; Caddy (provisioned by Terraform) terminates HTTPS,
certbot certificate) terminates TLS and forwards to the gateway Service. gets and renews certificates via its ACME client, and forwards to the gateway
Service.
# Why # Why
- A managed tunnel outsources exactly the part Noel wants to learn: DNS, TLS, - A managed tunnel outsources exactly the part Noel wants to learn: DNS, TLS,
proxies and what happens between a browser and a container. 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. - 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. - Caddy on the same 4 GB server costs a few MB, well inside the budget.
- Automatic HTTPS needs no certbot; the Caddyfile is about five lines.
# Consequences # Consequences
+2 -2
View File
@@ -1,7 +1,7 @@
--- ---
type: Decision type: Decision
title: Provision the server with Terraform title: Provision the server with Terraform
description: Packages, swap, k3s, nginx and DNS are Terraform code; workloads inside the cluster stay with kustomize. description: Packages, swap, k3s, Caddy and DNS are Terraform code; workloads inside the cluster stay with kustomize.
tags: [decision, terraform, infra] tags: [decision, terraform, infra]
status: stable status: stable
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-14T00:00:00Z } generated: { by: claude-code/claude-opus-5-5, at: 2026-10-14T00:00:00Z }
@@ -11,7 +11,7 @@ verified: { by: human:noel, at: 2026-10-14T00:00:00Z }
# Decision # Decision
Terraform owns everything outside k3s: server packages, swap, the k3s Terraform owns everything outside k3s: server packages, swap, the k3s
install, nginx and certbot, and the DNS record. Nothing inside the cluster. install, Caddy (including automatic HTTPS) and the DNS record. Nothing inside the cluster.
# Why # Why
+2 -2
View File
@@ -36,7 +36,7 @@ Full mapping: [chapter states](/chapters/state-mapping.md).
# How it works, high level # How it works, high level
``` ```
Visitor ─► nginx (TLS, Terraform) ─► Go gateway ─┬─ serves the Nuxt site (static files) Visitor ─► Caddy (TLS, Terraform) ─► Go gateway ─┬─ serves the Nuxt site (static files)
├─ streams live chapter states (SSE) ├─ streams live chapter states (SSE)
└─ forwards "push" to a chapter's /fall └─ forwards "push" to a chapter's /fall
│ │
@@ -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. - **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, - **No tooling beyond the stack without Noel's approval.** The stack is Nuxt,
Go, k3s, Terraform, Docker, Snyk, Gitea Actions, release-please, nginx and k6. Go, k3s, Terraform, Docker, Snyk, Gitea Actions, release-please, Caddy 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). - **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. - **Nobody gets Kubernetes API access.** Visitors and agents only talk to the gateway.
- **Failures are lessons, never bugs.** - **Failures are lessons, never bugs.**
+4 -4
View File
@@ -1,7 +1,7 @@
--- ---
type: Roadmap type: Roadmap
title: Roadmap title: Roadmap
description: Rebuilt plan - Terraform-provisioned server, self-run nginx proxy, and the original release track on top. Each release is a few days of work and ends in something that runs. description: Rebuilt plan - Terraform-provisioned server, self-run Caddy proxy, and the original release track on top. Each release is a few days of work and ends in something that runs.
tags: [roadmap, planning] tags: [roadmap, planning]
status: revised status: revised
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-14T00:00:00Z } generated: { by: claude-code/claude-opus-5-5, at: 2026-10-14T00:00:00Z }
@@ -77,10 +77,10 @@ stays inside the [memory budget](/architecture/server-budget.md).
## 0.4.0 Reverse proxy and DNS ## 0.4.0 Reverse proxy and DNS
- nginx (installed and templated by the Terraform module from 0.2.0) is the only public entry: TLS via certbot. Until the gateway exists it forwards to a placeholder. - Caddy (installed and templated by the Terraform module from 0.2.0) is the only public entry: HTTPS with certificates it gets and renews itself via ACME. Until the gateway exists it forwards to a placeholder.
- Router port-forward, static IP or DDNS, per [own proxy](/decisions/own-proxy.md). - Router port-forward, static IP or DDNS, per [own proxy](/decisions/own-proxy.md).
- **Done when:** the apex domain loads over HTTPS from outside the home network, certificate auto-renews, and a `terraform destroy` on the network config is recovered by re-applying Terraform. - **Done when:** the apex domain loads over HTTPS from outside the home network, certificate auto-renews, and a `terraform destroy` on the network config is recovered by re-applying Terraform.
- **Learn:** reverse proxies, TLS/certbot, DNS records, port-forwarding. - **Learn:** reverse proxies, TLS/ACME, DNS records, port-forwarding.
## 0.5.0 Pipeline ## 0.5.0 Pipeline
@@ -92,7 +92,7 @@ stays inside the [memory budget](/architecture/server-budget.md).
## 0.6.0 Live states ## 0.6.0 Live states
- `cmd/gateway`: polls pods and events every 2 seconds, streams changes on `GET /api/events` with a 30-second ping. - `cmd/gateway`: polls pods and events every 2 seconds, streams changes on `GET /api/events` with a 30-second ping.
- ServiceAccount with read-only Role. nginx route now points at the gateway for real. - ServiceAccount with read-only Role. Caddy route now points at the gateway for real.
- A bare HTML page that prints the stream. - A bare HTML page that prints the stream.
- **Done when:** the public URL shows a chapter going not-ready and back after `kubectl delete pod`. - **Done when:** the public URL shows a chapter going not-ready and back after `kubectl delete pod`.
- **Learn:** client-go, in-cluster auth, SSE, serving through a self-run proxy. - **Learn:** client-go, in-cluster auth, SSE, serving through a self-run proxy.