Compare commits

...
12 Commits
Author SHA1 Message Date
Noel Sabia 6ab76c2a36 docs(okf): record learning contract and boss-facing German plan
learning contract: 2 h company time per week plus evenings, 6-month learning phase, German one-pager per module, repo goes public; add lern-und-entwicklungsplan.md and modul-zusammenfassung.md template; language model fixed browser-only; resolve open questions
2026-10-15 14:44:49 +02:00
Noel Sabia f0a9d58cff 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
2026-10-15 14:44:49 +02:00
Noel Sabia a1de7a5fae docs(okf): restore release-please action open question 2026-10-14 21:55:08 +02:00
Noel Sabia 01cab5a565 docs(okf): rebuild roadmap for Terraform, own proxy and WebMCP
insert 0.2.0 Terraform server and 0.4.0 reverse proxy/DNS, renumber releases, fold story cards into 0.9.0 and tracker into 1.0.0; release 1.1.0 becomes WebMCP from the Nuxt page (server-side MCP endpoint dropped); update open questions, v1 scope and log
2026-10-14 21:54:40 +02:00
Noel Sabia 3940946448 docs(okf): add Terraform provisioning architecture and decision 2026-10-14 21:54:40 +02:00
Noel Sabia 3636053a35 docs(okf): replace Cloudflare Tunnel with own nginx reverse proxy
direction change: own nginx proxy (Terraform-installed, certbot TLS) is the only public entry; add own-proxy decision; update system, gateway SSE notes, server budget and accepted-downtime docs
2026-10-14 21:54:33 +02:00
Noel SabiaandClaude Opus 5.5 e432895080 docs(okf): align placeholder chapter count with roadmap
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-11 14:48:06 +02:00
Noel SabiaandClaude Opus 5.5 8e1ea495c4 docs(okf): replace GoatCounter proposal with own SQLite tracker
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-11 14:43:34 +02:00
Noel SabiaandClaude Opus 5.5 261cf17e52 docs(okf): add server memory budget and analytics proposal
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-11 14:39:54 +02:00
Noel SabiaandClaude Opus 5.5 64fef83314 docs(okf): move bundle to repo root and retire brief
The brief is fully captured in the bundle; it stays in git history.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-11 14:22:03 +02:00
Noel SabiaandClaude Opus 5.5 957a386b58 docs: add original planning brief
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-11 14:21:20 +02:00
Noel SabiaandClaude Opus 5.5 557ac1985b docs(okf): write overview, architecture, decisions and roadmap
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-11 14:18:32 +02:00
29 changed files with 1281 additions and 23 deletions

No files matched your search

