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.
|
- **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
|
||||||
|
|
||||||
|
|||||||
@@ -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.
|
||||||
@@ -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
|
||||||
|
|||||||
@@ -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"
|
||||||
|
|||||||
@@ -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.
|
||||||
|
|
||||||
|
|||||||
@@ -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
@@ -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
|
||||||
|
|||||||
@@ -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
|
||||||
|
|
||||||
|
|||||||
@@ -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
@@ -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
@@ -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.
|
||||||
|
|||||||
Reference in new issue
Block a user