diff --git a/architecture/gateway.md b/architecture/gateway.md index 9fee4ce..a89c722 100644 --- a/architecture/gateway.md +++ b/architecture/gateway.md @@ -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 diff --git a/architecture/index.md b/architecture/index.md index 16fdc9c..795e02f 100644 --- a/architecture/index.md +++ b/architecture/index.md @@ -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. diff --git a/architecture/language-model.md b/architecture/language-model.md index 6357afe..04fcb7e 100644 --- a/architecture/language-model.md +++ b/architecture/language-model.md @@ -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 diff --git a/architecture/server-budget.md b/architecture/server-budget.md index 2ce5173..d7138cc 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] # 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" diff --git a/architecture/system.md b/architecture/system.md index f5a5d03..ce6e92e 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 | |---|---|---| -| 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. diff --git a/architecture/terraform.md b/architecture/terraform.md index 9dc9603..acc0cf2 100644 --- a/architecture/terraform.md +++ b/architecture/terraform.md @@ -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 diff --git a/decisions/index.md b/decisions/index.md index 5004a79..8ead492 100644 --- a/decisions/index.md +++ b/decisions/index.md @@ -1,13 +1,12 @@ # 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. -* [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. * [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 index 9a33a1a..25a6196 100644 --- a/decisions/own-proxy.md +++ b/decisions/own-proxy.md @@ -1,8 +1,8 @@ --- 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] +title: Own Caddy reverse proxy instead of Cloudflare Tunnel +description: The apex domain points straight at the home server; a Caddy reverse proxy installed by Terraform is the only entry. +tags: [decision, networking, caddy, 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 } @@ -11,15 +11,17 @@ 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. +the home server directly; Caddy (provisioned by Terraform) terminates HTTPS, +gets and renews certificates via its ACME client, 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. +- 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 diff --git a/decisions/provision-with-terraform.md b/decisions/provision-with-terraform.md index 9a35e12..ebcb78c 100644 --- a/decisions/provision-with-terraform.md +++ b/decisions/provision-with-terraform.md @@ -1,7 +1,7 @@ --- type: Decision 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] status: stable 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 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 diff --git a/overview.md b/overview.md index d1a9e69..10e0588 100644 --- a/overview.md +++ b/overview.md @@ -36,7 +36,7 @@ Full mapping: [chapter states](/chapters/state-mapping.md). # 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) └─ 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. - **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). - **Nobody gets Kubernetes API access.** Visitors and agents only talk to the gateway. - **Failures are lessons, never bugs.** diff --git a/roadmap.md b/roadmap.md index f512f31..9a395e7 100644 --- a/roadmap.md +++ b/roadmap.md @@ -1,7 +1,7 @@ --- type: 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] status: revised 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 -- 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). - **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 @@ -92,7 +92,7 @@ stays inside the [memory budget](/architecture/server-budget.md). ## 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. -- 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. - **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.