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.
- 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
through nginx's default read timeout.
through the proxy's default read timeout.
# 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.
* [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.
* [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.
+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
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
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`:
```yaml
disable: [traefik, servicelb] # nginx (Terraform) replaces both
disable: [traefik, servicelb] # Caddy (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 |
|---|---|---|
| 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. |
| [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. 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.
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 |
| 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 |
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/
main.tf server: packages, swap, k3s, nginx, certbot
main.tf server: packages, swap, k3s, Caddy
dns.tf A record for the apex domain
variables.tf server IP, SSH key, domain
outputs.tf server IP, proxy URL
@@ -31,8 +31,8 @@ Plan output for one run:
```
+ swapfile 2 GB
+ k3s service (traefik, servicelb disabled)
+ nginx server block -> http://127.0.0.1:8080 (gateway NodePort)
+ certbot certificate for noelsabia.dev
+ Caddy reverse_proxy block -> http://127.0.0.1:8080 (gateway NodePort)
+ certificate for noelsabia.dev
```
## Why