docs(okf): replace GoatCounter proposal with own SQLite tracker

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Noel SabiaandClaude Opus 5.5 committed 2026-10-11 14:43:34 +02:00
1 parent 261cf17e52
commit 8e1ea495c4
9 files changed
+67 -54

No files matched your search

+17
View File
@@ -14,6 +14,7 @@ generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
| `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
@@ -42,6 +43,22 @@ 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.
# 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).
+2 -3
View File
@@ -33,9 +33,8 @@ Per workload inside `cv`:
| Workload | Memory limit | CPU limit |
|---|---|---|
| Gateway | 64Mi, `GOMEMLIMIT=50MiB` | 100m |
| Gateway, including the [tracker](/decisions/own-tracker.md) | 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.
@@ -70,7 +69,7 @@ kubelet-arg:
```
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
the tracker's SQLite volume the second. Single-node k3s uses SQLite, not etcd; do not
pass `--cluster-init`.
# Swap
+1 -2
View File
@@ -12,12 +12,11 @@ generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
| Component | Runs as | Job |
|---|---|---|
| Cloudflare Tunnel | `cloudflared` on the home server | Only way in from the internet. Points at the gateway. |
| [Gateway](/architecture/gateway.md) | 1 Deployment, Go | Serves the static site, streams states, forwards knockdowns. 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`. |
| [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. |
| 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).
-38
View File
@@ -1,38 +0,0 @@
---
type: Decision
title: GoatCounter over Umami for analytics
description: Proposed; GoatCounter gives cookie-free open source analytics in about 30 MB, where Umami needs Postgres and about 300-400 MB.
tags: [decision, analytics, resources]
status: draft
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
---
# Proposal
Self-host GoatCounter in namespace `cv` instead of Umami. Needs Noel's
approval as new tooling.
# Why
| | Umami | GoatCounter |
|---|---|---|
| Runtime | Node app | Single Go binary |
| Database | Postgres | SQLite file |
| Memory | ~300-400 MB with Postgres | ~30 MB |
| Cookie-free, no consent banner | Yes | Yes |
| Custom events | Yes | Yes |
| License | Open source | Open source |
On a [4 GB shared server](/architecture/server-budget.md), Umami alone would
match the whole CV budget.
# Track
- Page views.
- PDF CV downloads.
- Falls per chapter.
# Details
One Deployment, 64Mi limit, SQLite on a small `local-path` volume. No backup:
losing analytics hurts nobody.
+1 -4
View File
@@ -3,13 +3,10 @@
* [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.
* [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.
# Proposed
* [GoatCounter over Umami for analytics](goatcounter-over-umami.md) - Proposed; GoatCounter gives cookie-free open source analytics in about 30 MB, where Umami needs Postgres and about 300-400 MB.
# Open
* [Open questions](open-questions.md) - Decisions still to make, with the release that needs each answer.
-1
View File
@@ -15,6 +15,5 @@ generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
| Which Gitea release-please action, exact name | 0.1.0 | None, Noel names it |
| Staging for k6 in CI: namespace or separate cluster | 1.2.0 | Namespace `cv-staging` on the same cluster |
| MCP scope: read-only or read plus `/fall` | 1.1.0 | Read plus `/fall`, same limits as visitors |
| Approve GoatCounter for analytics | 0.9.0 | None, needs Noel |
| 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 |
+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.
+2 -1
View File
@@ -1,7 +1,8 @@
# Update Log
## 2026-10-11
* **Creation**: Added the [server and memory budget](/architecture/server-budget.md) from measured usage, and proposed [GoatCounter over Umami](/decisions/goatcounter-over-umami.md).
* **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).
+8 -5
View File
@@ -25,7 +25,7 @@ generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
| 0.6.0 | First screen | 2 |
| 0.7.0 | Life map | 3 |
| 0.8.0 | Story cards and dev view | 2 |
| 0.9.0 | Analytics | 1 |
| 0.9.0 | Own tracker | 1-2 |
| 1.0.0 | Real content, launch | 2-3 |
| 1.1.0 | MCP endpoint | 1 |
| 1.2.0 | k6 release gate | 2 |
@@ -117,11 +117,14 @@ stays inside the [memory budget](/architecture/server-budget.md).
- Dev view: the raw stream in a `<pre>`.
- **Done when:** two browsers see each other's knockdowns live.
## 0.9.0 Analytics
## 0.9.0 Own tracker
- GoatCounter in `cv`, 64Mi limit, SQLite on a `local-path` volume. Needs approval, see [decision](/decisions/goatcounter-over-umami.md).
- Count page views, PDF downloads and falls per chapter.
- **Done when:** a test visit, a PDF download and a fall all show up in GoatCounter.
- 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.
- Gateway Deployment switches to strategy `Recreate`.
- One test for the upsert and the bot filter.
- **Done when:** 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.
## 1.0.0 Real content and launch