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:
1 parent
a1de7a5fae
commit
f0a9d58cff
11 files changed
+37
-29
No files matched your search
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
@@ -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
|
||||
|
||||
@@ -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"
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
+3
-4
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
+2
-2
@@ -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.**
|
||||
|
||||
+4
-4
@@ -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.
|
||||
|
||||
Reference in new issue
Block a user