+45
View File
@@ -0,0 +1,45 @@
---
type: Service
title: Chapter service
description: One small Go binary whose health behavior is set by the MODE env var; every life chapter runs it.
tags: [architecture, go, k3s]
status: stable
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
---
# Behavior
| `MODE` | Runs as | `/healthz` (liveness) | `/ready` (readiness) | Resulting state |
|---|---|---|---|---|
| `healthy` | Deployment | 200 | 200 | Running, Ready |
| `not-ready` | Deployment | 200 | 503 | Running, NotReady |
| `crash` | Deployment | n/a | n/a | Exits on start: CrashLoopBackOff |
| `complete` | Job | n/a | n/a | Prints a line, exits 0: Completed |
`CHAPTER` env var names the chapter. Used in logs only.
# Endpoints
- `GET /healthz` - liveness.
- `GET /ready` - readiness, depends on `MODE`.
- `POST /fall` - responds 202, then `os.Exit(1)`. The kubelet restarts the container and increments `restartCount`.
# Kubernetes details
- Each chapter gets a Deployment (1 replica) and a Service `chapter-{name}`.
- Services set `publishNotReadyAddresses: true`, otherwise a NotReady chapter
has no endpoints and the gateway cannot push it.
- Label every pod `cv.noelsabia.dev/chapter: {name}`. The gateway uses it to map pods to chapters.
- Limits per chapter: 10m CPU, 16Mi memory, `GOMEMLIMIT=12MiB`. See [server budget](/architecture/server-budget.md).
Crashing chapters back off on Kubernetes' default schedule, which caps at 5 minutes.
- Completed Jobs keep no `ttlSecondsAfterFinished`, so they stay visible as Completed.
- A CrashLoopBackOff chapter cannot be pushed; it is already down. The UI shows its lesson card instead.
# Manifests
Plain YAML, one file per chapter, applied with `kubectl apply -k` (kustomize is
built into kubectl). Copy-paste per chapter is fine at this size.
# Size
About 50 lines of Go, standard library only.
+38
View File
@@ -0,0 +1,38 @@
---
type: Pipeline
title: Delivery
description: Gitea Actions on the home server scan, build, push to the Gitea registry, deploy with kubectl, and version with release-please.
tags: [architecture, ci, gitea, release-please]
status: stable
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
---
# Pipeline
```
push to main ─► Gitea Actions (runner on the home server)
├─ go test ./...
├─ snyk test
├─ build images: gateway (with Nuxt), chapter
├─ push to the Gitea container registry
└─ kubectl apply -k deploy/
─► release-please (Gitea variant) opens a release PR; merging it tags the version
```
# Details
- **Commits:** Conventional Commits. `feat:` bumps minor, `fix:` bumps patch,
`docs:` and `chore:` do not release.
- **Image tags:** the git SHA, so every deploy is traceable.
- **Registry pull:** k3s needs an `imagePullSecret` for the Gitea registry,
or `/etc/rancher/k3s/registries.yaml` if the registry is plain HTTP.
- **Runner permissions:** a kubeconfig for a ServiceAccount that can only
manage resources in `cv`.
- **Jobs are immutable:** changing a completed chapter's Job spec needs a
delete before apply. Rare, since finished chapters do not change.
- **Snyk:** needs a `SNYK_TOKEN` secret in Gitea.
- **Memory:** builds run on the same 4 GB server. Runner capacity 1, Node capped at 512 MB, swap as a safety net. See [server budget](/architecture/server-budget.md).
# Later
- k6 as a release gate needs a staging target. See [open questions](/decisions/open-questions.md).
+48
View File
@@ -0,0 +1,48 @@
---
type: Frontend
title: Frontend
description: Nuxt site generated to static files and served by the gateway, with three audience layers fed by one SSE stream.
tags: [architecture, nuxt, design]
status: stable
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
---
# Build
`nuxt generate` produces static, prerendered files. A multi-stage Docker build
runs it in a Node stage and copies the output into the gateway's Go stage for
`go:embed`. No Node process runs in the cluster.
# Layers
| Layer | Audience | Content | Needs live cluster |
|---|---|---|---|
| 0: First screen | HR | Name, role, contact, PDF CV download | No |
| 1: Life map | Non-technical | Chapters in plain words, "Push this chapter", story cards | Yes, degrades to static |
| 2: Dev view | Developers | Raw SSE events in a `<pre>` | Yes |
# Content
Chapter text (title, dates, story, setback, recovery, lesson) lives in the
Nuxt repo as one data file. The key is the chapter name, the same value as the
pod label `cv.noelsabia.dev/chapter`. The gateway knows nothing about stories.
# Behavior without the live stream
If `/api/events` fails, the life map renders from the data file with a small
"live cluster offline" note. No error page.
# Plain-word states
| State | Shown as |
|---|---|
| Completed | finished |
| Running, Ready | active |
| Running, NotReady | unfinished |
| CrashLoopBackOff | failed, lesson learned |
| Restarting after a push | recovering |
# Design
Terminal feel, navy `#1A3D64` and white, logo with a "broken pieces" look.
Drafted with Stitch prompts.
+70
View File
@@ -0,0 +1,70 @@
---
type: Service
title: Gateway
description: The only public service; serves the static site, streams chapter states over SSE, and forwards rate-limited knockdowns.
tags: [architecture, go, security]
status: stable
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
---
# Routes
| Route | Does |
|---|---|
| `GET /` and static paths | Serves the Nuxt build, embedded with `go:embed` |
| `GET /api/events` | SSE stream: full state on connect, then each change |
| `POST /api/fall/{chapter}` | Allowlist, cooldown, rate limit, then calls the chapter's `/fall` |
| every route | Counted by the tracker |
# Reading cluster state
- v1 polls `list pods` and `list events` in `cv` every 2 seconds and diffs the result.
At about 10 pods this is cheap. Upgrade path: a client-go informer.
- Recovery times come from the pod's Ready condition `lastTransitionTime`,
so they are exact even though polling is not.
- Dependency: `k8s.io/client-go`. It authenticates through the in-cluster ServiceAccount.
# SSE event shape
```json
{"chapter": "example", "phase": "Running", "ready": true, "restarts": 3, "event": "recovered", "seconds": 4.2}
```
The same stream feeds the life map and the developer view.
# Limits
- **Per-chapter cooldown:** a `map[string]time.Time` behind a mutex. Default 30 seconds.
- **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".
# Caddy proxy and SSE
- 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 the proxy's default read timeout.
# Tracker
Middleware that counts page views, PDF downloads and falls. See [decision](/decisions/own-tracker.md).
```sql
CREATE TABLE counts (day TEXT, event TEXT, n INTEGER, PRIMARY KEY (day, event));
-- event: 'view:/', 'pdf', 'fall:example', ...
INSERT INTO counts VALUES (?, ?, 1) ON CONFLICT DO UPDATE SET n = n + 1;
```
- Daily totals only. No IP addresses, no cookies, no personal data.
- Skip requests whose user agent looks like a bot.
- SQLite file on a small `local-path` volume. Deployment strategy `Recreate`,
so two gateway pods never write the file at the same time.
- Read the numbers with `sqlite3` or a small admin route later; no dashboard in v1.
# Resources
64Mi memory limit with `GOMEMLIMIT=50MiB`, 100m CPU. See [server budget](/architecture/server-budget.md).
# RBAC
ServiceAccount `gateway` in `cv`, Role with `get/list/watch` on `pods`,
`events` and `jobs`. No create, delete or patch.
+10
View File
@@ -0,0 +1,10 @@
# Architecture
* [System](system.md) - All runtime components of the v1 site and how a request and a knockdown flow through them.
* [Chapter service](chapter-service.md) - One small Go binary whose health behavior is set by the MODE env var; every life chapter runs it.
* [Gateway](gateway.md) - The only public service; serves the static site, streams chapter states over SSE, and forwards rate-limited knockdowns.
* [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, 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.
+48
View File
@@ -0,0 +1,48 @@
---
type: Project
title: In-browser language model
description: A tiny language model trained by Noel that runs entirely in the visitor's browser and shows its internals live.
tags: [architecture, ml, typescript, learning]
status: draft
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
---
# Goal
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
statically by the [gateway](/architecture/gateway.md). It adds nothing to the cluster.
# Plan
| Step | What | Guide |
|---|---|---|
| Base model | About 5M parameters, layers written by hand, trained with PyTorch on TinyStories with word-piece tokens | Karpathy "Zero to Hero", llama2.c |
| Browser inference | Forward pass in plain TypeScript | llama2.c |
| Visuals | Attention heatmaps, next-token probabilities, temperature slider | |
| Chat | Fine-tune at 15-30M parameters on simple dialogues in a fixed user/bot format | |
| Own engine | Replace PyTorch gradients with Noel's own autograd | micrograd |
# Expectations
- TinyStories gives coherent short stories. Grimm gives stylish nonsense.
- The chat handles greetings and small talk, not knowledge questions or long conversations.
# Constraints
- **Download size:** 5M parameters in fp32 is about 20 MB, 30M is about 120 MB.
Ship int8 weights (about 4× smaller) and load them lazily.
- **Training happens on Noel's own computer.** The [server](/architecture/server-budget.md) only serves the weights file.
- **PyTorch is new tooling** and needs Noel's approval under the stack rule.
+97
View File
@@ -0,0 +1,97 @@
---
type: Reference
title: Server and memory budget
description: The CV shares a 2 vCPU, 4 GB server with Gitea and a small webapp, so every workload gets a hard memory cap.
tags: [architecture, k3s, resources]
status: stable
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
sources:
- id: free-m
resource: "`free -m` on server0, before k3s, with Gitea, runner and webapp running"
author: human:noel
last_modified: 2026-10-11T12:15:30Z
---
# Server
`server0`: 2 vCPU, 3805 MB RAM, no swap yet. Shared with Gitea, its Actions
runner, and a small webapp with one user.
# Budget
| What | Memory | Basis |
|---|---|---|
| OS, Gitea, runner (idle), webapp | 1143 MB | Measured[^free-m] |
| k3s, trimmed | ~500 MB | Estimate, measure after install |
| Namespace `cv`, hard quota | 384 MB | ResourceQuota |
| Left for CI builds and page cache | ~1.7 GB | |
| Swap | 2 GB | Safety net for build spikes |
[^free-m]: `free -m` on server0
Per workload inside `cv`:
| Workload | Memory limit | CPU limit |
|---|---|---|
| Gateway, including the [tracker](/decisions/own-tracker.md) | 64Mi, `GOMEMLIMIT=50MiB` | 100m |
| Each chapter (~10) | 16Mi, `GOMEMLIMIT=12MiB` | 10m |
Completed Jobs do not count against the quota.
# Namespace caps
```yaml
apiVersion: v1
kind: ResourceQuota
metadata: { name: cv-budget, namespace: cv }
spec:
hard: { limits.memory: 384Mi }
---
apiVersion: v1
kind: LimitRange
metadata: { name: cv-defaults, namespace: cv }
spec:
limits:
- type: Container
default: { memory: 16Mi, cpu: 50m }
defaultRequest: { memory: 8Mi, cpu: 5m }
```
# k3s config
`/etc/rancher/k3s/config.yaml`:
```yaml
disable: [traefik, servicelb] # Caddy (Terraform) replaces both
kubelet-arg:
- "system-reserved=memory=1300Mi" # measured 1143 MB plus margin
- "eviction-hard=memory.available<200Mi"
```
Keep `metrics-server` and `local-storage`: the HPA demo needs the first,
the tracker's SQLite volume the second. Single-node k3s uses SQLite, not etcd; do not
pass `--cluster-init`.
# Swap
```sh
sudo fallocate -l 2G /swapfile && sudo chmod 600 /swapfile
sudo mkswap /swapfile && sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
```
k3s starts with swap enabled. Pods do not swap; host processes such as
Gitea and builds can.
# CI builds
The biggest memory risk. A Nuxt build can take over 1 GB.
- Runner capacity 1: one job at a time.
- `NODE_OPTIONS=--max-old-space-size=512` for the Nuxt build.
- Swap catches the rest.
# What does not run here
- **Language model training:** on Noel's own computer. The server only serves the weights file.
- **Large load tests:** k6 and the HPA demo stay tiny (max 3 replicas, a few virtual users), or are cut.
+61
View File
@@ -0,0 +1,61 @@
---
type: Architecture
title: System architecture
description: All runtime components of the v1 site and how a request and a knockdown flow through them.
tags: [architecture, k3s, go, nuxt]
status: stable
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
---
# Components
| Component | Runs as | Job |
|---|---|---|
| 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. |
| [Delivery](/architecture/delivery.md) | Gitea Actions on the home server | Test, scan, build, push, deploy, version. |
Everything runs in one namespace: `cv`, capped at 384Mi memory in total, on a
2 vCPU, 4 GB server shared with Gitea. See [server budget](/architecture/server-budget.md).
# Images
Two images from one Go module:
```
cmd/gateway → image `gateway` (includes the Nuxt build)
cmd/chapter → image `chapter`
```
# Flow: page load
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.
# Flow: knockdown
1. Visitor clicks "Push this chapter": `POST /api/fall/{chapter}`.
2. Gateway checks the allowlist, the per-chapter cooldown, and the global rate limit.
3. Gateway calls `http://chapter-{chapter}.cv.svc/fall` over cluster DNS.
4. The chapter process exits. The kubelet restarts it, `restartCount` goes up.
5. Gateway sees the pod go not-ready, then ready again, and pushes both changes over SSE.
6. Recovery time = Ready condition `lastTransitionTime` minus the fall time.
7. The page shows the story card with the measured seconds.
No step needs write access to the Kubernetes API.
# Security boundaries
- Only the gateway is reachable from outside.
- Gateway ServiceAccount: `get/list/watch` on pods, events and jobs in `cv`. Nothing else.
- `/fall` is unauthenticated inside the cluster. A NetworkPolicy (supported natively by k3s) restricts it to the gateway.
- No visitor-supplied input reaches the cluster except a chapter name checked against an allowlist.
# Accepted risk
If the home server is down, the whole site is down. See
[accept downtime in v1](/decisions/accept-downtime-v1.md).
+53
View File
@@ -0,0 +1,53 @@
# Server provisioning
Terraform owns everything outside the cluster: packages, swap, k3s itself,
the reverse proxy, and DNS records. Rebuilding the server from nothing is two
commands.
## Scope
| Layer | Managed by | Examples |
|---|---|---|
| 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-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
describes its own state; Terraform and kubectl would fight over it.
## Files
```
terraform/
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
```
Plan output for one run:
```
+ swapfile 2 GB
+ k3s service (traefik, servicelb disabled)
+ Caddy reverse_proxy block -> http://127.0.0.1:8080 (gateway NodePort)
+ certificate for noelsabia.dev
```
## Why
- The server became disposable: `terraform destroy && terraform apply` plus
`kubectl apply -k deploy/` returns the whole system. That is the fastest
possible disaster recovery and the clearest possible demo.
- Proxmox and cloud names change; code does not. The same Terraform targets the
home server now and a VM later.
- Home IP changes: the DNS provider has an A record the server can update.
Terraform manages the record; a small script re-sets it if the IP moves.
## Constraints
- **Terraform is new tooling** for Noel and needs approval under the stack
rule. Worth it: infrastructure as code is a core work skill.
- State file: local, not in Git. Nothing secret in the config itself.
- Changing a completed chapter or a Job is a delete plus apply, documented.
+7
View File
@@ -0,0 +1,7 @@
# Chapters
* [Chapter states](state-mapping.md) - How each Kubernetes primitive and state maps to a meaning in Noel's life story.
# Chapter list
Not written yet. One concept per chapter: dates, state, story, setback, recovery or lesson.
+30
View File
@@ -0,0 +1,30 @@
---
type: Reference
title: Chapter states
description: How each Kubernetes primitive and state maps to a meaning in Noel's life story.
tags: [chapters, k3s, narrative]
status: stable
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
---
# Mapping
| Kubernetes | Meaning | Example | Release |
|---|---|---|---|
| Job, Completed | Finished chapter | School, 42 piscine | v1 |
| Deployment, Running and Ready | Active, stable chapter | PreZero, Example | v1 |
| Running, NotReady | Exists, unfinished | Ongoing studies, thesis | v1 |
| CrashLoopBackOff | Failed and stayed failed | Abandoned projects | v1 |
| `restartCount` | Setbacks survived | "fell 3×, stood up 3×" | v1 |
| Replicas, HPA scale-up | Load carried, growth under pressure | Team lead, two businesses | Phase 3 |
| Rolling update | Pivot or reinvention | Career switch | Not planned yet |
Finished chapters are Jobs because they complete. Current chapters are
Deployments because they must stay alive.
# Narrative rules
- Every fall shows a story card: what went wrong and what got Noel back up.
- The recovery time shown is real, measured in seconds.
- Permanently failed chapters show a lesson card, not a recovery.
- Failures are labeled as lessons, never as bugs.
+25
View File
@@ -0,0 +1,25 @@
---
type: Decision
title: Accept home-server downtime in v1
description: v1 serves everything from the home server; if it is down, the whole site is down.
tags: [decision, availability]
status: stable
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
verified: { by: human:noel, at: 2026-10-11T12:15:30Z }
---
# Decision
Accept the risk. No off-box hosting, no snapshot persistence in v1.
# Why
- Off-box hosting (Cloudflare Pages, GitHub Pages) is new tooling and needs approval.
- A snapshot fallback only helps when the server is up but the gateway is not,
which the static Nuxt data file already covers.
- If the server is down, visitors see the reverse proxy's error page. HR may hit it.
# Revisit when
The CV is actively sent to employers, or downtime is noticed in practice.
The fix is hosting the static first screen off-box.
+24
View File
@@ -0,0 +1,24 @@
---
type: Decision
title: Knowledge bundle lives at the repository root
description: The repository root is the OKF bundle root; any other markdown file there needs frontmatter to stay conformant.
tags: [decision, okf]
status: stable
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
verified: { by: human:noel, at: 2026-10-11T12:15:30Z }
---
# Decision
The OKF v0.2 bundle root is the repository root.
# Consequence
OKF requires frontmatter with a `type` in every non-reserved `.md` file in the
bundle. Any other markdown at the root breaks conformance unless it carries
frontmatter, for example:
- `README.md`: give it frontmatter (`type: Readme`) or skip it; `index.md` already does its job.
- `CHANGELOG.md` from release-please: release-please writes it without
frontmatter. Options: point release-please's `changelog-path` at a non-`.md`
file, or accept that one file is non-conformant.
+24
View File
@@ -0,0 +1,24 @@
---
type: Decision
title: CI/CD on Gitea Actions
description: The existing Gitea instance and runner on the home server build, scan, deploy and version the project.
tags: [decision, ci, gitea, release-please]
status: stable
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
verified: { by: human:noel, at: 2026-10-11T12:15:30Z }
---
# Decision
Use Gitea Actions with the runner already on the home server, the Gitea
container registry, and the Gitea variant of the release-please action.
# Why
- GitHub Actions cannot reach the k3s API behind the tunnel. The local runner can.
- No new tooling: Gitea, its runner and its registry already exist.
- No GitOps agent (Flux, Argo) needed.
# Details
See [delivery](/architecture/delivery.md).
+14
View File
@@ -0,0 +1,14 @@
# 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.
* [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.
* [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 questions](open-questions.md) - Decisions still to make, with the release that needs each answer.
+39
View File
@@ -0,0 +1,39 @@
---
type: Decision
title: Learning contract with PreZero
description: 2 hours of company time per week plus evenings on this project during a 6-month learning phase; a German one-pager per finished module; the repo goes public so the boss can follow by link.
tags: [decision, learning, prezero]
status: stable
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-15T00:00:00Z }
verified: { by: human:noel, at: 2026-10-15T00:00:00Z }
---
# Decision
Noel, developer in the AI & Digitalization department, runs this project as a
personal learning project within an agreed **6-month learning phase**:
- **2 hours of company time per week**, the rest in the evenings, on Noel's
own server. No company data, no company secrets, no company cost.
- **No hard delivery promise.** After 6 months both sides review how far the
work has come; the follow-up phase is decided then.
- **One German one-pager per finished module** (template:
[`modul-zusammenfassung.md`](/modul-zusammenfassung.md)): what was built,
what was learned, relevance for the team, and proof.
- **The Gitea repository becomes public**, so the boss can follow progress by
link. The [Lern- und Entwicklungsplan](/lern-und-entwicklungsplan.md) in
this bundle is the document he reads.
# Why
- The AI & Digitalization department builds webapps and missing tooling.
This project exercises exactly that delivery path: containers, orchestration,
infrastructure as code, CI/CD and observability — on a day job's real stack.
- The boss explicitly wants the team to get better; this makes the learning
visible and reviewable instead of invisible.
- Direction to senior developer: demonstrating ownership across the full
delivery chain, not only writing features.
# Revisit when
The 6-month review happens, or company time availability changes.
+24
View File
@@ -0,0 +1,24 @@
---
type: Open Questions
title: Open questions
description: Decisions still to make, with the release that needs each answer.
tags: [decision, open]
status: draft
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-15T00:00:00Z }
---
| Question | Needed by | Default if nobody decides |
|---|---|---|
| Final chapter list and the state of each chapter | 0.3.0 (placeholders), 1.0.0 (final) | Four placeholder chapters: one completed, one active, one unfinished, one failed |
| Story card text per chapter | 0.9.0 | None, Noel writes it |
| Life map visual form: timeline, graph or map | 0.9.0 | Vertical timeline |
| Which Gitea release-please action, exact name | 0.1.0 | None, Noel names it |
| How the server is reachable: router port-forward, static IP or DDNS | 0.4.0 | DDNS + port-forward 80/443 |
| k6 staging target: namespace or separate cluster | 1.2.0 | Namespace `cv-staging` on the same cluster |
| Approve PyTorch for the language model | 1.5.0 | None, needs Noel |
| Approve NumPy (or similar) for the own autograd engine | 1.13.0 | None, needs Noel |
Resolved since the last review: Terraform approved (0.2.0), WebMCP scope
decided — state plus push, exposed from the Nuxt page, same limits as
visitors (1.1.0), Caddy instead of nginx (0.4.0), browser-only language
model (after 1.7.0), and the [learning contract](/decisions/learning-contract.md).
+30
View File
@@ -0,0 +1,30 @@
---
type: Decision
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 }
---
# Decision
No tunnel, no managed entry service. A DNS A record points the apex domain at
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.
- 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
Inbound ports 80 and 443 must be reachable at the home server (router
port-forward, static IP or DDNS). This is a solved-but-open question — see
[open questions](/decisions/open-questions.md).
+36
View File
@@ -0,0 +1,36 @@
---
type: Decision
title: Own analytics tracker on SQLite
description: Analytics are counted by Noel's own code in the gateway and stored as daily totals in SQLite; no third-party tracker, no Postgres.
tags: [decision, analytics, sqlite, go]
status: stable
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
verified: { by: human:noel, at: 2026-10-11T12:15:30Z }
---
# Decision
Write the tracker as middleware in the [gateway](/architecture/gateway.md).
Store daily totals in SQLite via `modernc.org/sqlite` (pure Go, no cgo).
SQLite is approved tooling.
# Why
- The gateway already sees every page view, PDF download and fall. No
tracking script, nothing for ad blockers to block.
- About 5 MB of memory, no extra pod. GoatCounter would need ~30 MB, Umami
with Postgres ~300-400 MB, on a [4 GB shared server](/architecture/server-budget.md).
- A learning project: owning the code is the point.
# Rejected
| Option | Why not |
|---|---|
| Umami | Needs Postgres, ~300-400 MB |
| GoatCounter | Fine, but Noel wants his own |
| Postgres for the own tracker | ~40-60 MB for a table of counters |
| Cloudflare analytics only | Cannot count falls or PDF downloads |
# Revisit when
Noel wants to learn Postgres. The schema is plain SQL, so the move is small.
+34
View File
@@ -0,0 +1,34 @@
---
type: Decision
title: Provision the server with Terraform
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 }
verified: { by: human:noel, at: 2026-10-14T00:00:00Z }
---
# Decision
Terraform owns everything outside k3s: server packages, swap, the k3s
install, Caddy (including automatic HTTPS) and the DNS record. Nothing inside the cluster.
# Why
- The whole system becomes rebuildable from nothing: `terraform destroy`
then `terraform apply`, then `kubectl apply -k deploy/`.
- Infrastructure as code is a core work skill; the playground is the place to
learn it on a real, cheap target.
- The same files target the home server now and any cloud VM later.
# Rejected
| Option | Why not |
|---|---|
| Ansible | Fine, but Terraform also covers DNS and is the more common hire signal |
| Terraform for k8s workloads | kubectl/helm already own cluster state; two owners fight |
| Manual server setup | Works once, impossible to demo or recover |
# Details
See [terraform provisioning](/architecture/terraform.md).
+26
View File
@@ -0,0 +1,26 @@
---
type: Decision
title: Static Nuxt served by the gateway
description: Nuxt is generated to static files and embedded in the gateway image instead of running as its own pod.
tags: [decision, nuxt, go]
status: stable
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
---
# Decision
Build with `nuxt generate`, embed the output in the gateway with `go:embed`.
# Why
- One less Deployment, no Node runtime in the cluster.
- One public service, same origin for the site and `/api`, so no CORS.
- The life map can still render from its data file when the live stream fails.
# Cost
Frontend and gateway release together in one image.
# Revisit when
The site needs server-side rendering per request.
+32
View File
@@ -0,0 +1,32 @@
---
type: Decision
title: v1 scope
description: What the first public version keeps and what moves to later phases.
tags: [decision, scope, roadmap]
status: stable
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
---
# Keep in v1
- First screen: name, role, contact, PDF CV. Never gated behind interaction.
- Life map with plain-word states and a "Push this chapter" button.
- Story cards with real recovery seconds, lesson cards for failed chapters.
- Live states: Completed, Ready, NotReady, CrashLoopBackOff, restart counts.
- Gateway: SSE plus `/fall` with per-chapter cooldown and global rate limit.
- "Someone just knocked down X" messages. Free, the SSE stream carries them.
- Dev view: the raw event stream in a `<pre>`. Also free.
- CI: Snyk, build, deploy, release-please.
# Cut from v1
| Cut | Why | Where it went |
|---|---|---|
| Separate Nuxt pod | Static build served by the gateway is simpler | [Decision](/decisions/static-nuxt-in-gateway.md) |
| Snapshot persistence, offline banner | Downtime accepted for v1 | [Decision](/decisions/accept-downtime-v1.md) |
| Server-side MCP endpoint on the gateway | Replaced by WebMCP from the Nuxt page: agents use the same public API, the gateway gains no new authority | Phase 2 (1.1.0) |
| k6 as a CI gate | Needs a staging target first | Phase 2 |
| Full kubectl-style terminal (YAML, probes) | The raw stream covers it | Phase 2 |
| Interactive k6, HPA demo, latency graph | Most work and most abuse risk | Phase 3 |
| Rolling update as "pivot" | Nothing triggers it yet | Not planned |
| client-go informer | Polling every 2 seconds is enough at about 10 pods | When polling falls short |
+19
View File
@@ -0,0 +1,19 @@
---
okf_version: "0.2"
---
# Start here
* [Overview](overview.md) - A CV whose life chapters run as real Kubernetes workloads that visitors can knock down and watch recover.
* [Roadmap](roadmap.md) - Small releases in three phases, each a few days of work at most, each ending in something that runs.
* [Update log](log.md) - History of changes to this bundle.
# Für den Vorgesetzten
* [Lern- und Entwicklungsplan](lern-und-entwicklungsplan.md) - Der deutsche Plan: was ich baue, was ich lerne, wie Fortschritt messbar wird.
# Drill down
* [Architecture](architecture/) - Components, services, frontend, delivery, and the in-browser language model.
* [Decisions](decisions/) - What we chose, what we cut, and what is still open.
* [Chapters](chapters/) - How Kubernetes states map to life chapters, and later one concept per chapter.
-23
View File
@@ -1,23 +0,0 @@
---
okf_version: "0.2"
---
# Project
* [Overview](overview.md) - Interactive CV on k3s: falling down and standing up again, shown live.
* [Roadmap](roadmap.md) - What ships in v1, v2 and v3, including the in-browser language model.
# Architecture
* [System](architecture/system.md) - Cloudflare Tunnel, Go gateway serving the static Nuxt build, chapter services in namespace `cv`.
* [Chapter service](architecture/chapter-service.md) - One Go image, health behavior set by `MODE`, knockdown via `/fall`.
* [Gateway](architecture/gateway.md) - Only public API: SSE pod states and rate-limited `/fall`.
* [Delivery](architecture/delivery.md) - Gitea Actions: Snyk, build, Gitea registry, `kubectl apply -k`, release-please.
# Decisions
* [Decisions](decisions/) - Accepted trade-offs, such as v1 accepting home-server downtime.
# Chapters
* [Chapters](chapters/) - One concept per life chapter and its Kubernetes state.
+111
View File
@@ -0,0 +1,111 @@
---
type: Lernplan
title: Lern- und Entwicklungsplan
description: Deutschsprachiger Plan für meinen Vorgesetzten — was ich baue, was ich lerne, wie Fortschritt messbar wird.
tags: [lernplan, prezero, deutsch]
status: stable
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-15T00:00:00Z }
---
# Zusammenfassung
> **TL;DR: In einer 6-monatigen Lernphase baue ich auf meinem eigenen Server
> eine interaktive CV-Website, auf der jedes Lebenskapitel als echtes System
> läuft, das man umwerfen und sich wieder aufrichten sehen kann. Dafür lerne
> ich die komplette moderne Lieferkette — Infrastruktur als Code, Container,
> Kubernetes, automatisierte Pipelines und load testing — genau die
> Werkzeuge, die unser Team (AI & Digitalization) beim Bauen von Webapps und
> Werkzeugen täglich braucht. 2 Stunden Firmenzeit pro Woche plus Abende,
> alles auf eigener Infrastruktur, keine Kosten für PreZero. Nach jedem
> fertigen Modul schreibe ich einen One-Pager (Was gebaut / Was gelernt /
> Relevanz fürs Team / Beweis). Fortschritt ist jederzeit sichtbar im
> Repo.**
# Ausgangslage
Ich bin Developer in der Abteilung AI & Digitalization — wir bauen fehlende
Tools, Webapps und helfen strategisch bei der Digitalisierung. Mein Ziel ist
es, über Skill und Kenntnis in Richtung Senior-Developer zu wachsen. Der
direkteste Weg dafür: ein echtes Produkt bauen, betreiben und nachweisbar
verbessern — nicht in einer Sandkastenumgebung, sondern im echten Betrieb.
# Das Projekt in vier Sätzen
Meine CV-Website serviert zunächst den professionellen Regelbetrieb — Name,
Kontakt, PDF, in 10 Sekunden verstanden. Darunter läuft jedes Lebenskapitel
als echter Service auf meinem k3s-Cluster ("schlankes Kubernetes"): Besucher
können ein Kapitel umwerfen und zusehen, wie es in gemessenen Sekunden
wieder hochkommt. Failures sind bewusste Inhalte ("Lektion gelernt"), kein
Bug. Das Projekt zeigt damit exakt, was im Job zählt: Systeme bauen,
die ausfallen und wieder aufstehen.
# Warum das für unser Team relevant ist
Unser Team baut Webapps und Tooling. Dieses Projekt durchläuft genau die
Lieferschritte, die wir dafür täglich brauchen:
| Fähigkeit | Direkte Anwendung im Team |
|---|---|
| Infrastruktur als Code (Terraform) | Server-Umgebungen reproduzierbar und versionierbar aufbauen |
| Container & Kubernetes (Docker, k3s) | Webapps portabel, skaliert und mit Limits betreiben |
| Automatisierte Pipelines (CI/CD, Snyk) | Testen, scannen und ausliefern ohne manuelle Schritte |
| Eigener Reverse-Proxy (Caddy) | Verstehen, was zwischen Browser und Container passiert |
| Beobachterbarkeit (SSE, Logs) | Live-Systeme sichtbar machen, Probleme früh erkennen |
| Kontrolliertes Load-Testing (k6) | Wissen, wie viel Last ein Service trägt — ohne Schätzung. |
Jedes Modul endet mit einem One-Pager: kurz, auf Deutsch, mit Beweis. So
wird Lernen messbar statt gefühlt.
# Der Lernplan
Die Module bauen aufeinander auf (Reihenfolge = Abhängigkeiten). Zeitwerte
sind Fokustag-Estimates, keine Deadlines; insgesamt rund 20–25 Fokustage.
| # | Modul | Was ich lerne |
|---|---|---|
| 1 | Restartbarer Chapter-Service | Software bauen, die den Neustart als Feature nutzt |
| 2 | Server als Terraform-Code | Kompletten Server zerstörbar & neu aufbaubar machen |
| 3 | Kapitel auf k3s | Workloads mit Limits, Labels und Services betreiben |
| 4 | Eigener Caddy-Proxy, DNS, TLS | Den gesamten Request-Pfad selbst besitzen |
| 5 | CI/CD-Pipeline | Ein `git push` reicht bis zum laufenden Cluster |
| 6 | Live-Status (SSE) | Echte Systemzustände sicher an Besucher streamen |
| 7 | Knockdown mit Limits | Öffentliche Endpunkte gegen Missbrauch absichern |
| 8 | Professioneller First-Screen | Läuft ohne JavaScript, degradiert sauber |
| 9 | Life Map & Story Cards | Systemereignisse für Nicht-Techniker erzählbar machen |
| 10 | Eigener Tracker + Launch | Ohne Cookies tracken, Privacy by design, fertigstellen |
Danach, noch in den 6 Monaten, ambitioniert:
| # | Modul | Was ich lerne |
|---|---|---|
| 11 | WebMCP | Die Seite wird über die Browser-Schnittstelle für KI-Agenten bedienbar — ohne neue Server-Berechtigungen |
| 12 | k6 als Release-Gate | Performanz wird zum Blocker-Kriterium im Release, öffentlich sichtbar |
| 13 | Autoscaling-Demo | Skalierung unter Last live sichtbar machen (mehr Repliken unter Last, weniger danach) |
Erste Phase nach den 6 Monaten: ein kleines, selbst trainiertes
Sprachmodell, das komplett **im Browser** läuft und seine Funktionsweise
live zeigt — Chat-Fähigkeit und Training von Grund auf, ohne fremde API.
# Modalitäten
- **2 Stunden/Woche auf Firmenzeit**, den Rest in den Abenden; beide Anteile
laufen auf meinem eigenen Server.
- **Keine Kosten, keine Firmendaten, keine Firmengeheimnisse** im Projekt.
- Mein **Gitea-Repo wird öffentlich**: Fortschritt, Releases und die Live-Seite
sind per Link sichtbar — Sie können beliebig häufig selbst nachsehen.
- **Keine harte Deadline:** Die 6 Monate sind mein Taktstock. Danach
gemeinsame Bilanz, wie weit ich gekommen bin und was als Nächstes kommt.
# Messbarkeit
1. **One-Pager pro Modul** (Vorlage: `modul-zusammenfassung.md`): Was gebaut,
was gelernt, Relevanz fürs Team, Beweis (Link, Screenshot, Log).
2. **Sichtbarer Fortschritt im Repo:** Releases, Tests, Pipeline und die
Live-Seite selbst sind die Beweise.
3. **Halbzeitbilanz** nach ca. 3 Monaten: kurzer Stand, was läuft, was
gelernt wurde.
---
*Quelle: die Planungsdokumente in diesem Bundle (`OKF_CV_Website/`) —
Übersicht, Architecture, Entscheidungen und Roadmap.*
+21
View File
@@ -0,0 +1,21 @@
# Update Log
## 2026-10-15
* **Creation**: Added the [Lern- und Entwicklungsplan](/lern-und-entwicklungsplan.md) (German, for the boss at PreZero) and the [Modul-Zusammenfassung template](/modul-zusammenfassung.md) — one German one-pager per finished module.
* **Decision**: Recorded the [learning contract](/decisions/learning-contract.md): 2 h company time per week plus evenings, 6-month learning phase, one-pager per module, Gitea repo goes public.
* **Update**: Switched the reverse proxy from nginx to **Caddy** everywhere [own proxy](/decisions/own-proxy.md), [Terraform](/architecture/terraform.md), [system](/architecture/system.md), [gateway](/architecture/gateway.md), [roadmap](/roadmap.md) — automatic HTTPS instead of certbot.
* **Update**: Language model fixed as **browser-only**; a server-inference variant is cut. See [language model](/architecture/language-model.md).
* **Cleanup**: Resolved open questions: Terraform approved, WebMCP scope (state plus push from the page), Caddy, browser-only model. See [open questions](/decisions/open-questions.md).
## 2026-10-14
* **Direction change**: No Cloudflare Tunnel. The apex domain points straight at the home server; nginx (installed by Terraform with certbot TLS) is the only public entry. See [own proxy](/decisions/own-proxy.md).
* **Decision**: Add [Terraform provisioning](/architecture/terraform.md): packages, swap, k3s, nginx and DNS are code; workloads inside the cluster stay with kustomize. See [decision](/decisions/provision-with-terraform.md).
* **Update**: Rebuilt the [roadmap](/roadmap.md) around the new direction: Terraform server (0.2.0), reverse proxy and DNS (0.4.0), renumbered releases, and story cards folded into the life map release.
* **Decision**: Server-side MCP endpoint on the gateway is out. Replaced by WebMCP on the Nuxt page (release 1.1.0): the page exposes read-state and push tools to an agent in the browser, calling the same public gateway API with the same limits.
## 2026-10-11
* **Update**: Replaced the GoatCounter proposal with Noel's [own tracker on SQLite](/decisions/own-tracker.md).
* **Creation**: Added the [server and memory budget](/architecture/server-budget.md) from measured usage, and proposed GoatCounter over Umami (since replaced by the [own tracker](/decisions/own-tracker.md)).
* **Update**: Moved the bundle from `knowledge/` to the repository root and replaced the planning brief with this bundle. See [bundle at root](/decisions/bundle-at-root.md).
* **Creation**: Wrote the [overview](/overview.md), [architecture](/architecture/), [decisions](/decisions/), [chapter states](/chapters/state-mapping.md) and [roadmap](/roadmap.md) from the planning conversation.
* **Initialization**: Created the bundle [index](/index.md).
+30
View File
@@ -0,0 +1,30 @@
---
type: Template
title: Modul-Zusammenfassung (One-Pager)
description: Pro fertigem Modul ausfüllen — was gebaut, was gelernt, Relevanz fürs Team, Beweis.
tags: [template, learning, deutsch]
status: draft
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-15T00:00:00Z }
---
# Modul: `<Name>` — `<Datum>`
**Was habe ich gebaut?**
<!-- 2–4 Sätze, Ergebnis orientiert. Link zum Artefakt, falls es eins gibt. -->
**Was habe ich gelernt?**
<!-- 3–5 konkrete Punkte, jeder mit Bezug zur Praxis. -->
**Relevanz für AI & Digitalization**
<!-- Wie hilft das unserem Team: Muster, Werkzeuge, Prozesse, die wiederverwendbar sind. -->
**Beweis**
<!-- Link, Screenshot, Ausgabe des Done-Checks, Release-Log. -->
**Wie ist es gelaufen?**
<!-- Umfang (Zeit), Blocker, was ich beim nächsten Mal anders mache. -->
+74
View File
@@ -0,0 +1,74 @@
---
type: Overview
title: Interactive CV on k3s
description: A CV whose life chapters run as real Kubernetes workloads that visitors can knock down and watch recover.
tags: [overview, cv, k3s]
status: stable
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
---
# In one sentence
Noel's CV on the apex domain, where every life chapter is a workload on a
home k3s cluster: visitors push a chapter over and watch it stand up again.
The theme is **falling down and standing up again**.
# Two audiences, one page
| Audience | What they get |
|---|---|
| HR, 10 seconds | Name, role, contact, PDF CV. No interaction needed. |
| Non-technical visitor | A life map of chapters in plain words, a "Push this chapter" button, and a story card after every fall. |
| Developer | The raw live event stream from the cluster: pod states, restarts, recovery times. |
# The idea in pictures
| Kubernetes state | Life meaning |
|---|---|
| Job, Completed | Finished chapter (school, 42 piscine) |
| Deployment, Running and Ready | Active chapter |
| Running, NotReady | Exists but unfinished (studies, thesis) |
| CrashLoopBackOff | An attempt that failed and stayed failed, shown as a lesson |
| restartCount | Setbacks survived |
Full mapping: [chapter states](/chapters/state-mapping.md).
# How it works, high level
```
Visitor ─► Caddy (TLS, Terraform) ─► Go gateway ─┬─ serves the Nuxt site (static files)
├─ streams live chapter states (SSE)
└─ forwards "push" to a chapter's /fall
│
chapter services in namespace `cv`
(one Go image, behavior set by env)
```
When a chapter is pushed, its process exits, Kubernetes restarts it, and the
page shows the real recovery time next to the story of how Noel recovered.
# Drill down
* [System architecture](/architecture/system.md) - every component and how they connect.
* [Roadmap](/roadmap.md) - small releases, each a few days of work.
* [Decisions](/decisions/) - what we chose and what we cut.
* [Open questions](/decisions/open-questions.md) - what is still undecided.
# Ground rules
- **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, 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.**
# Risks
| Risk | Mitigation |
|---|---|
| HR confusion | The first screen is conventional and complete on its own. The interactive part is optional. |
| Spectacle without substance | Every state change links to a story card. |
| Home server downtime | Accepted for v1, see [decision](/decisions/accept-downtime-v1.md). |
| Abuse | Cooldowns, global rate limit, no raw cluster access, no visitor-defined k6 scripts. |
| "Unhealthy" read as incompetence | Failures are labeled as lessons. |
+211
View File
@@ -0,0 +1,211 @@
---
type: Roadmap
title: Roadmap
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 }
---
# Overview
| Phase | Releases | Outcome |
|---|---|---|
| 1: Ship the CV | 0.1.0 - 1.0.0 | Public interactive CV on the apex domain |
| 2: Depth | 1.1.0 - 1.7.0 | WebMCP, k6 release gate, dev terminal, in-browser language model |
| 3: Pressure and from scratch | 1.8.0 - 1.13.0 | Interactive load test with HPA, chat model, own autograd engine |
| Release | Name | Days |
|---|---|---|
| 0.1.0 | Chapter service | 1-2 |
| 0.2.0 | Terraform server | 2-3 |
| 0.3.0 | Chapters on k3s | 2 |
| 0.4.0 | Reverse proxy and DNS | 1-2 |
| 0.5.0 | Pipeline | 2 |
| 0.6.0 | Live states | 2-3 |
| 0.7.0 | Knockdown | 1-2 |
| 0.8.0 | First screen | 2 |
| 0.9.0 | Life map and story cards | 3-4 |
| 1.0.0 | Own tracker, real content, launch | 3-4 |
| 1.1.0 | WebMCP | 2 |
| 1.2.0 | k6 release gate | 2 |
| 1.3.0 | Dev terminal | 2 |
| 1.4.0 | LM: data and tokenizer | 2-3 |
| 1.5.0 | LM: model and training | 3 |
| 1.6.0 | LM: browser inference | 3 |
| 1.7.0 | LM: visuals | 2-3 |
| 1.8.0 | Interactive k6 | 3 |
| 1.9.0 | HPA demo | 2-3 |
| 1.10.0 | LM: bigger base model | 2-3 |
| 1.11.0 | LM: chat fine-tune | 3 |
| 1.12.0 | Own autograd engine | 3 |
| 1.13.0 | Train with own engine | 2-3 |
Each release is cut by release-please from `feat:` commits. A release is done
when its "done when" check passes on the real cluster, not locally.
Everything runs on a 2 vCPU, 4 GB server shared with Gitea. Every release
stays inside the [memory budget](/architecture/server-budget.md).
---
# Phase 1: Ship the CV
## 0.1.0 Chapter service
- Go module with `cmd/chapter`: `/healthz`, `/ready`, `/fall`, behavior from `MODE`. See [chapter service](/architecture/chapter-service.md).
- Dockerfile, distroless or scratch base.
- One `go test` that checks `/ready` per `MODE`.
- release-please config, manifest and Gitea workflow, so this release is the first one it cuts.
- **Done when:** `docker run -e MODE=not-ready` answers 503 on `/ready`, and `POST /fall` ends the container with exit code 1.
- **Learn:** Go `net/http`, container basics, Conventional Commits.
## 0.2.0 Terraform server
- Terraform module that rebuilds server0 from nothing: packages, 2 GB swap file, k3s installed with traefik and servicelb disabled, kubelet reservations, and the `imagePullSecret` for the Gitea registry. See [terraform provisioning](/architecture/terraform.md).
- Terraform also creates namespace `cv` with the ResourceQuota (384Mi) and LimitRange, and the DNS A record for the apex domain.
- State file stays local; `plan` output is reviewed before every apply.
- **Done when:** `terraform destroy` then `terraform apply` on a blank server0 leaves k3s running, swap active, namespace `cv` with its quota on a fresh server. No hand steps.
- **Learn:** Terraform (providers, provisioners, plan/apply, state), cloud-init/SSH provisioning, why infra as code beats hand setup.
## 0.3.0 Chapters on k3s
- Four placeholder chapters applied with `kubectl apply -k deploy/`: one Job (`complete`), one each of `healthy`, `not-ready`, `crash`.
- Services with `publishNotReadyAddresses: true`, resource limits, pod label `cv.noelsabia.dev/chapter`.
- **Done when:** `kubectl get pods -n cv` shows Completed, Running 1/1, Running 0/1 and CrashLoopBackOff, and a `/fall` from a debug pod raises `restartCount`.
- **Learn:** Deployments, Jobs, probes, Services, kustomize, resource limits and quotas.
## 0.4.0 Reverse proxy and DNS
- 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/ACME, DNS records, port-forwarding.
## 0.5.0 Pipeline
- Gitea workflow: `go test`, `snyk test`, build and push images tagged with the git SHA, `kubectl apply -k`.
- Runner kubeconfig limited to namespace `cv`. Runner capacity 1, so builds never run in parallel.
- **Done when:** a push to `main` deploys a new image without touching the server by hand.
- **Learn:** Gitea Actions, RBAC for CI, Snyk.
## 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. 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.
## 0.7.0 Knockdown
- `POST /api/fall/{chapter}`: allowlist, 30-second per-chapter cooldown, global `rate.Limiter`.
- Recovery time from the Ready condition's `lastTransitionTime`.
- "fell" and "recovered" events with seconds in the stream.
- NetworkPolicy: only the gateway can reach chapter `/fall`.
- One test for the cooldown and limiter logic.
- **Done when:** a POST knocks a chapter over, a second POST within 30 seconds gets 429, and the stream shows the recovery seconds.
- **Learn:** rate limiting, NetworkPolicy, measuring with Kubernetes conditions.
## 0.8.0 First screen
- Nuxt project, `nuxt generate` with `NODE_OPTIONS=--max-old-space-size=512`, multi-stage Dockerfile that embeds the output in the gateway image.
- Layer 0: name, role, contact, PDF CV download. Navy `#1A3D64` and white.
- **Done when:** the page loads and the PDF downloads with JavaScript disabled.
- **Learn:** Nuxt static generation, `go:embed`, multi-stage builds.
## 0.9.0 Life map and story cards
- Chapter data file in Nuxt keyed by chapter name.
- Life map (default: vertical timeline) with plain-word states from the stream and a "Push this chapter" button.
- Story card on every fall with the measured seconds. Lesson card for CrashLoopBackOff chapters. Falls back to the data file with a "live cluster offline" note when the stream fails.
- Dev view: the raw stream in a `<pre>`.
- **Done when:** a non-technical person can push a chapter, say what happened, and two browsers see each other's knockdowns live.
- **Learn:** Nuxt components, `EventSource`, degrading gracefully.
## 1.0.0 Own tracker and launch
- Gateway middleware writing daily totals to SQLite (`modernc.org/sqlite`) on a `local-path` volume. See [decision](/decisions/own-tracker.md). Count page views, PDF downloads and falls per chapter. No IPs, no cookies. Deployment strategy `Recreate`.
- Final chapter list, one manifest per chapter, story text, final PDF CV.
- **Done when:** someone from HR finds the PDF within 10 seconds, the live map shows every real chapter, and a test visit, a PDF download and a fall each raise their count in the SQLite file.
- **Learn:** SQLite, Go `database/sql`, HTTP middleware, privacy by design, finishing work.
---
# Phase 2: Depth
## 1.1.0 WebMCP
- No server-side MCP endpoint. Instead, the Nuxt page itself exposes tools over WebMCP (the browser-native agent interface): a tool to read chapter states and a tool to push a chapter.
- Under the hood the tools call the same public gateway API, so agents get exactly the limits visitors get. The gateway gains no new authority.
- **Done when:** an agent in the browser can list chapters and push one, and the gateway counts and rate-limits it like any other visitor.
- **Learn:** WebMCP, agent-facing tool design, least-privilege agency.
## 1.2.0 k6 release gate
- Namespace `cv-staging`, deploy there first in CI, run a fixed k6 script, fail the pipeline on the p95 threshold.
- Badge on the site: "p95 < X ms, last run".
- **Done when:** a deliberately slow build blocks the release.
## 1.3.0 Dev terminal
- kubectl-style view: events, probe results, restart history, YAML per chapter (read-only `get` through the gateway).
- **Done when:** a developer can inspect any chapter's state without the cluster.
## 1.4.0 LM: data and tokenizer
- TinyStories download, word-piece tokenizer written by hand, train/validation split.
- **Done when:** encode then decode round-trips the validation set.
## 1.5.0 LM: model and training
- About 5M-parameter transformer, layers written by hand, gradients from PyTorch (needs approval).
- Training runs on Noel's own computer, not the server. Checkpoint saved.
- **Done when:** samples read like short simple stories.
## 1.6.0 LM: browser inference
- Export int8 weights, forward pass in plain TypeScript on `/lm`.
- **Done when:** TypeScript logits match PyTorch logits within a small tolerance for the same input.
## 1.7.0 LM: visuals
- Attention heatmaps per head, next-token probability bars, temperature slider.
- **Done when:** moving the slider visibly changes the probability bars and the generated text.
---
# Phase 3: Pressure and from scratch
## 1.8.0 Interactive k6
- Fixed k6 script run as a Job with the `grafana/k6` image, a few virtual users, 30 seconds max, 64Mi limit.
- The server is shared with Gitea: if a run slows Gitea noticeably, cut this release.
- One run at a time across the site. No visitor-supplied parameters.
- The gateway needs `create` on Jobs for this, the first write permission it gets. Limit it to this one Job template.
- **Done when:** a second visitor sees "a test is already running".
## 1.9.0 HPA demo
- HPA on one chapter using metrics-server (ships with k3s), max 3 replicas, live replica count and latency graph during a k6 run.
- **Done when:** replicas go up during a run and back down after.
## 1.10.0 LM: bigger base model
- Retrain the base model at 15-30M parameters on Noel's own computer. Check training time first.
- **Done when:** samples are clearly better than the 5M model.
## 1.11.0 LM: chat fine-tune
- Fine-tune on simple dialogues in a fixed user/bot format.
- **Done when:** it answers greetings and small talk in the browser.
## 1.12.0 Own autograd engine
- Tensor autograd written by Noel, likely on NumPy (needs approval).
- **Done when:** gradients match PyTorch on a small model.
## 1.13.0 Train with own engine
- Train the 5M model with the own engine instead of PyTorch.
- **Done when:** loss curves roughly match the PyTorch run.