reuse-surface/docs/deploy/reuse-kubernetes.md

reuse-surface Service — Kubernetes Deployment

Companion to RAILIANCE-WP-0007 (railiance-apps Helm release).

Image

gitea.coulomb.social is going away. CoulombCore, which hosts it, is switched off 2026-08-31. Do not push images there and do not deploy anything that references it. Tracked as REUSE-WP-0020.

This repo's canonical remote migrated to Forgejo in REUSE-WP-0019-T03 (origin → forgejo-remote:coulomb/reuse-surface.git; the old Gitea copy is read-only, not deleted). .forgejo/workflows/image.yaml builds and pushes forgejo.coulomb.social/coulomb/reuse-surface:latest and :main-<short-sha> on every push that touches Dockerfile/reuse_surface/**/schemas/**/ pyproject.toml. Prefer promoting a CI-built tag over building by hand.

railiance-apps@04be416 already repointed charts/reuse-surface/values.yaml to the Forgejo repository, but helm/reuse-surface-values.yaml still pins image.tag: "e3ae22e" — a commit from 2026-07-07 18:25, whereas CI only began publishing to Forgejo at 21:25 that day. A Forgejo :e3ae22e tag most likely never existed, so the deployment as written risks ImagePullBackOff on any restart or reschedule today, not only after the retirement date. Verify the tag exists before relying on the current manifest. See REUSE-WP-0020-T05.

If you must build by hand:

docker build -t forgejo.coulomb.social/coulomb/reuse-surface:<tag> .
docker push forgejo.coulomb.social/coulomb/reuse-surface:<tag>

Required environment

Variable	Purpose
REUSE_SURFACE_TOKEN	Bearer token for write API
REUSE_SURFACE_FORGEJO_WEBHOOK_SECRET	HMAC for POST /v1/webhooks/forgejo
REUSE_SURFACE_DB	SQLite path (default /data/reuse.db)
REUSE_SURFACE_CACHE_DIR	Remote index cache (default /data/cache)

Mount a PVC at /data for persistence. Production injects secrets via ExternalSecret reuse-surface-runtime → Kubernetes Secret reuse-surface-env (OpenBao path platform/workloads/reuse/reuse-surface/runtime-secrets, CCR-2026-0005). Operator runbook: railiance-apps/docs/reuse-surface-on-railiance01.md; rotation: railiance-platform/docs/reuse-surface-runtime-secrets-rotation-runbook.md.

Probes

• Liveness/readiness: GET /health on port 8000

Browser landing page

Production ingress routes HTTPS / to a static landing Deployment (reuse-surface-landing, RAILIANCE-WP-0008). API paths are unchanged:

• /health and /v1/* → hub service container
• / → informational HTML for browser visitors (no login, no secrets)

Agents and CLI clients should target /health and /v1/* only, not /.

Public URL and DNS

Item	Value
URL	https://reuse.coulomb.social
DNS A record	92.205.62.239 (Railiance01 production)

CoulombCore (92.205.130.254) held a bootstrap deploy; production release uses KUBECONFIG=~/.kube/config-hosteurope. Verify propagation:

dig +short reuse.coulomb.social A   # must return 92.205.62.239

Client configuration

export REUSE_SURFACE_URL=https://reuse.coulomb.social
export REUSE_SURFACE_TOKEN=<write-token>
reuse-surface hub status

Operational hardening

The hub runs as a single-replica Deployment with SQLite on a PVC (A5 containerized service). A6 (managed platform) is deferred until multi-replica or Postgres backing is required.

Backup and restore (SQLite PVC)

1. Identify the PVC mounted at /data (stores reuse.db and remote index cache).
2. Snapshot or copy while the pod is running (SQLite WAL-safe copy) or scale to zero briefly for a cold copy:

kubectl -n <namespace> exec deploy/reuse-surface -- \
  sqlite3 /data/reuse.db '.backup /tmp/reuse-backup.db'
kubectl -n <namespace> cp deploy/reuse-surface:/tmp/reuse-backup.db ./reuse-backup.db

3. Restore by replacing /data/reuse.db from backup and restarting the pod.
4. Re-register repos if the database is empty (reuse-surface hub list).

Verify backup once per environment after deploy changes.

TLS certificate renewal

Ingress TLS is managed by the cluster cert issuer (Railiance01 companion chart). Monitor certificate expiry on reuse.coulomb.social. Renewal is automatic when the issuer is healthy; on failure, check ingress secret reuse-surface-tls and cert-manager / companion operator logs.

Token rotation

1. Generate a new REUSE_SURFACE_TOKEN value.
2. Update Kubernetes Secret reuse-surface-env.
3. Rolling restart the hub Deployment.
4. Update operator workstations and CI secrets that call write endpoints.
5. Confirm reuse-surface hub register fails with the old token and succeeds with the new token.

Image promotion checklist

1. Tag image from CI commit. .forgejo/workflows/image.yaml already builds and pushes forgejo.coulomb.social/coulomb/reuse-surface:main-<short-sha> automatically on every push that touches Dockerfile/reuse_surface/**/ schemas/**/pyproject.toml — verify it's green rather than building by hand. Confirm the tag exists in the registry before bumping the manifest; GET /v2/coulomb/reuse-surface/tags/list needs registry credentials.
2. Run pytest -q and reuse-surface validate on that commit (CI already does this; re-verify locally if promoting outside CI).
3. Update Helm values image tag in railiance-apps (helm/reuse-surface-values.yaml).
4. Deploy to Railiance01 (make reuse-deploy); verify GET /v1/federated and GET /v1/repos (not GET /health — see the known ingress routing issue below).
5. Smoke reuse-surface hub list and GET /v1/federated capability count; check reuse-surface stats shows a fresh composed_at post-deploy.
6. Record image digest in workplan or progress log.

Known issue (found 2026-07-07, not fixed): the public ingress's exact-path /health rule 404s (shadowed by the catch-all / rule to the landing page) — confirmed ingress-layer only via direct port-forward and the Deployment's own passing readiness/liveness probes. Use GET /v1/repos or GET /v1/federated for external verification instead. Flagged to railiance-apps; not this repo's fix to make (shared ingress template).

SQLite vs Postgres (cnpg) — decision criteria

Stay on SQLite while:

• Single replica is acceptable.
• RPO of occasional PVC snapshot is sufficient.
• Write volume is low (repo registration changes only).

Consider Postgres (e.g. CloudNative-PG) when:

• Multiple hub replicas or zero-downtime failover is required.
• RPO/RTO targets need point-in-time recovery beyond PVC snapshots.
• Federation cache metadata or audit tables grow beyond comfortable SQLite size.

Implementation deferred unless an operator approves migration. Document only until then.