chore: publish 25ef5af
Built from main 25ef5af63e
fix: refuse to publish a build that logged a vite error
This commit is contained in:
Marcos Paulo
@@ -1,152 +0,0 @@
|
||||
# vote-service
|
||||
|
||||
Tiny Go HTTP API backing the "prefer original / prefer improved" vote widget
|
||||
on `skills-review/`. One binary, no external dependencies, one JSON file on
|
||||
disk as the store — proportionate to workshop-scale traffic, not a general
|
||||
voting platform.
|
||||
|
||||
## Why a separate service
|
||||
|
||||
`netcracker.pages.marcospaulo.dev.br` is a static Pages Server: it serves
|
||||
files, it cannot run server code or remember state. Any real vote count needs
|
||||
a small stateful service reachable from the visitor's browser, so this lives
|
||||
outside the static repo and runs as its own pod.
|
||||
|
||||
## Anti-abuse: IP, not MAC
|
||||
|
||||
A MAC address is a link-layer detail; it never reaches a server across the
|
||||
internet, so it cannot be used here. "Same source" is approximated by client
|
||||
IP (`X-Forwarded-For` / `X-Real-IP` behind the ingress, else the raw remote
|
||||
address). One IP holds at most one active vote per skill — casting again
|
||||
updates that vote instead of stacking a second one. This is imperfect (NAT,
|
||||
VPNs, shared networks collapse to one vote; IP changes let someone vote
|
||||
again) but matches the ask and needs no cookies, accounts, or client secrets.
|
||||
A `X-Voter-Id` header (a random id the frontend keeps in `localStorage`) is
|
||||
layered on only so a browser can display "you already voted X" — it is never
|
||||
trusted as the sole anti-abuse signal, since `localStorage` is trivially
|
||||
resettable.
|
||||
|
||||
## API
|
||||
|
||||
| Method | Path | Body | Response |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `GET` | `/api/votes` | — | `{ "tallies": { "<skillId>": { "original": n, "improved": n } } }` |
|
||||
| `GET` | `/api/votes?skillId=X` | — | adds `"you": "original"\|"improved"` when the caller's IP already voted on `X` |
|
||||
| `POST` | `/api/votes` | `{"skillId":"X","choice":"original"\|"improved"}` | `{"skillId","original","improved","you"}` |
|
||||
| `GET` | `/healthz` | — | `200` |
|
||||
|
||||
## Run locally
|
||||
|
||||
```bash
|
||||
go run . # PORT=8080 VOTE_DB_PATH=/tmp/votes.json ALLOWED_ORIGIN=http://localhost:4173
|
||||
```
|
||||
|
||||
## Build and publish the image
|
||||
|
||||
Pushed to this cluster's Nexus registry (docker-hosted repo, anonymous read
|
||||
already enabled cluster-wide — no `imagePullSecrets` needed). Push host and
|
||||
pull host differ because Nexus is reached from a workstation via its NodePort
|
||||
but from inside the cluster via its Service DNS name:
|
||||
|
||||
```bash
|
||||
docker build -t localhost:30892/ai-for-dummies-vote-service:latest .
|
||||
docker push localhost:30892/ai-for-dummies-vote-service:latest
|
||||
# pods pull the same image as: nexus-service.nexus.svc.cluster.local:8082/ai-for-dummies-vote-service:latest
|
||||
```
|
||||
|
||||
## Deploy (microk8s)
|
||||
|
||||
The `ai-for-dummies-vote-data` PVC uses `microk8s-hostpath`, whose PVs carry a
|
||||
`nodeAffinity` for whichever node first binds them — so scheduling and storage
|
||||
must agree on one node. This runs on `kubernets` (the control-plane node that
|
||||
hosts the rest of the cluster's workloads), pinned via `nodeSelector` in
|
||||
`deployment.yaml`.
|
||||
|
||||
kubelet's image pulls run in the *host* network namespace and there is no
|
||||
`certs.d/hosts.toml` entry for `localhost:30892`, so a plain pull of the Nexus
|
||||
ref fails (`no basic auth credentials`). Push to Nexus for a durable off-node
|
||||
copy, then import straight into that node's containerd store and let
|
||||
`imagePullPolicy: Never` skip the network pull entirely — the same pattern the
|
||||
`pragent-webhook` image uses in this cluster:
|
||||
|
||||
```bash
|
||||
docker save localhost:30892/ai-for-dummies-vote-service:latest -o /tmp/vote-service.tar
|
||||
/snap/microk8s/current/bin/ctr --address /var/snap/microk8s/common/run/containerd.sock \
|
||||
--namespace k8s.io image import /tmp/vote-service.tar
|
||||
# use microk8s's own bundled ctr, not the host's — different containerd major
|
||||
# versions speak incompatible client/server protocols (`unknown service
|
||||
# containerd.services.streaming.v1.Streaming` otherwise)
|
||||
|
||||
microk8s kubectl apply -f deploy/deployment.yaml # namespace + Deployment + PVC + Service
|
||||
microk8s kubectl apply -f deploy/ingress.yaml
|
||||
microk8s kubectl -n ai-for-dummies rollout restart deploy ai-for-dummies-vote
|
||||
```
|
||||
|
||||
Re-run the `docker save`/`ctr image import` pair after every image rebuild —
|
||||
`imagePullPolicy: Never` means the cluster never fetches a newer tag on its
|
||||
own, and a `rollout restart` is what picks the new image up.
|
||||
|
||||
## Public exposure
|
||||
|
||||
Public traffic reaches the cluster through **Caddy on the Oracle VPS over
|
||||
Tailscale**, which is how all ~21 public hosts in this account are served
|
||||
(`langfuse`, `pragent-dashboard`, `vault`, …) — *not* through the cloudflared
|
||||
tunnel. The tunnel's public-hostname routes are dashboard-managed and the DNS
|
||||
API token cannot write them, so the Caddy path is also the only one that can
|
||||
be automated end to end.
|
||||
|
||||
```bash
|
||||
cf-dns add ai-for-dummies-vote A 129.148.56.8 # DNS-only (grey cloud), like every other Caddy host
|
||||
```
|
||||
|
||||
Caddy block (`/etc/caddy/Caddyfile` on the VPS, local copy `~/scripts/Caddyfile`):
|
||||
|
||||
```caddyfile
|
||||
ai-for-dummies-vote.marcospaulo.dev.br {
|
||||
tls {
|
||||
dns cloudflare <CF_TOKEN>
|
||||
}
|
||||
reverse_proxy 100.74.17.70:80 {
|
||||
header_up Host {host}
|
||||
header_up X-Client-IP {remote_host}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
It proxies to port `80` (not a NodePort): the cluster's nginx ingress runs on
|
||||
`hostNetwork` on `kubernets` and routes by `Host`.
|
||||
|
||||
### Why `X-Client-IP`
|
||||
|
||||
The ingress controller runs with `use-forwarded-headers` **off** (the microk8s
|
||||
default — `nginx-load-balancer-microk8s-conf` has no `data`). nginx therefore
|
||||
*overwrites* `X-Forwarded-For` and `X-Real-IP` with its own downstream peer,
|
||||
which is the VPS's tailnet address `100.67.25.57`. Every visitor would collapse
|
||||
into one voter, and since one IP holds at most one active vote per skill, each
|
||||
skill would only ever hold a single vote in total — the anti-abuse rule would
|
||||
silently become a hard cap.
|
||||
|
||||
Rather than flip `use-forwarded-headers` globally (it would change client-IP
|
||||
handling for every other ingress in the cluster), Caddy stamps the true remote
|
||||
address into `X-Client-IP`, a non-standard header nginx forwards untouched, and
|
||||
`clientIP()` reads it first. `header_up` sets it unconditionally, so a public
|
||||
client cannot spoof it; the trust placed in it is exactly the trust already
|
||||
placed in `X-Forwarded-For`.
|
||||
|
||||
Verified after deploy: requests from two distinct sources are recorded as two
|
||||
separate votes rather than overwriting one another.
|
||||
|
||||
## Frontend wiring
|
||||
|
||||
`skills-review/index.html` sets `window.SKILLS_REVIEW_VOTE_API` to
|
||||
`https://ai-for-dummies-vote.marcospaulo.dev.br`; keep it in sync with
|
||||
`ALLOWED_ORIGIN` in `deployment.yaml`
|
||||
(`https://netcracker.pages.marcospaulo.dev.br`), which is the real caller
|
||||
boundary — CORS restricts which origin's browser code may call the API, not
|
||||
which network can reach it.
|
||||
|
||||
`replicas: 1` and `strategy: Recreate` are deliberate: the store is one file
|
||||
on one `ReadWriteOnce` PVC, so two pods writing it concurrently would race.
|
||||
Scale up only after moving the store to something that supports concurrent
|
||||
writers (e.g. SQLite on a shared volume with proper locking, or Postgres) —
|
||||
not needed at this traffic scale.
|
||||
Reference in New Issue
Block a user