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

reuse-surface Service — Kubernetes Deployment

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

Image

Repository: gitea.coulomb.social/coulomb/reuse-surface (Gitea org coulomb, repo reuse-surface).

docker build -t gitea.coulomb.social/coulomb/reuse-surface:<tag> .
docker push gitea.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: gitea.coulomb.social/coulomb/reuse-surface:<sha>.
2. Run pytest -q and reuse-surface validate on that commit.
3. Update Helm values image tag in railiance-apps.
4. Deploy to Railiance01; verify GET /health and GET /v1/repos.
5. Smoke reuse-surface hub list and GET /v1/federated capability count.
6. Record image digest in workplan or progress log.

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.