docs(okf): add server memory budget and analytics proposal
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
64fef83314
commit
261cf17e52
13 files changed
+178
-12
No files matched your search
@@ -30,7 +30,7 @@ generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
|
||||
- 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.
|
||||
- Tight resource limits on every chapter (for example 10m CPU, 16Mi memory).
|
||||
- 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.
|
||||
|
||||
@@ -31,6 +31,7 @@ push to main ─► Gitea Actions (runner on the home server)
|
||||
- **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
|
||||
|
||||
|
||||
@@ -42,6 +42,10 @@ The same stream feeds the life map and the developer view.
|
||||
- Send `Content-Type: text/event-stream` and flush after every message.
|
||||
- Send a comment line (`: ping`) every 30 seconds so idle connections are not closed.
|
||||
|
||||
# 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`,
|
||||
|
||||
@@ -4,5 +4,6 @@
|
||||
* [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.
|
||||
* [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.
|
||||
@@ -37,4 +37,5 @@ statically by the [gateway](/architecture/gateway.md). It adds nothing to the cl
|
||||
|
||||
- **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.
|
||||
@@ -0,0 +1,98 @@
|
||||
---
|
||||
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 | 64Mi, `GOMEMLIMIT=50MiB` | 100m |
|
||||
| Each chapter (~10) | 16Mi, `GOMEMLIMIT=12MiB` | 10m |
|
||||
| Analytics ([GoatCounter](/decisions/goatcounter-over-umami.md)) | 64Mi | 50m |
|
||||
|
||||
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] # Cloudflare Tunnel 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,
|
||||
analytics storage 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.
|
||||
@@ -17,7 +17,10 @@ generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
|
||||
| [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`.
|
||||
| Analytics | 1 Deployment, GoatCounter (proposed) | Page views, PDF downloads, falls per chapter. See [decision](/decisions/goatcounter-over-umami.md). |
|
||||
|
||||
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
|
||||
|
||||
|
||||
Reference in new issue
Block a user