Files
OKF_CV_Website/roadmap.md
T
Noel Sabia e022c30527 feat(okf): run on full Kubernetes with FreeLens for admin
k3s is out. The cluster is upstream Kubernetes installed with kubeadm:
containerd, single control-plane etcd, Calico for NetworkPolicy.

- add the cluster decision and the FreeLens decision
- move Terraform from the k3s service to kubeadm, Calico, metrics-server
  and the local-path provisioner
- budget ~900 MB for the control plane and plan a bigger machine before 0.3.0
- note kubelet failSwapOn and containerd hosts.toml
- rename 0.3.0 and commit the 0.2.0 done-when to the new stack
- update the German learning plan
2026-10-24 19:02:17 +02:00

11 KiB

type, title, description, tags, status, generated
type title description tags status generated
Roadmap Roadmap 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.
roadmap
planning
revised
by at
claude-code/claude-opus-5-5 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 Kubernetes 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 small home server shared with Gitea; a bigger machine (8 GB or a second server) arrives before 0.3.0 because the kubeadm control plane needs more room than k3s did. Every release stays inside the memory budget.


Phase 1: Ship the CV

0.1.0 Chapter service

  • Go module with cmd/chapter: /healthz, /ready, /fall, behavior from MODE. See chapter service.
  • 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, containerd, kubeadm init with a single control plane, Calico, kubelet reservations, and the imagePullSecret for the Gitea registry. See terraform provisioning.
  • Terraform also installs metrics-server and the local-path provisioner, creates namespace cv with the ResourceQuota (384Mi) and LimitRange, and creates the DNS A record for the apex domain.
  • FreeLens on Noel's laptop points at 127.0.0.1:6443 through an SSH tunnel. See FreeLens.
  • State file stays local; plan output is reviewed before every apply.
  • Done when: terraform destroy then terraform apply on a blank server0 leaves a Ready control plane with Calico, metrics-server and namespace cv with its quota, FreeLens shows the node and the namespace over the tunnel, and swap is active. No hand steps. Requires the bigger machine from open questions.
  • Learn: Terraform (providers, provisioners, plan/apply, state), cloud-init/SSH provisioning, kubeadm and containerd, why infra as code beats hand setup.

0.3.0 Chapters on Kubernetes

  • 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.
  • 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. 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 (installed by the 0.2.0 module), 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.