Ops: Bump manifests for v1.1.0 release

API responses now include file_url and thumbnail_url fields. When
S3_PUBLIC_BASE_URL is configured, these point to the CDN domain;
when unset, they fall back to the existing API proxy paths so local
dev requires no additional setup. UI updated to use response URL
fields directly instead of constructing proxy URLs client-side.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.env.example

@@ -11,6 +11,10 @@ S3_REGION=us-east-1
 # Angular SPA — injected at build or runtime
 API_BASE_URL=http://localhost:8000
 
+# CDN base URL for serving images (e.g. https://cdn.example.com).
+# Leave empty in local dev to use API proxy fallback.
+S3_PUBLIC_BASE_URL=
+
 # Upload size limit in bytes (default 50 MiB)
 MAX_UPLOAD_BYTES=52428800
 

.specify/feature.json

@@ -1,3 +1 @@
-{
-  "feature_directory": "specs/012-api-docs-gate"
-}
+{"feature_directory": "specs/014-r2-cdn-serving"}

.specify/memory/constitution.md

@@ -1,8 +1,8 @@
 <!--
 SYNC IMPACT REPORT
 ==================
-Version change: 1.2.0 → 1.3.0
-Ratified: 2026-05-01 | Last amended: 2026-05-06
+Version change: 1.3.0 → 1.4.0
+Ratified: 2026-05-01 | Last amended: 2026-05-08
 
 Principles introduced (first population from docs/CONSTITUTION.md):
   - §2  Architecture Principles (6 sub-principles)
@@ -171,11 +171,14 @@ OR/NOT logic is explicitly out of scope until the constitution is revised.
 
 ## 5. Testing Discipline
 
-### 5.1 TDD is non-negotiable
+### 5.1 Tests are required alongside every implementation task
 
-No production code MAY be written before a failing test exists for it. This
-applies to both API and UI. Tasks MUST include a "write failing test" step
-before any implementation step.
+Every implementation task MUST be accompanied by tests covering its behaviour.
+The ideal is red-green-refactor: write a failing test, then make it pass. In
+practice, tests written in the same task as the implementation are acceptable;
+what is non-negotiable is that no implementation task is marked done without
+corresponding test coverage. Tasks MUST NOT be split such that implementation
+is complete but tests are deferred to a later task.
 
 ### 5.2 Test pyramid
 
@@ -194,10 +197,15 @@ Unit and integration tests are required. E2E tests are best-effort in v1.
 API tests in `api/tests/`, UI tests colocated with their components. No
 separate top-level `tests/` directory that mirrors the source tree.
 
-### 5.4 CI must pass before any task is considered done
+### 5.4 The test suite must pass before any task is considered done
 
 "Done" means: all tests pass, linter passes, type checker passes. A task MUST
-NOT be marked complete while CI is failing.
+NOT be marked complete while any of these are failing.
+
+The acceptance gate is `make test-unit && make test-integration` plus `ruff
+check` / `ruff format --check` for the API. A formal CI pipeline is planned
+but not yet in place; until one exists, passing the above commands locally is
+the required gate. When CI is introduced it MUST enforce the same checks.
 
 ---
 
@@ -214,6 +222,9 @@ NOT be marked complete while CI is failing.
 | UI framework     | Angular (latest stable)                   | Job-relevant, learning goal               |
 | UI language      | TypeScript strict mode                    | No `any`, no implicit types               |
 | Containerisation | Docker + Docker Compose                   | Local dev must start with one command     |
+| Production runtime | k3s (Kubernetes)                        | Manifests in `k8s/`; see deployment docs  |
+| Ingress          | nginx ingress controller + cert-manager   | TLS via Let's Encrypt (`letsencrypt-prod` ClusterIssuer) |
+| Secret management | HashiCorp Vault + VSO (Vault Secrets Operator) | Secrets never committed; VSO syncs Vault KV v2 → K8s Secrets |
 
 ---
 
@@ -251,6 +262,15 @@ revised:
 - Mobile-native app
 - OIDC auth (planned Phase 3)
 
+**Known gaps carried forward from v1** — these are not out of scope; they are
+acknowledged deficiencies that MUST be resolved before the affected area is
+expanded:
+
+- **Password hashing**: The owner password is currently stored and compared in
+  plaintext. Hashing (bcrypt or Argon2) MUST be implemented before any
+  additional authentication work (e.g. OIDC, additional accounts) is started.
+  Specs that touch credential storage MUST address this first.
+
 ---
 
 ## 9. Governance
@@ -289,7 +309,8 @@ Phase 1 design is complete.
 | 1.1.1   | 2026-05-03 | Clarify that the only acceptable form of image transformation or editing is thumbnail generation                                |
 | 1.2.0   | 2026-05-03 | §2.4: Mark Phase 2 (JWT bearer auth) complete, reword phase status; §6: Add PyJWT to tech stack table; §8: Remove username/password auth from out-of-scope (now shipped) |
 | 1.3.0   | 2026-05-06 | §2.5: Remove planned PostgreSQL → SQLite refactor note; prohibit alternative database engines in integration tests. §5.2: Explicitly require PostgreSQL for integration tests; prohibit SQLite — a production HAVING/GROUP BY bug was masked by SQLite's permissive dialect. |
+| 1.4.0   | 2026-05-08 | §5.1: Soften strict TDD wording to reflect actual practice — tests alongside implementation are acceptable; deferring tests to a later task is not. §5.4: Replace "CI must pass" with local test suite gate; note CI is planned but not yet in place. §6: Add production runtime rows (k3s, nginx ingress + cert-manager, Vault + VSO). §8: Add "known gaps" subsection; document plaintext password storage as a deficiency that must be resolved before further auth work. |
 
 ---
 
-**Version**: 1.3.0 | **Ratified**: 2026-05-01 | **Last Amended**: 2026-05-06
+**Version**: 1.4.0 | **Ratified**: 2026-05-01 | **Last Amended**: 2026-05-08

.yamllint.yml

@@ -0,0 +1,4 @@
+extends: relaxed
+rules:
+  line-length:
+    max: 120

CLAUDE.md

@@ -1,5 +1,5 @@
 <!-- SPECKIT START -->
 For additional context about technologies to be used, project structure,
 shell commands, and other important information, read the current plan at
-`specs/012-api-docs-gate/plan.md`.
+`specs/014-r2-cdn-serving/plan.md`.
 <!-- SPECKIT END -->

Makefile

@@ -1,4 +1,4 @@
-.PHONY: test-unit test-integration build-prod verify-prod build-ui-prod verify-ui-prod
+.PHONY: test-unit test-integration build-prod verify-prod build-ui-prod verify-ui-prod validate-k8s
 
 test-unit:
 	cd api && python -m pytest tests/unit/ -v
@@ -18,3 +18,8 @@ build-ui-prod:
 
 verify-ui-prod:
 	bash ui/tests/build/verify_production_image.sh
+
+# Offline: yamllint only. Online (requires kubeconfig): kubectl apply --dry-run=client -f k8s/
+validate-k8s:
+	yamllint -d relaxed k8s/
+	kubectl apply --dry-run=client -f k8s/

README.md

@@ -2,3 +2,141 @@
 _Organize your reaction images._
 
 ![Reactbin UI](.img/reactbin-ui.png)
+
+A self-hosted reaction image board. Single owner account, tag-based browsing, S3-compatible image storage.
+
+---
+
+## Local development
+
+```bash
+cp .env.example .env
+# Edit .env — defaults work out of the box for local dev
+docker compose up
+```
+
+- UI: http://localhost:4200
+- API: http://localhost:8000
+- MinIO console: http://localhost:9001 (minioadmin / minioadmin)
+
+The API serves on port 8000 directly in dev. In production the nginx ingress routes `/api/` there.
+
+### Running tests
+
+```bash
+make test-unit          # pytest unit tests (no Docker)
+make test-integration   # builds api-test image, runs full suite against Postgres + MinIO
+```
+
+### Production image builds
+
+```bash
+make build-prod         # builds reactbin-api-prod:latest from api/Dockerfile.prod
+make verify-prod        # smoke-tests the production image
+make build-ui-prod      # builds reactbin-ui-prod:latest from ui/Dockerfile.prod
+make verify-ui-prod     # smoke-tests the production UI image
+```
+
+---
+
+## Production deployment (k3s)
+
+### Cluster prerequisites
+
+- nginx ingress controller
+- cert-manager with a `letsencrypt-prod` ClusterIssuer
+- Vault Secrets Operator (VSO) installed and connected to Vault
+- Vault KV v2 secrets populated (see below)
+
+### Vault secrets
+
+Two KV v2 paths. VSO syncs these into Kubernetes Secrets automatically.
+
+**`reactbin/api/config`** → K8s Secret `api-env`
+
+| Key | Notes |
+|-----|-------|
+| `DATABASE_URL` | `postgresql+asyncpg://user:pass@host:5432/db` |
+| `JWT_SECRET_KEY` | Long random string — `openssl rand -base64 48` |
+| `OWNER_USERNAME` | Login username |
+| `OWNER_PASSWORD` | Login password |
+| `S3_ENDPOINT_URL` | `http://minio.reactbin.svc.cluster.local:9000` |
+| `S3_BUCKET_NAME` | `reactbin` |
+| `S3_ACCESS_KEY_ID` | Same value as `MINIO_ROOT_USER` |
+| `S3_SECRET_ACCESS_KEY` | Same value as `MINIO_ROOT_PASSWORD` |
+| `API_BASE_URL` | `https://<your-domain>` |
+| `LOGIN_TRUSTED_PROXY_IPS` | Pod CIDR of nginx ingress pods, e.g. `10.42.0.0/16` — needed for per-client login rate limiting behind the ingress |
+
+**`reactbin/minio/credentials`** → K8s Secret `minio-credentials`
+
+| Key | Notes |
+|-----|-------|
+| `MINIO_ROOT_USER` | MinIO admin username |
+| `MINIO_ROOT_PASSWORD` | `openssl rand -base64 32` |
+
+### Apply order
+
+```bash
+# 1. Namespace first
+kubectl apply -f k8s/namespace.yaml
+
+# 2. Vault CRDs — wait for VSO to create api-env and minio-credentials Secrets
+kubectl apply -f k8s/vault/
+kubectl get secret -n reactbin api-env minio-credentials   # wait until both appear
+
+# 3. API, UI, Ingress — replace 'latest' tags and <your-domain> first
+kubectl apply -f k8s/api/ -f k8s/ui/ -f k8s/ingress.yaml
+kubectl rollout status deployment/api -n reactbin          # Alembic init container runs here
+
+# 4. MinIO — wait for StatefulSet ready before running the bucket init Job
+kubectl apply -f k8s/minio/service.yaml -f k8s/minio/statefulset.yaml
+kubectl rollout status statefulset/minio -n reactbin
+kubectl apply -f k8s/minio/init-job.yaml
+```
+
+Before applying: substitute real image tags in the Deployment manifests and replace `<your-domain>` in `k8s/ingress.yaml`.
+
+### Updating a secret
+
+1. Update the value in Vault
+2. Force VSO to sync immediately (otherwise waits up to 1 hour):
+   ```bash
+   kubectl annotate vaultstaticsecret api-secret -n reactbin \
+     secrets.hashicorp.com/force-sync=$(date +%s) --overwrite
+   ```
+3. Restart the deployment to pick up the new Secret:
+   ```bash
+   kubectl rollout restart deployment/api -n reactbin
+   ```
+
+### Validating manifests
+
+```bash
+make validate-k8s   # yamllint + kubectl apply --dry-run=client (requires kubeconfig)
+```
+
+---
+
+## Environment variables reference
+
+All variables are read at startup from environment / `.env`.
+
+| Variable | Default | Notes |
+|----------|---------|-------|
+| `DATABASE_URL` | — | Async DSN: `postgresql+asyncpg://...` |
+| `JWT_SECRET_KEY` | — | Required; use a long random string in production |
+| `JWT_EXPIRY_SECONDS` | `86400` | Token lifetime (24 h) |
+| `OWNER_USERNAME` | — | Single owner account username |
+| `OWNER_PASSWORD` | — | Single owner account password |
+| `S3_ENDPOINT_URL` | — | MinIO or any S3-compatible endpoint |
+| `S3_BUCKET_NAME` | `reactbin` | |
+| `S3_ACCESS_KEY_ID` | — | |
+| `S3_SECRET_ACCESS_KEY` | — | |
+| `S3_REGION` | `us-east-1` | |
+| `MAX_UPLOAD_BYTES` | `52428800` | 50 MiB |
+| `API_BASE_URL` | — | Used for generating public URLs |
+| `API_DOCS_ENABLED` | `true` | Set to `false` in production |
+| `LOGIN_MAX_FAILURES` | `5` | Failed attempts before cooldown |
+| `LOGIN_WINDOW_SECONDS` | `300` | Sliding window for failure count |
+| `LOGIN_COOLDOWN_SECONDS` | `900` | Lock duration after threshold hit |
+| `LOGIN_TRUSTED_PROXY_IPS` | `""` | Comma-separated CIDRs of trusted upstream proxies |

api/Dockerfile.prod

@@ -35,6 +35,8 @@ RUN groupadd --system --gid 1001 appgroup \
 
 COPY --from=builder --chown=appuser:appgroup /app/.venv /app/.venv
 COPY --chown=appuser:appgroup app/ ./app/
+COPY --chown=appuser:appgroup alembic/ ./alembic/
+COPY --chown=appuser:appgroup alembic.ini .
 
 USER appuser
 

api/app/config.py

@@ -14,6 +14,7 @@ class Settings(BaseSettings):
     s3_secret_access_key: str
     s3_region: str = "us-east-1"
     api_base_url: str = "http://localhost:8000"
+    s3_public_base_url: str | None = None
     max_upload_bytes: int = 52_428_800  # 50 MiB
     jwt_secret_key: str
     jwt_expiry_seconds: int = 86400

api/app/routers/images.py

@@ -27,7 +27,16 @@ def _error(detail: str, code: str, status: int):
     raise HTTPException(status_code=status, detail={"detail": detail, "code": code})
 
 
-def _image_to_dict(image: Image, *, duplicate: bool | None = None) -> dict[str, Any]:
+def _image_to_dict(
+    image: Image, *, cdn_base: str | None = None, duplicate: bool | None = None
+) -> dict[str, Any]:
+    _base = cdn_base.rstrip("/") if cdn_base else None
+    file_url = f"{_base}/{image.storage_key}" if _base else f"/api/v1/images/{image.id}/file"
+    thumbnail_url = (
+        (f"{_base}/{image.thumbnail_key}" if _base else f"/api/v1/images/{image.id}/thumbnail")
+        if image.thumbnail_key
+        else None
+    )
     data: dict[str, Any] = {
         "id": str(image.id),
         "hash": image.hash,
@@ -38,6 +47,8 @@ def _image_to_dict(image: Image, *, duplicate: bool | None = None) -> dict[str,
         "height": image.height,
         "storage_key": image.storage_key,
         "thumbnail_key": image.thumbnail_key,
+        "file_url": file_url,
+        "thumbnail_url": thumbnail_url,
         "created_at": image.created_at.isoformat(),
         "tags": image.tags,
     }
@@ -133,10 +144,13 @@ async def upload_image(
 
     hash_hex = compute_sha256(data)
     image_repo = ImageRepository(db)
+    _cdn_base = settings.s3_public_base_url
     existing = await image_repo.get_by_hash(hash_hex)
     if existing:
         return Response(
-            content=__import__("json").dumps(_image_to_dict(existing, duplicate=True)),
+            content=__import__("json").dumps(
+                _image_to_dict(existing, cdn_base=_cdn_base, duplicate=True)
+            ),
             status_code=200,
             media_type="application/json",
         )
@@ -183,7 +197,7 @@ async def upload_image(
         await tag_repo.attach_tags(image, tag_names)
         image = await image_repo.reload_with_tags(image.id)
 
-    return _image_to_dict(image, duplicate=False)
+    return _image_to_dict(image, cdn_base=_cdn_base, duplicate=False)
 
 
 @router.get("/images")
@@ -192,13 +206,15 @@ async def list_images(
     limit: int = 50,
     offset: int = 0,
     db: AsyncSession = Depends(get_db),
+    settings=Depends(get_settings),
 ):
     limit = min(limit, 100)
+    _cdn_base = settings.s3_public_base_url
     tag_names = [t.strip() for t in tags.split(",") if t.strip()] if tags else None
     image_repo = ImageRepository(db)
     images, total = await image_repo.list_images(tag_names=tag_names, limit=limit, offset=offset)
     return {
-        "items": [_image_to_dict(img) for img in images],
+        "items": [_image_to_dict(img, cdn_base=_cdn_base) for img in images],
         "total": total,
         "limit": limit,
         "offset": offset,
@@ -209,7 +225,9 @@ async def list_images(
 async def get_image(
     image_id: uuid.UUID,
     db: AsyncSession = Depends(get_db),
+    settings=Depends(get_settings),
 ):
+    _cdn_base = settings.s3_public_base_url
     image_repo = ImageRepository(db)
     image = await image_repo.get_by_id(image_id)
     if not image:
@@ -217,7 +235,7 @@ async def get_image(
             status_code=404,
             detail={"detail": "Image not found", "code": "image_not_found"},
         )
-    return _image_to_dict(image)
+    return _image_to_dict(image, cdn_base=_cdn_base)
 
 
 @router.get("/images/{image_id}/file")
@@ -288,7 +306,9 @@ async def update_image_tags(
     body: dict,
     db: AsyncSession = Depends(get_db),
     _: Identity = Depends(require_auth),
+    settings=Depends(get_settings),
 ):
+    _cdn_base = settings.s3_public_base_url
     image_repo = ImageRepository(db)
     image = await image_repo.get_by_id(image_id)
     if not image:
@@ -309,7 +329,7 @@ async def update_image_tags(
 
     await tag_repo.replace_tags_on_image(image, tag_names)
     image = await image_repo.reload_with_tags(image.id)
-    return _image_to_dict(image)
+    return _image_to_dict(image, cdn_base=_cdn_base)
 
 
 @router.delete("/images/{image_id}", status_code=204)

api/tests/integration/test_upload.py

@@ -132,6 +132,10 @@ async def test_upload_returns_thumbnail_key(authed_client):
     assert "thumbnail_key" in body
     assert body["thumbnail_key"] is not None
     assert body["thumbnail_key"].endswith("-thumb")
+    assert "file_url" in body
+    assert body["file_url"].startswith("/api/v1/images/")
+    assert "thumbnail_url" in body
+    assert body["thumbnail_url"].startswith("/api/v1/images/")
 
 
 @pytest.mark.asyncio
@@ -172,3 +176,6 @@ async def test_upload_succeeds_when_thumbnail_fails(authed_client):
     assert response.status_code in (200, 201)
     body = response.json()
     assert body["thumbnail_key"] is None
+    assert "file_url" in body
+    assert body["file_url"].startswith("/api/v1/images/")
+    assert body["thumbnail_url"] is None

api/tests/unit/test_url_construction.py

@@ -0,0 +1,58 @@
+import uuid
+from unittest.mock import MagicMock
+
+import pytest
+
+from app.routers.images import _image_to_dict
+
+
+def _make_image(*, thumbnail_key=None):
+    img = MagicMock()
+    img.id = uuid.UUID("00000000-0000-0000-0000-000000000001")
+    img.hash = "abc123"
+    img.filename = "test.jpg"
+    img.mime_type = "image/jpeg"
+    img.size_bytes = 1024
+    img.width = 100
+    img.height = 100
+    img.storage_key = "abc123storagekey"
+    img.thumbnail_key = thumbnail_key
+    img.created_at.isoformat.return_value = "2026-05-09T00:00:00"
+    img.tags = []
+    return img
+
+
+def test_cdn_configured_with_thumbnail():
+    img = _make_image(thumbnail_key="abc123storagekey-thumb")
+    result = _image_to_dict(img, cdn_base="https://cdn.example.com")
+    assert result["file_url"] == "https://cdn.example.com/abc123storagekey"
+    assert result["thumbnail_url"] == "https://cdn.example.com/abc123storagekey-thumb"
+
+
+def test_cdn_configured_no_thumbnail():
+    img = _make_image(thumbnail_key=None)
+    result = _image_to_dict(img, cdn_base="https://cdn.example.com")
+    assert result["file_url"] == "https://cdn.example.com/abc123storagekey"
+    assert result["thumbnail_url"] is None
+
+
+def test_no_cdn_with_thumbnail():
+    img = _make_image(thumbnail_key="abc123storagekey-thumb")
+    result = _image_to_dict(img, cdn_base=None)
+    assert result["file_url"] == "/api/v1/images/00000000-0000-0000-0000-000000000001/file"
+    assert result["thumbnail_url"] == "/api/v1/images/00000000-0000-0000-0000-000000000001/thumbnail"
+
+
+def test_no_cdn_no_thumbnail():
+    img = _make_image(thumbnail_key=None)
+    result = _image_to_dict(img, cdn_base=None)
+    assert result["file_url"] == "/api/v1/images/00000000-0000-0000-0000-000000000001/file"
+    assert result["thumbnail_url"] is None
+
+
+def test_cdn_trailing_slash_normalised():
+    img = _make_image(thumbnail_key="abc123storagekey-thumb")
+    result = _image_to_dict(img, cdn_base="https://cdn.example.com/")
+    assert result["file_url"] == "https://cdn.example.com/abc123storagekey"
+    assert result["thumbnail_url"] == "https://cdn.example.com/abc123storagekey-thumb"
+    assert "//" not in result["file_url"].replace("https://", "")

k8s/api/deployment.yaml

@@ -0,0 +1,52 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: api
+  namespace: reactbin
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: api
+  template:
+    metadata:
+      labels:
+        app: api
+    spec:
+      initContainers:
+        - name: migrate
+          image: git.juggalol.com/juggalol/reactbin-api:v1.1.0
+          command: ["alembic", "upgrade", "head"]
+          workingDir: /app
+          envFrom:
+            - secretRef:
+                name: api-env
+          securityContext:
+            runAsNonRoot: true
+            runAsUser: 1001
+      containers:
+        - name: api
+          image: git.juggalol.com/juggalol/reactbin-api:v1.1.0
+          ports:
+            - containerPort: 8000
+          envFrom:
+            - secretRef:
+                name: api-env
+          env:
+            - name: API_DOCS_ENABLED
+              value: "false"
+          livenessProbe:
+            httpGet:
+              path: /api/v1/health
+              port: 8000
+            initialDelaySeconds: 10
+            periodSeconds: 30
+          readinessProbe:
+            httpGet:
+              path: /api/v1/health
+              port: 8000
+            initialDelaySeconds: 5
+            periodSeconds: 10
+          securityContext:
+            runAsNonRoot: true
+            runAsUser: 1001

k8s/api/service.yaml

@@ -0,0 +1,13 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: api
+  namespace: reactbin
+spec:
+  type: ClusterIP
+  selector:
+    app: api
+  ports:
+    - name: http
+      port: 8000
+      targetPort: 8000

k8s/ingress.yaml

@@ -0,0 +1,34 @@
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: reactbin
+  namespace: reactbin
+  annotations:
+    cert-manager.io/cluster-issuer: letsencrypt-prod
+    kubernetes.io/tls-acme: "true"
+    nginx.ingress.kubernetes.io/ssl-redirect: "true"
+    nginx.ingress.kubernetes.io/proxy-body-size: "52m"
+spec:
+  ingressClassName: nginx-public
+  tls:
+    - hosts:
+        - reactbin.juggalol.com
+      secretName: reactbin-tls
+  rules:
+    - host: reactbin.juggalol.com
+      http:
+        paths:
+          - path: /api/
+            pathType: Prefix
+            backend:
+              service:
+                name: api
+                port:
+                  number: 8000
+          - path: /
+            pathType: Prefix
+            backend:
+              service:
+                name: ui
+                port:
+                  number: 8080

k8s/minio/init-job.yaml

@@ -0,0 +1,24 @@
+apiVersion: batch/v1
+kind: Job
+metadata:
+  name: minio-init
+  namespace: reactbin
+spec:
+  template:
+    spec:
+      restartPolicy: OnFailure
+      containers:
+        - name: mc
+          image: minio/mc:latest
+          # mc runs as root by default; FR-013 exception documented in spec
+          securityContext:
+            runAsNonRoot: false
+          command:
+            - sh
+            - -c
+            - |
+              mc alias set local http://minio:9000 "$MINIO_ROOT_USER" "$MINIO_ROOT_PASSWORD"
+              mc mb --ignore-existing local/reactbin
+          envFrom:
+            - secretRef:
+                name: minio-credentials

k8s/minio/service.yaml

@@ -0,0 +1,16 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: minio
+  namespace: reactbin
+spec:
+  type: ClusterIP
+  selector:
+    app: minio
+  ports:
+    - name: api
+      port: 9000
+      targetPort: 9000
+    - name: console
+      port: 9001
+      targetPort: 9001

k8s/minio/statefulset.yaml

@@ -0,0 +1,59 @@
+apiVersion: apps/v1
+kind: StatefulSet
+metadata:
+  name: minio
+  namespace: reactbin
+spec:
+  serviceName: minio
+  replicas: 1
+  selector:
+    matchLabels:
+      app: minio
+  template:
+    metadata:
+      labels:
+        app: minio
+    spec:
+      securityContext:
+        runAsNonRoot: true
+        runAsUser: 1000
+        runAsGroup: 1000
+        fsGroup: 1000
+      containers:
+        - name: minio
+          image: minio/minio:latest
+          args:
+            - server
+            - /data
+            - --console-address
+            - ":9001"
+          ports:
+            - containerPort: 9000
+            - containerPort: 9001
+          envFrom:
+            - secretRef:
+                name: minio-credentials
+          livenessProbe:
+            httpGet:
+              path: /minio/health/live
+              port: 9000
+            initialDelaySeconds: 10
+            periodSeconds: 30
+          readinessProbe:
+            httpGet:
+              path: /minio/health/ready
+              port: 9000
+            initialDelaySeconds: 5
+            periodSeconds: 10
+          volumeMounts:
+            - name: data
+              mountPath: /data
+  volumeClaimTemplates:
+    - metadata:
+        name: data
+      spec:
+        accessModes:
+          - ReadWriteOnce
+        resources:
+          requests:
+            storage: 10Gi

k8s/namespace.yaml

@@ -0,0 +1,4 @@
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: reactbin

k8s/ui/deployment.yaml

@@ -0,0 +1,29 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: ui
+  namespace: reactbin
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: ui
+  template:
+    metadata:
+      labels:
+        app: ui
+    spec:
+      containers:
+        - name: ui
+          image: git.juggalol.com/juggalol/reactbin-ui:v1.1.0
+          ports:
+            - containerPort: 8080
+          livenessProbe:
+            httpGet:
+              path: /
+              port: 8080
+            initialDelaySeconds: 10
+            periodSeconds: 30
+          securityContext:
+            runAsNonRoot: true
+            runAsUser: 101  # nginxinc/nginx-unprivileged default UID

k8s/ui/service.yaml

@@ -0,0 +1,13 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: ui
+  namespace: reactbin
+spec:
+  type: ClusterIP
+  selector:
+    app: ui
+  ports:
+    - name: http
+      port: 8080
+      targetPort: 8080

k8s/vault/api-secret.yaml

@@ -0,0 +1,18 @@
+apiVersion: secrets.hashicorp.com/v1beta1
+kind: VaultStaticSecret
+metadata:
+  name: api-secret
+  namespace: reactbin
+spec:
+  vaultAuthRef: reactbin-vault-auth
+  mount: kv
+  type: kv-v2
+  # Required Vault keys at this path:
+  #   DATABASE_URL, JWT_SECRET_KEY, OWNER_USERNAME, OWNER_PASSWORD,
+  #   S3_ENDPOINT_URL, S3_BUCKET_NAME, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY,
+  #   API_BASE_URL
+  path: reactbin/api/config
+  refreshAfter: 1h
+  destination:
+    name: api-env
+    create: true

k8s/vault/minio-secret.yaml

@@ -0,0 +1,16 @@
+apiVersion: secrets.hashicorp.com/v1beta1
+kind: VaultStaticSecret
+metadata:
+  name: minio-secret
+  namespace: reactbin
+spec:
+  vaultAuthRef: reactbin-vault-auth
+  mount: kv
+  type: kv-v2
+  # Required Vault keys at this path:
+  #   MINIO_ROOT_USER, MINIO_ROOT_PASSWORD
+  path: reactbin/minio/credentials
+  refreshAfter: 1h
+  destination:
+    name: minio-credentials
+    create: true

k8s/vault/vault-auth.yaml

@@ -0,0 +1,22 @@
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: vso-reactbin
+  namespace: reactbin
+---
+apiVersion: secrets.hashicorp.com/v1beta1
+kind: VaultAuth
+metadata:
+  name: reactbin-vault-auth
+  namespace: reactbin
+spec:
+  method: kubernetes
+  mount: kubernetes
+  kubernetes:
+    # The operator must create this role in Vault and bind it to the
+    # default service account in the reactbin namespace with read access
+    # to both reactbin/api/config and reactbin/minio/credentials.
+    role: vso-reactbin
+    serviceAccount: vso-reactbin
+    audiences:
+      - vault

specs/013-k8s-manifests/checklists/requirements.md

@@ -0,0 +1,35 @@
+# Specification Quality Checklist: Kubernetes Production Manifests
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-05-07
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- FR-014 (migration files in production image) is a prerequisite code change to `Dockerfile.prod`, not a manifest. Included in scope as it is required for the init container to function.
+- Image tag placeholder strategy is documented in Assumptions; the specifics of tag substitution (kustomize, sed, etc.) are left to planning.

specs/013-k8s-manifests/contracts/operator-deploy.md

@@ -0,0 +1,59 @@
+# Contract: Operator Deployment Interface
+
+The manifests in `k8s/` define the operator's deployment interface — the inputs required before applying and the observable outputs after applying.
+
+## Pre-deployment Prerequisites (Operator-supplied)
+
+| Prerequisite | Details |
+|---|---|
+| Vault KV v2 secret at `reactbin/api/config` | Must contain keys: `DATABASE_URL`, `JWT_SECRET_KEY`, `OWNER_USERNAME`, `OWNER_PASSWORD`, `S3_ENDPOINT_URL`, `S3_BUCKET_NAME`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `API_BASE_URL` |
+| Vault KV v2 secret at `reactbin/minio/credentials` | Must contain keys: `MINIO_ROOT_USER`, `MINIO_ROOT_PASSWORD` |
+| Vault Kubernetes auth role | A role in the Vault Kubernetes auth mount bound to the `default` service account in the `reactbin` namespace with read access to both paths above |
+| `VaultConnection` resource | Named `default` in the operator's VSO namespace pointing to the Vault server address |
+| External PostgreSQL database | A dedicated database and user created; `DATABASE_URL` in Vault reflects the credentials |
+| DNS | The production domain resolves to the cluster ingress IP |
+| `ClusterIssuer` | A cert-manager `ClusterIssuer` named `letsencrypt-prod` exists in the cluster |
+| Image tags | The operator substitutes the `latest` placeholder in `k8s/api/deployment.yaml` and `k8s/ui/deployment.yaml` with the real image tag before applying |
+
+## Apply Command
+
+```bash
+# Substitute image tags
+sed -i 's|reactbin-api:latest|reactbin-api:<tag>|g' k8s/api/deployment.yaml
+sed -i 's|reactbin-ui:latest|reactbin-ui:<tag>|g' k8s/ui/deployment.yaml
+
+# Apply all manifests
+kubectl apply -f k8s/
+```
+
+Applying is idempotent — safe to re-run on every deployment.
+
+## Observable Outputs (Post-apply)
+
+| Resource | Expected State |
+|---|---|
+| `Namespace/reactbin` | Active |
+| `Deployment/api` in `reactbin` | 1/1 Ready (init container completes first) |
+| `Deployment/ui` in `reactbin` | 1/1 Ready |
+| `StatefulSet/minio` in `reactbin` | 1/1 Ready |
+| `Job/minio-init-bucket` in `reactbin` | Completed |
+| `Secret/api-env` in `reactbin` | Created by VSO, populated with all API env keys |
+| `Secret/minio-credentials` in `reactbin` | Created by VSO, populated with MinIO root keys |
+| `Certificate/reactbin-tls` in `reactbin` | Issued (may take up to 2 minutes on first apply) |
+| `Ingress/reactbin` in `reactbin` | Address populated with cluster ingress IP |
+
+## Verification Commands
+
+```bash
+# All pods running
+kubectl get pods -n reactbin
+
+# API health
+curl -sf https://<domain>/api/v1/health
+
+# UI reachable
+curl -sf https://<domain>/
+
+# Docs correctly gated (should return 404)
+curl -o /dev/null -w "%{http_code}" https://<domain>/docs
+```

specs/013-k8s-manifests/plan.md

@@ -0,0 +1,238 @@
+# Implementation Plan: Kubernetes Production Manifests
+
+**Branch**: `013-k8s-manifests` | **Date**: 2026-05-07 | **Spec**: [spec.md](spec.md)
+**Input**: Feature specification from `specs/013-k8s-manifests/spec.md`
+
+## Summary
+
+Write Kubernetes manifests deploying Reactbin to k3s: a `Namespace`, API `Deployment` (with Alembic init container) + `Service`, UI `Deployment` + `Service`, a shared `Ingress` with Let's Encrypt TLS, a MinIO `StatefulSet` + `Service` + bucket-init `Job`, and three VSO CRDs (`VaultConnection`, `VaultAuth`, `VaultStaticSecret` × 2) to sync secrets from Vault. A small update to `api/Dockerfile.prod` includes Alembic migration files in the production image so the init container can run them.
+
+## Technical Context
+
+**Language/Version**: YAML (Kubernetes manifests); Python 3.12 (Dockerfile.prod touch)
+**Primary Dependencies**: Kubernetes 1.29+ API, nginx Ingress controller, cert-manager (ClusterIssuer `letsencrypt-prod`), Vault Secrets Operator (`secrets.hashicorp.com/v1beta1`), MinIO
+**Storage**: MinIO StatefulSet with ReadWriteOnce PVC (cluster default storage class); external PostgreSQL (operator-provisioned)
+**Testing**: `kubectl apply --dry-run=client` for schema validation; `yamllint` for formatting
+**Target Platform**: k3s cluster (Kubernetes 1.29+, Linux)
+**Performance Goals**: No measurable impact — manifests are declarative config, not runtime code
+**Constraints**: All secrets must come from Vault (no plaintext in manifests); all containers run non-root; MinIO is ClusterIP-only (no external Ingress)
+**Scale/Scope**: 11 YAML files across `k8s/`; one Dockerfile.prod change; one Makefile target
+
+## Constitution Check
+
+| Principle | Requirement | Status |
+|-----------|-------------|--------|
+| §5.1 TDD | Failing tests before implementation | ✅ Dry-run validation script written before manifests |
+| §5.4 CI before done | All tests pass before task marked done | ✅ kubectl dry-run + yamllint gate |
+| §7.2 Env config | No hardcoded secrets or hostnames | ✅ All secrets via VSO; domain is operator-substituted placeholder |
+| §7.3 Linting | `ruff` / linting passes | ✅ `yamllint` on all manifests |
+| §2.6 No speculative abstraction | No Kustomize overlays or Helm chart | ✅ Plain YAML, single environment |
+| §8 Scope boundaries | No multi-user, no OIDC, no OR/NOT tags | ✅ Not affected |
+
+**No violations. All gates pass.**
+
+*Post-design re-check*: The Dockerfile.prod change (FR-014) adds `alembic/` to the runtime stage only — no builder-stage change, no new dependencies, no behaviour change to the running API. Constitution unchanged.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/013-k8s-manifests/
+├── plan.md                          ← this file
+├── research.md                      ← 8 decisions
+├── contracts/
+│   └── operator-deploy.md           ← prerequisites + verification commands
+├── quickstart.md                    ← deploy + verify + scenario walkthroughs
+└── tasks.md                         ← generated by /speckit-tasks
+```
+
+### Source Code Changes
+
+```text
+k8s/                                 ← NEW directory
+├── namespace.yaml                   ← Namespace: reactbin
+├── api/
+│   ├── deployment.yaml              ← Deployment: api (with alembic init container)
+│   └── service.yaml                 ← Service: api (ClusterIP, port 8000)
+├── ui/
+│   ├── deployment.yaml              ← Deployment: ui
+│   └── service.yaml                 ← Service: ui (ClusterIP, port 8080)
+├── ingress.yaml                     ← Ingress: /api/ → api, / → ui, TLS via cert-manager
+├── minio/
+│   ├── statefulset.yaml             ← StatefulSet: minio (volumeClaimTemplates)
+│   ├── service.yaml                 ← Service: minio (ClusterIP, port 9000)
+│   └── init-job.yaml                ← Job: minio-init-bucket (mc mb --ignore-existing)
+└── vault/
+    ├── vault-auth.yaml              ← VaultAuth: kubernetes method, reactbin SA
+    ├── api-secret.yaml              ← VaultStaticSecret → K8s Secret: api-env
+    └── minio-secret.yaml            ← VaultStaticSecret → K8s Secret: minio-credentials
+
+api/Dockerfile.prod                  ← MODIFIED: add alembic/ and alembic.ini to runtime stage
+Makefile                             ← MODIFIED: add dry-run validation target
+```
+
+## Implementation Design
+
+### `api/Dockerfile.prod` — runtime stage addition
+
+```dockerfile
+# In the runtime stage, after copying app/:
+COPY --chown=appuser:appgroup alembic/ ./alembic/
+COPY --chown=appuser:appgroup alembic.ini .
+```
+
+No builder-stage change. No new base image. The init container uses the same image and `workingDir: /app`.
+
+### `k8s/namespace.yaml`
+
+```yaml
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: reactbin
+```
+
+### `k8s/vault/vault-auth.yaml`
+
+```yaml
+apiVersion: secrets.hashicorp.com/v1beta1
+kind: VaultAuth
+metadata:
+  name: reactbin-auth
+  namespace: reactbin
+spec:
+  method: kubernetes
+  mount: kubernetes
+  kubernetes:
+    role: reactbin
+    serviceAccount: default
+    audiences:
+      - https://kubernetes.default.svc
+```
+
+Note: `VaultConnection` is not included in the `k8s/` tree — it lives in the VSO operator's namespace and is operator-managed infrastructure, not application manifests.
+
+### `k8s/vault/api-secret.yaml`
+
+```yaml
+apiVersion: secrets.hashicorp.com/v1beta1
+kind: VaultStaticSecret
+metadata:
+  name: api-secret
+  namespace: reactbin
+spec:
+  vaultAuthRef: reactbin-auth
+  mount: secret
+  type: kv-v2
+  path: reactbin/api/config
+  refreshAfter: 1h
+  destination:
+    name: api-env
+    create: true
+```
+
+The API Deployment then uses `envFrom: [{secretRef: {name: api-env}}]`.
+
+### `k8s/vault/minio-secret.yaml`
+
+Same pattern, path `reactbin/minio/credentials`, destination `minio-credentials`.
+
+### `k8s/api/deployment.yaml` — init container
+
+```yaml
+initContainers:
+  - name: alembic-migrate
+    image: reactbin-api:latest          # same tag as main container
+    command: ["alembic", "upgrade", "head"]
+    workingDir: /app
+    envFrom:
+      - secretRef:
+          name: api-env
+containers:
+  - name: api
+    image: reactbin-api:latest
+    ports:
+      - containerPort: 8000
+    envFrom:
+      - secretRef:
+          name: api-env
+    env:
+      - name: API_DOCS_ENABLED
+          value: "false"
+    livenessProbe:
+      httpGet: {path: /api/v1/health, port: 8000}
+      initialDelaySeconds: 10
+      periodSeconds: 30
+    readinessProbe:
+      httpGet: {path: /api/v1/health, port: 8000}
+      initialDelaySeconds: 5
+      periodSeconds: 10
+    securityContext:
+      runAsNonRoot: true
+      runAsUser: 1001
+```
+
+### `k8s/ingress.yaml`
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: reactbin
+  namespace: reactbin
+  annotations:
+    cert-manager.io/cluster-issuer: letsencrypt-prod
+    nginx.ingress.kubernetes.io/ssl-redirect: "true"
+spec:
+  ingressClassName: nginx
+  tls:
+    - hosts: [<your-domain>]
+      secretName: reactbin-tls
+  rules:
+    - host: <your-domain>
+      http:
+        paths:
+          - path: /api/
+            pathType: Prefix
+            backend:
+              service: {name: api, port: {number: 8000}}
+          - path: /
+            pathType: Prefix
+            backend:
+              service: {name: ui, port: {number: 8080}}
+```
+
+`/api/` must be listed before `/`.
+
+### `k8s/minio/statefulset.yaml` — StatefulSet (not Deployment)
+
+StatefulSet gives stable pod name `minio-0` and automatic PVC reattachment via `volumeClaimTemplates`. ReadWriteOnce, default storage class.
+
+Health probes: `GET /minio/health/live:9000` (liveness), `GET /minio/health/ready:9000` (readiness).
+
+### `k8s/minio/init-job.yaml`
+
+```yaml
+command: ["sh", "-c", "mc alias set local http://minio:9000 $MINIO_ROOT_USER $MINIO_ROOT_PASSWORD && mc mb --ignore-existing local/reactbin"]
+```
+
+`restartPolicy: OnFailure`. `--ignore-existing` makes the job idempotent.
+
+### Makefile addition
+
+```makefile
+validate-k8s:
+    yamllint k8s/
+    kubectl apply --dry-run=client -f k8s/
+```
+
+## Dependencies & Risks
+
+| Item | Risk | Mitigation |
+|------|------|------------|
+| `VaultConnection` not in `k8s/` | Operator may not have it pre-created | Documented as prerequisite in contracts/operator-deploy.md |
+| `letsencrypt-prod` ClusterIssuer name | May differ in operator's cluster | Documented as prerequisite; easy to sed-replace |
+| Image tag placeholder `latest` | Operator forgets to substitute | `validate-k8s` dry-run will succeed but notes in quickstart.md and task descriptions warn explicitly |
+| MinIO PVC storage class | Default may be unsuitable (e.g., ephemeral) | Noted in Assumptions; operator can patch `storageClassName` |
+| `<your-domain>` placeholder in Ingress | `kubectl apply --dry-run=client` validates everything except host value | Noted in quickstart; hostname must be substituted before applying |

specs/013-k8s-manifests/quickstart.md

@@ -0,0 +1,92 @@
+# Quickstart: Kubernetes Production Deployment
+
+## Before You Apply
+
+1. Store API secrets in Vault at `reactbin/api/config` (KV v2):
+   ```
+   DATABASE_URL          = postgresql+asyncpg://reactbin:<pw>@<host>:5432/reactbin
+   JWT_SECRET_KEY        = <long-random-string>
+   OWNER_USERNAME        = <your-username>
+   OWNER_PASSWORD        = <your-password>
+   S3_ENDPOINT_URL       = http://minio.reactbin.svc.cluster.local:9000
+   S3_BUCKET_NAME        = reactbin
+   S3_ACCESS_KEY_ID      = <same as MINIO_ROOT_USER>
+   S3_SECRET_ACCESS_KEY  = <same as MINIO_ROOT_PASSWORD>
+   API_BASE_URL          = https://<your-domain>
+   API_DOCS_ENABLED      = false
+   ```
+
+2. Store MinIO credentials in Vault at `reactbin/minio/credentials` (KV v2):
+   ```
+   MINIO_ROOT_USER     = <choose a strong username>
+   MINIO_ROOT_PASSWORD = <choose a strong password>
+   ```
+
+3. Create a Vault Kubernetes auth role bound to the `default` service account in the `reactbin` namespace with read access to both paths above.
+
+4. Confirm DNS resolves to the cluster ingress IP and the `letsencrypt-prod` ClusterIssuer exists.
+
+## Deploy
+
+```bash
+# Substitute the real image tags
+sed -i 's|reactbin-api:latest|reactbin-api:v1.0.0|g' k8s/api/deployment.yaml
+sed -i 's|reactbin-ui:latest|reactbin-ui:v1.0.0|g' k8s/ui/deployment.yaml
+
+# Apply everything
+kubectl apply -f k8s/
+```
+
+## Verify
+
+```bash
+# Watch pods come up (init container runs first on the API pod)
+kubectl get pods -n reactbin -w
+
+# API health
+curl -sf https://<your-domain>/api/v1/health && echo "API OK"
+
+# UI reachable
+curl -sf -o /dev/null -w "%{http_code}\n" https://<your-domain>/
+
+# Docs correctly gated
+curl -o /dev/null -w "%{http_code}\n" https://<your-domain>/docs    # → 404
+curl -o /dev/null -w "%{http_code}\n" https://<your-domain>/redoc   # → 404
+
+# Check migration init container ran
+kubectl logs -n reactbin -l app=api -c alembic-migrate
+```
+
+## Scenario: Migration fails on deploy
+
+```bash
+# Pod will be stuck in Init state
+kubectl get pods -n reactbin
+# NAME          READY   STATUS                  RESTARTS
+# api-xxx-yyy   0/1     Init:CrashLoopBackOff   2
+
+# See why
+kubectl logs -n reactbin <pod-name> -c alembic-migrate
+
+# Fix the issue (e.g. correct DATABASE_URL in Vault, wait for VSO to resync)
+# Then delete the pod to force a fresh rollout
+kubectl rollout restart deployment/api -n reactbin
+```
+
+## Scenario: Update to a new image version
+
+```bash
+kubectl set image deployment/api api=reactbin-api:v1.1.0 -n reactbin
+kubectl set image deployment/ui ui=reactbin-ui:v1.1.0 -n reactbin
+# Kubernetes rolls out new pods; init container runs migrations before traffic switches
+```
+
+## Scenario: Restore after MinIO pod restart
+
+MinIO uses a PersistentVolumeClaim. Pod restarts do not affect stored data. Verify:
+
+```bash
+kubectl delete pod -n reactbin minio-0
+kubectl get pods -n reactbin -w   # minio-0 restarts, PVC reattaches
+# Previously uploaded images should still be accessible via the API
+```

specs/013-k8s-manifests/research.md

@@ -0,0 +1,63 @@
+# Research: Kubernetes Production Manifests
+
+## Decision 1: VSO CRD chain (VaultConnection → VaultAuth → VaultStaticSecret)
+
+**Decision**: Use three CRDs — `VaultConnection`, `VaultAuth`, and `VaultStaticSecret` — all under `apiVersion: secrets.hashicorp.com/v1beta1`.
+**Rationale**: This is the required VSO resource chain. `VaultConnection` points to the Vault server address. `VaultAuth` declares the Kubernetes auth method (role, service account, mount path). `VaultStaticSecret` references a `VaultAuth` via `vaultAuthRef` and declares the Vault KV path and the destination K8s Secret name. VSO syncs all Vault keys to the K8s Secret 1:1 by default — no explicit key mapping needed.
+**Alternatives considered**: `VaultAuthGlobal` for cross-namespace sharing — not needed; all resources are in the same `reactbin` namespace.
+
+Key fields:
+- `VaultStaticSecret.spec.type`: `kv-v2` (standard for modern Vault)
+- `VaultStaticSecret.spec.refreshAfter`: `1h` (Go duration string)
+- `VaultStaticSecret.spec.destination.create: true` — VSO creates the K8s Secret if absent
+- `VaultAuth.spec.kubernetes.role` — a Vault role the operator must pre-create and bind to the `reactbin` namespace service account
+
+## Decision 2: MinIO as StatefulSet (not Deployment)
+
+**Decision**: Run MinIO as a `StatefulSet` with `volumeClaimTemplates`.
+**Rationale**: StatefulSet gives the pod a stable name (`minio-0`) and automatically reattaches its PVC on pod recreation. A Deployment would require a manually-created PVC and is prone to PVC binding issues on reschedule. The marginal complexity of a StatefulSet over a Deployment is acceptable. `ReadWriteOnce` PVC is correct for single-replica MinIO.
+**Alternatives considered**: Deployment with explicit PVC — works but PVC lifecycle is decoupled from the pod, creating operational risk.
+
+MinIO health probes:
+- Liveness: `GET /minio/health/live:9000`
+- Readiness: `GET /minio/health/ready:9000`
+
+MinIO env vars: `MINIO_ROOT_USER`, `MINIO_ROOT_PASSWORD` (injected from a K8s Secret synced by VSO).
+
+## Decision 3: Bucket initialisation via Kubernetes Job with `minio/mc`
+
+**Decision**: A one-off `Job` using `minio/mc:latest` runs `mc mb --ignore-existing` to create the bucket idempotently.
+**Rationale**: This is the standard in-cluster pattern. `--ignore-existing` makes the job safe to re-apply (exits 0 if bucket already exists). `restartPolicy: OnFailure` retries transient failures (e.g. MinIO not yet ready).
+**Alternatives considered**: Init container on the API pod — tightly couples bucket creation to API startup; a Job is cleaner and independently rerunnable.
+
+## Decision 4: Ingress — single resource, `/api/` path before `/`
+
+**Decision**: One `Ingress` resource with `ingressClassName: nginx`, two path entries in a single rule: `/api/` (Prefix) → API Service, `/` (Prefix) → UI Service; `/api/` must be listed first.
+**Rationale**: nginx ingress evaluates paths in declaration order; the more specific `/api/` prefix must appear before `/` or all traffic is routed to the UI. No path rewriting annotation is needed — the API already handles full `/api/v1/...` paths.
+**TLS**: cert-manager annotation `cert-manager.io/cluster-issuer: letsencrypt-prod` triggers automatic certificate provisioning into a K8s Secret named in `spec.tls[].secretName`. HTTP→HTTPS redirect is on by default when TLS is configured (`nginx.ingress.kubernetes.io/ssl-redirect: "true"` is explicit but redundant).
+**Alternatives considered**: Two separate Ingress resources (one per service) — works but harder to reason about routing order; single Ingress is canonical.
+
+## Decision 5: Alembic init container — same image, workdir `/app`
+
+**Decision**: The API Deployment includes an init container with the same image as the main container, `command: ["alembic", "upgrade", "head"]`, and `workingDir: /app`. It shares the API's env secret via `envFrom` so it can read `DATABASE_URL`.
+**Rationale**: Alembic needs `DATABASE_URL` to connect and `alembic.ini` + `alembic/` to find migrations. Both are available in the production image once `Dockerfile.prod` is updated. Using the same image guarantees the migration files match the running version.
+**Dockerfile.prod update required**: Add `COPY --chown=appuser:appgroup alembic/ ./alembic/` and `COPY --chown=appuser:appgroup alembic.ini .` in the runtime stage (not the builder stage — no compilation needed).
+**Alternatives considered**: Separate migration image — adds a second image to build and push on every release; unnecessary when the source image already has everything.
+
+## Decision 6: Image tag strategy — placeholder `latest`, substituted at deploy time
+
+**Decision**: Manifests reference image tags using `latest` as a documented placeholder. The operator substitutes the real tag with `kubectl set image` or a `sed` one-liner before applying.
+**Rationale**: Kustomize's `images` transformer is the clean alternative, but introduces a tooling dependency. For a personal single-operator deployment, `sed` or `kubectl set image` after `kubectl apply` is simpler and requires no additional setup. The placeholder is documented in the operator guide (quickstart.md).
+**Alternatives considered**: Kustomize overlays — appropriate for multi-environment setups; over-engineered for one environment.
+
+## Decision 7: Two VaultStaticSecrets (API env and MinIO credentials)
+
+**Decision**: Separate VaultStaticSecret resources for API env vars and MinIO root credentials, syncing into `api-env` and `minio-credentials` K8s Secrets respectively.
+**Rationale**: The API's env secret contains database, JWT, and S3 access credentials. MinIO's root credentials are a different concern with a different rotation lifecycle. Keeping them separate makes Vault policies simpler (least privilege) and avoids giving the API pod access to MinIO's root password.
+**Vault paths assumed**: `reactbin/api/config` (KV v2) for API env; `reactbin/minio/credentials` (KV v2) for MinIO root credentials.
+
+## Decision 8: Namespace manifest included in `k8s/`
+
+**Decision**: `k8s/namespace.yaml` creates the `reactbin` namespace as part of the manifest set.
+**Rationale**: Makes the full deployment self-contained — operator runs `kubectl apply -f k8s/` without a prerequisite namespace creation step.
+**Note**: If the namespace already exists, `kubectl apply` is idempotent.

specs/013-k8s-manifests/spec.md

@@ -0,0 +1,124 @@
+# Feature Specification: Kubernetes Production Manifests
+
+**Feature Branch**: `013-k8s-manifests`
+**Created**: 2026-05-07
+**Status**: Draft
+**Input**: User description: "Kubernetes manifests for production deployment to k3s: Deployment, Service, and Ingress for the API and UI; VaultStaticSecret CRDs to sync secrets from HashiCorp Vault; Alembic init container on the API Deployment for schema migrations. The cluster uses an nginx ingress controller with Let's Encrypt TLS, a shared external Postgres instance, MinIO running in-cluster, and VSO (Vault Secrets Operator) for secret management."
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 — Application Reachable in Production (Priority: P1)
+
+As an operator, I can apply the manifests to my k3s cluster and have both the API and UI reachable at the production domain over HTTPS, with all health checks passing.
+
+**Why this priority**: This is the core deployment goal. Nothing else matters if the application is not reachable.
+
+**Independent Test**: Apply the API and UI manifests with a manually-created K8s Secret (bypassing Vault). Confirm the UI loads at the domain root and the API health endpoint returns 200 at `/api/v1/health`. Confirm HTTPS is enforced and HTTP redirects to HTTPS.
+
+**Acceptance Scenarios**:
+
+1. **Given** the manifests are applied to the cluster, **When** a browser navigates to `https://<domain>/`, **Then** the UI loads successfully with a valid TLS certificate.
+2. **Given** the manifests are applied, **When** a request is made to `https://<domain>/api/v1/health`, **Then** a 200 response is returned.
+3. **Given** the API docs flag is disabled, **When** a request is made to `https://<domain>/docs`, **Then** a 404 is returned.
+4. **Given** the API pod is restarted, **When** it comes back up, **Then** it passes readiness checks before receiving traffic.
+5. **Given** a request for an unknown path, **When** it is made to the UI, **Then** the SPA serves the index page (client-side routing is preserved).
+
+---
+
+### User Story 2 — Secrets Sourced from Vault (Priority: P2)
+
+As an operator, no secrets are stored in version-controlled manifest files. All sensitive values are declared in Vault and synced automatically into the cluster as Kubernetes Secrets by the Vault Secrets Operator.
+
+**Why this priority**: Security prerequisite for production. Hardcoded secrets in manifests are a material risk.
+
+**Independent Test**: Run `git grep` for known secret patterns across `k8s/` and confirm zero matches. Confirm VaultStaticSecret CRDs reference a Vault path and that the synced K8s Secret is created and the API pod's environment is populated from it.
+
+**Acceptance Scenarios**:
+
+1. **Given** Vault contains the required secret values at the declared path, **When** VSO is running, **Then** a K8s Secret is created in the cluster namespace with the declared keys.
+2. **Given** the K8s Secret exists, **When** the API pod starts, **Then** its environment variables are populated from that secret.
+3. **Given** a `git grep` for plaintext credentials across `k8s/`, **When** run against the committed manifests, **Then** no plaintext secrets are found.
+
+---
+
+### User Story 3 — Schema Migrations Run Before API Starts (Priority: P3)
+
+As an operator, every time the API is deployed, database migrations run automatically in an init container before the main application container starts. A failed migration prevents the pod from starting, protecting against schema drift.
+
+**Why this priority**: Prevents the API from serving requests against a stale or incompatible schema. Safe deployment ordering is essential for production.
+
+**Independent Test**: Deploy with the init container pointing at a valid database. Confirm migrations run and the API starts. Simulate a failing migration by pointing the init container at an unreachable database and confirm the pod stays in init state and does not serve traffic.
+
+**Acceptance Scenarios**:
+
+1. **Given** the API Deployment is applied, **When** the pod starts, **Then** the init container completes `alembic upgrade head` before the main container starts.
+2. **Given** the schema is already current, **When** the pod starts, **Then** the migration init container exits successfully with no changes applied.
+3. **Given** the migration fails, **When** the pod starts, **Then** the init container exits non-zero, the main container does not start, and the pod enters a visible error state.
+
+---
+
+### User Story 4 — MinIO Runs In-Cluster with Persistent Storage (Priority: P4)
+
+As an operator, MinIO runs inside the cluster with a PersistentVolumeClaim for durable storage, is not externally reachable, and has the required bucket initialised on first deployment.
+
+**Why this priority**: Required for image storage, but decoupled from the other manifests — the S3 endpoint is just a config value the API reads.
+
+**Independent Test**: Confirm the MinIO pod is running and has no external Ingress. Confirm the required bucket exists. Restart the MinIO pod and confirm previously stored objects are still accessible.
+
+**Acceptance Scenarios**:
+
+1. **Given** the MinIO manifests are applied, **When** the MinIO pod starts, **Then** the required bucket is created and the API can store and retrieve images.
+2. **Given** the MinIO pod is restarted, **When** it comes back up, **Then** all previously stored objects remain accessible (PVC-backed storage persists).
+3. **Given** no Ingress is defined for MinIO, **When** a connection is attempted from outside the cluster, **Then** MinIO is not reachable.
+
+---
+
+### Edge Cases
+
+- What if Vault is unavailable when VSO tries to sync? VSO retries on a configurable interval; the pod will not start until the K8s Secret exists.
+- What if the database is unreachable during migration? The init container exits non-zero; the pod does not start and Kubernetes retries with backoff.
+- What if the MinIO PVC runs out of space? MinIO will fail writes; the API will return upload errors. Capacity monitoring is out of scope for this feature.
+- What if migrations and the main container use different image tags? They use the same tag in the same Deployment spec, so they are always in sync.
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: All manifests MUST target a single configurable namespace (default: `reactbin`).
+- **FR-002**: The API MUST be deployed as a Deployment with liveness and readiness probes on `/api/v1/health`.
+- **FR-003**: The API Deployment MUST include an init container using the same image that runs database schema migrations before the main container starts.
+- **FR-004**: The API Deployment MUST set `API_DOCS_ENABLED=false`.
+- **FR-005**: The UI MUST be deployed as a Deployment with a liveness probe confirming the nginx process is serving.
+- **FR-006**: A single Ingress MUST route `https://<domain>/api/` to the API Service and all other paths to the UI Service, with TLS termination via a cert-manager Let's Encrypt certificate.
+- **FR-007**: HTTP requests MUST be redirected to HTTPS via the Ingress.
+- **FR-008**: All API secrets MUST be declared in a VaultStaticSecret CRD and synced into a K8s Secret; no secret value MUST appear as plaintext in any manifest file.
+- **FR-009**: The API Deployment MUST source all environment variables from the synced K8s Secret via `envFrom`.
+- **FR-010**: MinIO MUST be deployed as a StatefulSet with a PersistentVolumeClaim using the cluster's default storage class.
+- **FR-011**: A Kubernetes Job MUST create the required S3 bucket in MinIO on first deployment and MUST be idempotent on re-apply.
+- **FR-012**: MinIO MUST have no Ingress; it MUST only be accessible within the cluster via ClusterIP.
+- **FR-013**: All containers MUST run as non-root users.
+- **FR-014**: The API production image MUST include migration files so the init container can run migrations without a separate image.
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: The application is accessible at the production domain within 120 seconds of `kubectl apply`.
+- **SC-002**: Schema migrations complete and the API begins serving traffic without manual operator intervention on every deployment.
+- **SC-003**: A `git grep` across `k8s/` finds zero plaintext secret values in committed files.
+- **SC-004**: A simulated migration failure holds the pod in init state and the application never serves traffic.
+- **SC-005**: Restarting the MinIO pod does not result in data loss — previously uploaded images remain accessible.
+
+## Assumptions
+
+- The k3s cluster is running with the nginx ingress controller installed.
+- cert-manager is installed and a `ClusterIssuer` named `letsencrypt-prod` is already configured.
+- The Vault Secrets Operator is installed in the cluster.
+- A HashiCorp Vault instance is accessible from the cluster and the required secret values are stored at the declared Vault path before deployment.
+- A shared external PostgreSQL instance is available; the operator creates a dedicated database and user before deploying.
+- DNS for the production domain is already pointing at the cluster ingress IP.
+- Manifests are stored in a `k8s/` directory at the repository root.
+- The cluster's default storage class supports ReadWriteOnce (sufficient for single-replica MinIO).
+- All Deployments run a single replica (personal tool, no HA requirement).
+- Image tags are managed externally; manifests use a placeholder tag that the operator substitutes at deploy time.
+- The `API_DOCS_ENABLED` flag exists on the API (implemented in feature 012).

specs/013-k8s-manifests/tasks.md

@@ -0,0 +1,174 @@
+# Tasks: Kubernetes Production Manifests
+
+**Input**: Design documents from `specs/013-k8s-manifests/`
+**Prerequisites**: plan.md ✅, spec.md ✅, research.md ✅, contracts/operator-deploy.md ✅, quickstart.md ✅
+
+**Tests**: K8s manifests have no unit test framework. Validation is via `yamllint` (format) and `kubectl apply --dry-run=client` (schema). Each phase ends with a validation step. The TDD analogue is: write the validate-k8s Makefile target (Phase 1) before any manifest exists, so it immediately fails — then manifests are written to make it pass.
+
+**Organization**: Phase 1 creates the directory structure and validation target. Phase 2 creates the namespace and Vault CRDs (foundational — required by all user story deployments). Phases 3–6 implement user stories. Phase 7 polishes.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel with other [P] tasks in the same phase
+- **[Story]**: Which user story this task belongs to
+- Exact file paths included in every task description
+
+---
+
+## Phase 1: Setup
+
+**Goal**: Create the `k8s/` directory structure and the validation Makefile target before any manifests exist.
+
+- [X] T001 Create the `k8s/` directory tree: `mkdir -p k8s/api k8s/ui k8s/minio k8s/vault` from the repository root; confirm the four subdirectories exist
+
+- [X] T002 Add a `validate-k8s` target to `Makefile` immediately after the existing `verify-ui-prod` target: the target MUST run `yamllint -d relaxed k8s/` then `kubectl apply --dry-run=client -f k8s/`; add `validate-k8s` to the `.PHONY` line; note in a comment that `kubectl apply --dry-run=client` requires a kubeconfig with cluster access — offline validation uses `yamllint` only
+
+---
+
+## Phase 2: Foundational (Namespace + Vault CRDs)
+
+**Goal**: Namespace and Vault secret-sync resources that every other manifest depends on.
+
+**⚠️ CRITICAL**: No user story manifest can be applied until this phase is complete — the namespace must exist before any namespaced resource, and the Vault CRDs must exist before the API or MinIO pods can start.
+
+- [X] T003 Create `k8s/namespace.yaml`: a single `Namespace` resource with `name: reactbin` and no additional labels
+
+- [X] T004 [P] Create `k8s/vault/vault-auth.yaml`: a `VaultAuth` resource (`apiVersion: secrets.hashicorp.com/v1beta1`) with `name: reactbin-auth`, `namespace: reactbin`, `spec.method: kubernetes`, `spec.mount: kubernetes`, `spec.kubernetes.role: reactbin`, `spec.kubernetes.serviceAccount: default`, `spec.kubernetes.audiences: [https://kubernetes.default.svc]`; add a comment noting the operator must create the Vault role and bind it to the `default` SA in the `reactbin` namespace with read access to both secret paths
+
+- [X] T005 [P] Create `k8s/vault/api-secret.yaml`: a `VaultStaticSecret` resource with `name: api-secret`, `namespace: reactbin`, `spec.vaultAuthRef: reactbin-auth`, `spec.mount: secret`, `spec.type: kv-v2`, `spec.path: reactbin/api/config`, `spec.refreshAfter: 1h`, `spec.destination.name: api-env`, `spec.destination.create: true`; add a comment listing all required Vault keys: `DATABASE_URL`, `JWT_SECRET_KEY`, `OWNER_USERNAME`, `OWNER_PASSWORD`, `S3_ENDPOINT_URL`, `S3_BUCKET_NAME`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `API_BASE_URL`
+
+- [X] T006 [P] Create `k8s/vault/minio-secret.yaml`: same structure as T005 but `name: minio-secret`, `spec.path: reactbin/minio/credentials`, `spec.destination.name: minio-credentials`; comment listing required Vault keys: `MINIO_ROOT_USER`, `MINIO_ROOT_PASSWORD`
+
+**Checkpoint**: Foundational resources complete. User story implementation can now begin.
+
+---
+
+## Phase 3: User Story 1 — Application Reachable in Production (Priority: P1) 🎯 MVP
+
+**Goal**: API and UI are deployed and reachable at the production domain via HTTPS with TLS from cert-manager.
+
+**Independent Test**: Apply all Phase 2 + Phase 3 manifests. Confirm `kubectl get pods -n reactbin` shows api and ui pods Running. Confirm `curl https://<domain>/api/v1/health` returns 200 and `curl https://<domain>/` returns 200.
+
+- [X] T007 [P] [US1] Create `k8s/api/service.yaml`: `Service`, `name: api`, `namespace: reactbin`, `type: ClusterIP`, `selector: {app: api}`, `ports: [{port: 8000, targetPort: 8000, name: http}]`
+
+- [X] T008 [P] [US1] Create `k8s/ui/service.yaml`: `Service`, `name: ui`, `namespace: reactbin`, `type: ClusterIP`, `selector: {app: ui}`, `ports: [{port: 8080, targetPort: 8080, name: http}]`
+
+- [X] T009 [P] [US1] Create `k8s/ui/deployment.yaml`: `Deployment`, `name: ui`, `namespace: reactbin`, 1 replica, `selector.matchLabels: {app: ui}`; container `name: ui`, `image: reactbin-ui:latest` (placeholder — operator substitutes real tag), `ports: [{containerPort: 8080}]`; `livenessProbe: {httpGet: {path: /, port: 8080}, initialDelaySeconds: 10, periodSeconds: 30}`; `securityContext: {runAsNonRoot: true, runAsUser: 101}` (UID 101 is the nginxinc/nginx-unprivileged user); add comment: `# Replace 'latest' with the real image tag before applying`
+
+- [X] T010 [US1] Create `k8s/api/deployment.yaml`: `Deployment`, `name: api`, `namespace: reactbin`, 1 replica, `selector.matchLabels: {app: api}`; container `name: api`, `image: reactbin-api:latest` (placeholder), `ports: [{containerPort: 8000}]`; `envFrom: [{secretRef: {name: api-env}}]`; `env: [{name: API_DOCS_ENABLED, value: "false"}]`; `livenessProbe: {httpGet: {path: /api/v1/health, port: 8000}, initialDelaySeconds: 10, periodSeconds: 30}`; `readinessProbe: {httpGet: {path: /api/v1/health, port: 8000}, initialDelaySeconds: 5, periodSeconds: 10}`; `securityContext: {runAsNonRoot: true, runAsUser: 1001}`; add comment: `# initContainers block added in US3 (T015)`; add comment: `# Replace 'latest' with the real image tag before applying`
+
+- [X] T011 [US1] Create `k8s/ingress.yaml`: `Ingress`, `name: reactbin`, `namespace: reactbin`; `annotations: {"cert-manager.io/cluster-issuer": "letsencrypt-prod", "nginx.ingress.kubernetes.io/ssl-redirect": "true"}`; `spec.ingressClassName: nginx`; `spec.tls: [{hosts: ["<your-domain>"], secretName: reactbin-tls}]`; `spec.rules: [{host: "<your-domain>", http: {paths: [{path: /api/, pathType: Prefix, backend: {service: {name: api, port: {number: 8000}}}}, {path: /, pathType: Prefix, backend: {service: {name: ui, port: {number: 8080}}}}]}}]`; IMPORTANT — `/api/` path entry MUST appear before `/` in the YAML (nginx evaluates in declaration order); add comment: `# Replace <your-domain> with the real domain before applying`
+
+- [X] T012 [US1] Verify US1: run `yamllint -d relaxed k8s/` from the repository root and confirm no errors; run `kubectl apply --dry-run=client -f k8s/` (requires cluster kubeconfig) and confirm all resources in namespace.yaml, vault/, api/, ui/, and ingress.yaml are accepted; if no cluster is available, yamllint passing is sufficient for this checkpoint
+
+**Checkpoint**: US1 complete. API and UI manifests are schema-valid and ready to apply.
+
+---
+
+## Phase 4: User Story 2 — Secrets Sourced from Vault (Priority: P2)
+
+**Goal**: Confirm that no plaintext secret values appear in any committed manifest file. The implementation (VaultAuth + VaultStaticSecret × 2) was completed in Phase 2.
+
+**Independent Test**: `git grep` across `k8s/` finds no plaintext credential values.
+
+- [X] T013 [US2] Verify US2: run `git grep -rn "password\|secret_key\|access_key\|DATABASE_URL" k8s/` and confirm that only key names (in comments) and Vault path references appear — no actual values; also confirm that `k8s/vault/api-secret.yaml` and `k8s/vault/minio-secret.yaml` reference Vault paths under `spec.path` and that `spec.destination.create: true` is set so VSO creates the K8s Secrets
+
+**Checkpoint**: US2 complete. Zero plaintext secrets in manifests; all secrets flow through Vault.
+
+---
+
+## Phase 5: User Story 3 — Schema Migrations Run Before API Starts (Priority: P3)
+
+**Goal**: The API Deployment includes an Alembic init container. `api/Dockerfile.prod` is updated to include migration files.
+
+**Independent Test**: `docker build -f api/Dockerfile.prod api/ -t reactbin-api-prod:test` succeeds and `docker run --rm reactbin-api-prod:test ls /app/alembic` shows migration files. `make validate-k8s` confirms the init container spec is accepted by the Kubernetes schema.
+
+- [X] T014 [US3] Update `api/Dockerfile.prod`: in the **runtime stage** (the `FROM python:3.12-slim` stage), after the line `COPY --chown=appuser:appgroup app/ ./app/`, add two new lines: `COPY --chown=appuser:appgroup alembic/ ./alembic/` and `COPY --chown=appuser:appgroup alembic.ini .`; the builder stage is unchanged; verify with `docker build -f api/Dockerfile.prod api/ -t reactbin-api-prod:test && docker run --rm reactbin-api-prod:test ls /app/alembic /app/alembic.ini`
+
+- [X] T015 [US3] Update `k8s/api/deployment.yaml`: add an `initContainers` block to the pod spec (before the `containers` block) containing one init container: `name: alembic-migrate`, `image: reactbin-api:latest` (same placeholder tag as the main container), `command: ["alembic", "upgrade", "head"]`, `workingDir: /app`, `envFrom: [{secretRef: {name: api-env}}]`, `securityContext: {runAsNonRoot: true, runAsUser: 1001}`; remove the `# initContainers block added in US3 (T015)` comment added in T010
+
+- [X] T016 [US3] Verify US3: run `make validate-k8s` (or `yamllint -d relaxed k8s/`) and confirm the updated deployment.yaml with the init container passes validation; run `docker build -f api/Dockerfile.prod api/ -t reactbin-api-prod:test` and confirm it succeeds; run `docker run --rm reactbin-api-prod:test ls /app/alembic.ini` and confirm the file is present
+
+**Checkpoint**: US3 complete. API Deployment includes Alembic init container; production image includes migration files.
+
+---
+
+## Phase 6: User Story 4 — MinIO In-Cluster with Persistent Storage (Priority: P4)
+
+**Goal**: MinIO runs as a StatefulSet with a PVC, is accessible only within the cluster, and has the required bucket created by a Job.
+
+**Independent Test**: `make validate-k8s` confirms all MinIO manifests pass schema validation. On a live cluster: MinIO pod reaches Running state, bucket exists, no external Ingress for MinIO.
+
+- [X] T017 [P] [US4] Create `k8s/minio/service.yaml`: `Service`, `name: minio`, `namespace: reactbin`, `type: ClusterIP`, `selector: {app: minio}`, `ports: [{port: 9000, targetPort: 9000, name: s3}]`; add comment: `# No Ingress for MinIO — internal access only (FR-012)`
+
+- [X] T018 [US4] Create `k8s/minio/statefulset.yaml`: `StatefulSet` (NOT Deployment — StatefulSet ensures stable PVC binding on pod recreation), `name: minio`, `namespace: reactbin`, `replicas: 1`, `selector.matchLabels: {app: minio}`, `serviceName: minio`; pod `securityContext: {runAsUser: 1000, runAsGroup: 1000, fsGroup: 1000}`; container `name: minio`, `image: minio/minio:latest`, `args: ["server", "/data", "--console-address", ":9001"]`, `ports: [{containerPort: 9000, name: s3}]`; `env: [{name: MINIO_ROOT_USER, valueFrom: {secretKeyRef: {name: minio-credentials, key: MINIO_ROOT_USER}}}, {name: MINIO_ROOT_PASSWORD, valueFrom: {secretKeyRef: {name: minio-credentials, key: MINIO_ROOT_PASSWORD}}}]`; `livenessProbe: {httpGet: {path: /minio/health/live, port: 9000}, initialDelaySeconds: 30, periodSeconds: 20}`; `readinessProbe: {httpGet: {path: /minio/health/ready, port: 9000}, initialDelaySeconds: 15, periodSeconds: 10}`; `volumeMounts: [{name: minio-data, mountPath: /data}]`; `volumeClaimTemplates: [{metadata: {name: minio-data}, spec: {accessModes: [ReadWriteOnce], resources: {requests: {storage: 10Gi}}}}]`; add comment: `# storageClassName omitted — uses cluster default; override if needed`
+
+- [X] T019 [US4] Create `k8s/minio/init-job.yaml`: `Job`, `name: minio-init-bucket`, `namespace: reactbin`; `spec.template.spec.restartPolicy: OnFailure`; container `name: mc`, `image: minio/mc:latest`, `command: ["sh", "-c"]`, `args: ["mc alias set local http://minio.reactbin.svc.cluster.local:9000 $MINIO_ROOT_USER $MINIO_ROOT_PASSWORD && mc mb --ignore-existing local/reactbin"]`; `env: [{name: MINIO_ROOT_USER, valueFrom: {secretKeyRef: {name: minio-credentials, key: MINIO_ROOT_USER}}}, {name: MINIO_ROOT_PASSWORD, valueFrom: {secretKeyRef: {name: minio-credentials, key: MINIO_ROOT_PASSWORD}}}]`; `securityContext: {runAsNonRoot: false}` with comment `# minio/mc runs as root by default; FR-013 exception for this one-off init Job`; add comment: `# --ignore-existing makes this Job idempotent — safe to re-apply`
+
+- [X] T020 [US4] Verify US4: run `make validate-k8s` (or `yamllint -d relaxed k8s/`) and confirm all three MinIO manifests (statefulset.yaml, service.yaml, init-job.yaml) pass validation; confirm no Ingress resource references MinIO
+
+**Checkpoint**: All four user stories complete.
+
+---
+
+## Phase 7: Polish & Cross-Cutting Concerns
+
+- [X] T021 [P] Run `yamllint -d relaxed k8s/` from the repository root and fix any YAML formatting violations across all 12 manifest files; confirm output shows no errors
+
+- [X] T022 [P] Add `.yamllint.yml` at the repository root (if not already present) with `extends: relaxed` and `rules: {line-length: {max: 120}}` to keep line length reasonable for verbose K8s YAML
+
+- [X] T023 Run `make build-prod` to confirm `api/Dockerfile.prod` still builds cleanly after the T014 addition; run `docker run --rm reactbin-api-prod:latest ls /app/alembic.ini /app/alembic/` and confirm both are present in the production image
+
+---
+
+## Dependencies & Execution Order
+
+- T001 and T002 can run in parallel (directory creation vs Makefile edit)
+- T003, T004, T005, T006 can run in parallel after T001 (different files, same phase)
+- T007, T008, T009 can run in parallel after Phase 2 completes
+- T010 after T007 (deployment references service name, easier to write with service done) — but they're different files so technically parallel; keep sequential for clarity
+- T011 after T007 and T008 (Ingress references both service names)
+- T012 after T007–T011
+- T013 after Phase 2 (Vault CRDs exist to inspect)
+- T014 and T015 can run in parallel (different files: Dockerfile.prod vs deployment.yaml)
+- T016 after T014 and T015
+- T017, T018, T019 can run in parallel after Phase 2 completes
+- T020 after T017–T019
+- T021, T022, T023 can run in parallel
+
+### Execution Order Summary
+
+```
+Step 1: T001 ∥ T002                          (setup)
+Step 2: T003 ∥ T004 ∥ T005 ∥ T006           (foundational: namespace + Vault CRDs)
+Step 3: T007 ∥ T008 ∥ T009                  (US1: services + UI deployment)
+Step 4: T010                                  (US1: API deployment)
+Step 5: T011                                  (US1: Ingress)
+Step 6: T012                                  (US1: validate)
+Step 7: T013                                  (US2: verify no plaintext secrets)
+Step 8: T014 ∥ T015                          (US3: Dockerfile.prod + init container)
+Step 9: T016                                  (US3: verify)
+Step 10: T017 ∥ T018 ∥ T019                 (US4: MinIO manifests)
+Step 11: T020                                 (US4: validate MinIO)
+Step 12: T021 ∥ T022 ∥ T023                 (polish)
+```
+
+---
+
+## Implementation Strategy
+
+### MVP (US1 + US2 — application is reachable with Vault-backed secrets)
+
+1. Phase 1 (Setup) + Phase 2 (Foundational)
+2. Phase 3 (US1 — API, UI, Ingress)
+3. Phase 4 (US2 — verify no plaintext secrets)
+4. **STOP and VALIDATE**: apply to cluster, confirm `https://<domain>/` and `/api/v1/health` return 200
+5. Deploy MVP
+
+### Incremental Delivery
+
+1. Setup + Foundational → Apply → namespace and Vault sync ready
+2. Add US1 (API + UI + Ingress) → Deploy → application reachable at domain
+3. Add US3 (Alembic init container) → Deploy → migrations run automatically on rollout
+4. Add US4 (MinIO) → Deploy → persistent image storage in-cluster
+5. Polish → clean YAML, confirmed builds

specs/014-r2-cdn-serving/checklists/requirements.md

@@ -0,0 +1,34 @@
+# Specification Quality Checklist: CDN Image Serving
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-05-08
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [X] No implementation details (languages, frameworks, APIs)
+- [X] Focused on user value and business needs
+- [X] Written for non-technical stakeholders
+- [X] All mandatory sections completed
+
+## Requirement Completeness
+
+- [X] No [NEEDS CLARIFICATION] markers remain
+- [X] Requirements are testable and unambiguous
+- [X] Success criteria are measurable
+- [X] Success criteria are technology-agnostic (no implementation details)
+- [X] All acceptance scenarios are defined
+- [X] Edge cases are identified
+- [X] Scope is clearly bounded
+- [X] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [X] All functional requirements have clear acceptance criteria
+- [X] User scenarios cover primary flows
+- [X] Feature meets measurable outcomes defined in Success Criteria
+- [X] No implementation details leak into specification
+
+## Notes
+
+- All items pass. Ready for `/speckit-plan`.

specs/014-r2-cdn-serving/contracts/image-response.md

@@ -0,0 +1,54 @@
+# Contract: Image Metadata Response
+
+**Version**: 2.0 (adds `file_url`, `thumbnail_url`)
+**Endpoints affected**: `GET /api/v1/images`, `GET /api/v1/images/{id}`, `POST /api/v1/images`, `PATCH /api/v1/images/{id}/tags`
+
+## Response Schema
+
+```json
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+  "filename": "reaction.gif",
+  "mime_type": "image/gif",
+  "size_bytes": 204800,
+  "width": 480,
+  "height": 270,
+  "storage_key": "e3b0c44298fc1c149afbf4c8996fb924",
+  "thumbnail_key": "e3b0c44298fc1c149afbf4c8996fb924.thumb",
+  "file_url": "https://cdn.reactbin.juggalol.com/e3b0c44298fc1c149afbf4c8996fb924",
+  "thumbnail_url": "https://cdn.reactbin.juggalol.com/e3b0c44298fc1c149afbf4c8996fb924.thumb",
+  "created_at": "2026-05-08T12:00:00.000000",
+  "tags": ["funny", "reaction"]
+}
+```
+
+## Field Descriptions
+
+| Field | Type | Nullable | Notes |
+|-------|------|----------|-------|
+| `id` | string (UUID) | No | Stable image identifier |
+| `hash` | string (hex) | No | SHA-256 of file content; deduplication key |
+| `filename` | string | No | Original upload filename |
+| `mime_type` | string | No | One of: `image/jpeg`, `image/png`, `image/gif`, `image/webp` |
+| `size_bytes` | integer | No | File size in bytes |
+| `width` | integer | No | Image width in pixels |
+| `height` | integer | No | Image height in pixels |
+| `storage_key` | string | No | Object storage key (retained for backward compat) |
+| `thumbnail_key` | string | Yes | Thumbnail object storage key; null if generation failed |
+| `file_url` | string | No | Full URL to fetch the image file — CDN URL in production, API proxy path in local dev |
+| `thumbnail_url` | string | Yes | Full URL to fetch the thumbnail — CDN URL in production, API proxy path in local dev; null if no thumbnail |
+| `created_at` | string (ISO 8601) | No | Upload timestamp |
+| `tags` | string[] | No | Lowercase normalised tag list |
+| `duplicate` | boolean | Yes | Present only on upload responses; true if hash matched an existing image |
+
+## URL Behaviour
+
+| Configuration | `file_url` example | `thumbnail_url` example |
+|---------------|--------------------|------------------------|
+| `S3_PUBLIC_BASE_URL` set | `https://cdn.reactbin.juggalol.com/{storage_key}` | `https://cdn.reactbin.juggalol.com/{thumbnail_key}` |
+| `S3_PUBLIC_BASE_URL` not set | `/api/v1/images/{id}/file` | `/api/v1/images/{id}/thumbnail` |
+
+## UI Contract
+
+The UI MUST use `file_url` and `thumbnail_url` from the response to render images. The UI MUST NOT construct image URLs from `id`, `storage_key`, or `thumbnail_key` directly. The UI MUST treat `thumbnail_url: null` as "no thumbnail available" and fall back to `file_url` for display.

specs/014-r2-cdn-serving/plan.md

@@ -0,0 +1,137 @@
+# Implementation Plan: CDN Image Serving
+
+**Branch**: `014-r2-cdn-serving` | **Date**: 2026-05-08 | **Spec**: [spec.md](spec.md)
+**Input**: Feature specification from `specs/014-r2-cdn-serving/spec.md`
+
+## Summary
+
+Extend the image metadata API response to include `file_url` and `thumbnail_url` fields. When `S3_PUBLIC_BASE_URL` is configured, these fields contain CDN URLs pointing directly to Cloudflare R2. When unconfigured, they fall back to the existing API proxy paths so local development requires no setup changes. The UI is updated to use these response fields instead of constructing proxy URLs client-side. Proxy endpoints are retained unchanged.
+
+## Technical Context
+
+**Language/Version**: Python 3.12 (API), TypeScript strict mode (UI)
+**Primary Dependencies**: FastAPI, SQLAlchemy 2.x async, Angular (latest stable), pydantic-settings
+**Storage**: PostgreSQL (image metadata), S3-compatible object storage (R2 in production, MinIO in dev)
+**Testing**: pytest (unit + integration), Angular component tests
+**Target Platform**: Linux (k3s), local Docker Compose
+**Project Type**: Web service (API) + SPA (UI)
+**Performance Goals**: No additional latency on API responses; image load latency reduced by eliminating API proxy hop in production
+**Constraints**: No breaking changes to existing API response fields; proxy endpoints must remain functional
+**Scale/Scope**: Single-owner app; ~100 existing images migrated to R2 prior to this feature
+
+## Constitution Check
+
+| Principle | Status | Notes |
+|-----------|--------|-------|
+| §2.1 Strict separation of concerns | PASS | URL construction stays in router layer; storage backend unchanged |
+| §2.3 Storage abstraction | PASS | No changes to `StorageBackend` interface or `S3StorageBackend` |
+| §2.6 No speculative abstraction | PASS | No new interfaces introduced; URL logic is a simple helper |
+| §3.1 API versioning (`/api/v1/`) | PASS | Adding fields to response is non-breaking per §3.1 |
+| §3.2 OpenAPI as contract | PASS | New fields documented in contracts/image-response.md |
+| §5.1 Tests alongside implementation | REQUIRED | Unit tests for URL construction; integration tests for response fields |
+| §7.2 Environment configuration | PASS | `S3_PUBLIC_BASE_URL` via env var; no hardcoded URLs |
+
+No constitution violations. All gates pass.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/014-r2-cdn-serving/
+├── plan.md                     # This file
+├── research.md                 # Technical decisions
+├── contracts/
+│   └── image-response.md       # Updated image response schema
+├── quickstart.md               # Integration test scenarios
+└── tasks.md                    # Phase 2 output (speckit-tasks)
+```
+
+### Source Code Changes
+
+```text
+api/
+├── app/
+│   ├── config.py               # Add: s3_public_base_url: str | None = None
+│   └── routers/
+│       └── images.py           # Update: _image_to_dict gains cdn_base param;
+│                               #         add file_url + thumbnail_url to response;
+│                               #         pass cdn_base from get_settings() at endpoint level
+├── tests/
+│   ├── unit/
+│   │   └── test_url_construction.py   # New: pure unit tests for URL logic
+│   └── integration/
+│       └── test_images.py      # Update: assert file_url + thumbnail_url present in responses
+
+ui/src/app/
+├── services/
+│   └── image.service.ts        # Update: add file_url/thumbnail_url to ImageRecord;
+│                               #         remove getFileUrl()/getThumbnailUrl() methods
+├── library/
+│   └── library.component.ts    # Update: use img.thumbnail_url instead of getThumbnailUrl(img.id)
+└── detail/
+    └── detail.component.ts     # Update: use img.file_url instead of getFileUrl(img.id)
+
+.env.example                    # Add: S3_PUBLIC_BASE_URL= (empty = local dev proxy fallback)
+```
+
+## Key Implementation Details
+
+### URL construction logic (`api/app/routers/images.py`)
+
+`_image_to_dict` gains a `cdn_base: str | None` parameter:
+
+```python
+def _image_to_dict(image: Image, *, cdn_base: str | None = None, duplicate: bool | None = None):
+    base = cdn_base.rstrip("/") if cdn_base else None
+    file_url = f"{base}/{image.storage_key}" if base else f"/api/v1/images/{image.id}/file"
+    thumbnail_url = (
+        (f"{base}/{image.thumbnail_key}" if base else f"/api/v1/images/{image.id}/thumbnail")
+        if image.thumbnail_key else None
+    )
+    return {
+        ...,          # existing fields unchanged
+        "file_url": file_url,
+        "thumbnail_url": thumbnail_url,
+    }
+```
+
+Each endpoint calls `get_settings()` once and passes `settings.s3_public_base_url` as `cdn_base`.
+
+### Config addition (`api/app/config.py`)
+
+```python
+s3_public_base_url: str | None = None
+```
+
+No validator needed — `None` is the valid "not configured" state.
+
+### UI changes (`ui/src/app/services/image.service.ts`)
+
+`ImageRecord` gains two new fields:
+```typescript
+file_url: string;
+thumbnail_url: string | null;
+```
+
+`getFileUrl(id)` and `getThumbnailUrl(id)` methods are removed. Components use `image.file_url` and `image.thumbnail_url` directly.
+
+## Phase Breakdown
+
+### Phase 1: API — config + URL construction (US1 foundation)
+- Add `s3_public_base_url` to config
+- Update `_image_to_dict` with `cdn_base` parameter
+- Update all call sites to pass `cdn_base` from settings
+- Unit tests for URL construction (both CDN and fallback paths)
+- Integration tests verifying `file_url`/`thumbnail_url` in all image responses
+
+### Phase 2: UI — consume response URLs (US1 + US2)
+- Update `ImageRecord` interface
+- Remove `getFileUrl`/`getThumbnailUrl` methods from service
+- Update library component
+- Update detail component
+- Update service tests
+
+### Phase 3: Config + docs
+- Add `S3_PUBLIC_BASE_URL` to `.env.example`
+- Manual end-to-end verification (local dev + production)

specs/014-r2-cdn-serving/quickstart.md

@@ -0,0 +1,66 @@
+# Quickstart: CDN Image Serving
+
+## Local development (no CDN)
+
+No configuration change required. `S3_PUBLIC_BASE_URL` is unset by default.
+
+```bash
+docker compose up
+```
+
+Upload an image and inspect the API response:
+
+```bash
+curl -s http://localhost:8000/api/v1/images | jq '.items[0] | {file_url, thumbnail_url}'
+```
+
+Expected (local dev — relative proxy paths):
+```json
+{
+  "file_url": "/api/v1/images/550e8400-.../file",
+  "thumbnail_url": "/api/v1/images/550e8400-.../thumbnail"
+}
+```
+
+The UI loads images via these relative paths, which hit the API proxy as before.
+
+---
+
+## Production (CDN configured)
+
+Add `S3_PUBLIC_BASE_URL` to the Vault secret bundle at `reactbin/api/config`:
+
+```
+S3_PUBLIC_BASE_URL = https://cdn.reactbin.juggalol.com
+```
+
+Force VSO sync and restart:
+
+```bash
+kubectl annotate vaultstaticsecret api-secret -n reactbin \
+  secrets.hashicorp.com/force-sync=$(date +%s) --overwrite
+
+kubectl rollout restart deployment/api -n reactbin
+```
+
+Upload a test image and inspect the response:
+
+```bash
+curl -s https://reactbin.juggalol.com/api/v1/images | jq '.items[0] | {file_url, thumbnail_url}'
+```
+
+Expected (production — CDN URLs):
+```json
+{
+  "file_url": "https://cdn.reactbin.juggalol.com/e3b0c44...",
+  "thumbnail_url": "https://cdn.reactbin.juggalol.com/e3b0c44....thumb"
+}
+```
+
+Open the browser network panel on the library page and confirm image requests go to `cdn.reactbin.juggalol.com`, not `/api/`.
+
+---
+
+## Verifying existing images after migration
+
+All existing images were migrated to R2 with the same object keys before this feature was deployed. Once `S3_PUBLIC_BASE_URL` is configured, the API will return CDN URLs for all images immediately — no per-image migration step is needed.

specs/014-r2-cdn-serving/research.md

@@ -0,0 +1,51 @@
+# Research: CDN Image Serving
+
+## Decision 1: Where does URL construction logic live?
+
+**Decision**: In the image router's `_image_to_dict` helper, not in the `StorageBackend`.
+
+**Rationale**: The `StorageBackend` interface is responsible for put/get/delete of object bytes. Adding URL construction there conflates two concerns — storage operations and HTTP URL generation — and would require the storage abstraction to know about CDN configuration. The router already has access to application settings via `get_settings()` and knows the image ID and storage key, making it the natural place to construct URLs.
+
+**Alternatives considered**: Adding a `get_url(key)` method to `StorageBackend` — rejected because it leaks HTTP/CDN concerns into the storage abstraction, violating §2.3.
+
+---
+
+## Decision 2: Fallback URL format in local development
+
+**Decision**: Relative paths (`/api/v1/images/{id}/file`, `/api/v1/images/{id}/thumbnail`) when `S3_PUBLIC_BASE_URL` is not set.
+
+**Rationale**: Relative paths work regardless of the host the app is running on, require no additional configuration, and match how the UI currently constructs these URLs via `getFileUrl(id)` and `getThumbnailUrl(id)`. An absolute fallback would require `API_BASE_URL` to be set in local dev, adding unnecessary setup friction.
+
+**Alternatives considered**: Absolute URL fallback using `API_BASE_URL` — rejected because it adds a mandatory config dependency where none exists today.
+
+---
+
+## Decision 3: Trailing slash normalisation
+
+**Decision**: Strip trailing slash from `S3_PUBLIC_BASE_URL` at construction time using `rstrip('/')` in the config validator or at point of use.
+
+**Rationale**: Prevents double-slash URLs (`https://cdn.example.com//key`) if the operator includes a trailing slash in the configured value. Simple, defensive, zero-cost.
+
+---
+
+## Decision 4: Proxy endpoints retained or removed?
+
+**Decision**: Retained, fully functional, unchanged.
+
+**Rationale**: Spec FR-005 explicitly requires them. They serve as the local dev fallback and a safety net if the CDN is temporarily unavailable or misconfigured. Removing them would break local development immediately.
+
+---
+
+## Decision 5: `storage_key` and `thumbnail_key` in API response
+
+**Decision**: Keep both fields in the response alongside the new `file_url` and `thumbnail_url`.
+
+**Rationale**: Removing them is a breaking API change. The UI currently reads `thumbnail_key` to decide whether a thumbnail exists. After this change the UI will use `thumbnail_url` (null when no thumbnail), but the keys remain in the response for backward compatibility with any tooling.
+
+---
+
+## Decision 6: Settings access in `_image_to_dict`
+
+**Decision**: Pre-compute the CDN base URL string once per request at the endpoint level and pass it into `_image_to_dict` as a parameter, rather than calling `get_settings()` inside the helper.
+
+**Rationale**: Keeps `_image_to_dict` a pure function (easier to test), avoids calling `get_settings()` inside a helper that is called in a loop (image list endpoint), and makes the dependency explicit.

specs/014-r2-cdn-serving/spec.md

@@ -0,0 +1,93 @@
+# Feature Specification: CDN Image Serving
+
+**Feature Branch**: `014-r2-cdn-serving`
+**Created**: 2026-05-08
+**Status**: Draft
+**Input**: User description: "R2 CDN image serving with local dev fallback to API proxy"
+
+## Overview
+
+Images and thumbnails are currently served by proxying bytes through the API. This feature changes image delivery so that clients receive direct URLs pointing to a CDN edge network, eliminating the API as a middleman for image content. In local development, where no CDN is available, the API proxy endpoints remain as a fallback so the developer experience is unchanged.
+
+---
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - Images Load Directly from CDN (Priority: P1)
+
+When a visitor views the image library or opens an image detail page, images and thumbnails are fetched directly from the CDN rather than through the application server. The page loads faster because image bytes no longer pass through the API.
+
+**Why this priority**: Core value of the feature. Reduces API load and improves image load speed for all users.
+
+**Independent Test**: Upload an image, open the library page, and inspect the network requests. Image and thumbnail requests should go directly to the CDN domain, not to `/api/`. The API response for the image list should include direct CDN URLs for each image and thumbnail.
+
+**Acceptance Scenarios**:
+
+1. **Given** a published image, **When** the visitor loads the image library, **Then** each thumbnail `src` URL points to the CDN domain and loads without passing through the API
+2. **Given** a published image, **When** the visitor opens the detail page, **Then** the full image `src` URL points to the CDN domain
+3. **Given** the API returns image metadata, **When** the response is inspected, **Then** it includes a `file_url` and `thumbnail_url` field containing full CDN URLs
+
+---
+
+### User Story 2 - Local Development Works Without CDN (Priority: P2)
+
+In local development, where no CDN is configured, images continue to load via the existing API proxy endpoints. No additional setup is required to run the application locally.
+
+**Why this priority**: Developer experience must not regress. The proxy endpoints must remain functional and be used automatically when no CDN is configured.
+
+**Independent Test**: Run the application locally without setting a public base URL. Upload an image. Verify the library and detail pages load images correctly via the API proxy endpoints, with no errors or broken images.
+
+**Acceptance Scenarios**:
+
+1. **Given** no CDN base URL is configured, **When** the API returns image metadata, **Then** `file_url` and `thumbnail_url` point to the API proxy paths (e.g. `/api/v1/images/{id}/file`)
+2. **Given** no CDN base URL is configured, **When** a visitor views the library, **Then** thumbnails load via the API proxy with no broken images
+3. **Given** a CDN base URL is configured, **When** the application starts, **Then** all image URLs use the CDN domain instead of the proxy paths
+
+---
+
+### Edge Cases
+
+- What happens when the CDN base URL is set but the object does not exist in CDN storage? The browser receives a 404 from the CDN — the API does not re-proxy the content.
+- What happens if an image has no thumbnail (thumbnail generation failed)? The `thumbnail_url` field is absent or null; the UI falls back to the full image URL as it does today.
+- What happens if the CDN base URL has a trailing slash? The system normalises the URL to avoid double slashes in constructed paths.
+
+---
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: The API MUST include a `file_url` field in all image metadata responses, containing the full URL from which the image file can be fetched
+- **FR-002**: The API MUST include a `thumbnail_url` field in all image metadata responses when a thumbnail exists, containing the full URL from which the thumbnail can be fetched
+- **FR-003**: When a CDN base URL is configured, `file_url` and `thumbnail_url` MUST point to the CDN domain
+- **FR-004**: When no CDN base URL is configured, `file_url` and `thumbnail_url` MUST point to the existing API proxy endpoints so local development continues to work without additional setup
+- **FR-005**: The existing API proxy endpoints (`/images/{id}/file`, `/images/{id}/thumbnail`) MUST remain functional regardless of whether a CDN base URL is configured
+- **FR-006**: The UI MUST use `file_url` and `thumbnail_url` from the API response to render images, rather than constructing proxy URLs client-side
+- **FR-007**: The CDN base URL MUST be configurable via environment variable; no value is required in local development
+- **FR-008**: A trailing slash in the configured CDN base URL MUST NOT result in double slashes in constructed image URLs
+- **FR-009**: When `thumbnail_url` is null, the UI MUST fall back to `file_url` for thumbnail display rather than rendering a broken image
+
+### Key Entities
+
+- **Image metadata response**: Extended to include `file_url` and `thumbnail_url` fields alongside existing fields (`id`, `filename`, `tags`, `width`, `height`, `mime_type`, etc.)
+
+---
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: In production, zero image or thumbnail requests pass through the API server — all are served directly by the CDN
+- **SC-002**: Local development requires no additional configuration beyond what is already required — `docker compose up` continues to work with images loading correctly
+- **SC-003**: All existing image-related API integration tests continue to pass after the change
+- **SC-004**: Image metadata responses include `file_url` and `thumbnail_url` fields for 100% of images that have been successfully stored
+
+---
+
+## Assumptions
+
+- The CDN storage bucket and public domain are already configured and operational before this feature is deployed — this feature only changes how URLs are constructed and served, not how objects are stored
+- Object keys in CDN storage are identical to those used in the existing storage backend — no key remapping is needed
+- The CDN serves objects publicly without authentication — no signed URL generation is required
+- The existing API proxy endpoints are retained as functional fallbacks; the UI stops calling them in production but they are not removed
+- Local development uses the existing MinIO-backed proxy and does not require a locally running CDN

specs/014-r2-cdn-serving/tasks.md

@@ -0,0 +1,116 @@
+# Tasks: CDN Image Serving
+
+**Input**: Design documents from `specs/014-r2-cdn-serving/`
+**Prerequisites**: plan.md ✅, spec.md ✅, research.md ✅, contracts/image-response.md ✅, quickstart.md ✅
+
+**Tests**: Unit tests for URL construction logic; integration tests asserting `file_url` and `thumbnail_url` in all image responses. Tests accompany each implementation task per §5.1.
+
+**Organization**: Phase 1 adds the config value (foundational — blocks everything). Phase 2 implements US1 (CDN URL serving in API + UI consumption). Phase 3 verifies US2 (local dev fallback). Polish runs the full suite and manual end-to-end check.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no dependencies)
+- **[Story]**: Which user story this task belongs to
+
+---
+
+## Phase 1: Foundational (Config)
+
+**Goal**: Add `s3_public_base_url` to config and `.env.example`. All US1 and US2 tasks depend on this.
+
+**⚠️ CRITICAL**: No user story work can begin until this phase is complete.
+
+- [X] T001 Add `s3_public_base_url: str | None = None` to the `Settings` class in `api/app/config.py` (after `api_base_url`); add `S3_PUBLIC_BASE_URL=` with comment "# CDN base URL for serving images (e.g. https://cdn.example.com). Leave empty in local dev to use API proxy fallback." to `.env.example` after the `API_BASE_URL` line
+
+**Checkpoint**: Config in place — user story work can begin.
+
+---
+
+## Phase 2: User Story 1 — Images Load Directly from CDN (Priority: P1) 🎯 MVP
+
+**Goal**: API returns `file_url` and `thumbnail_url` in all image responses; UI uses those fields to render images rather than constructing proxy URLs client-side.
+
+**Independent Test**: With `S3_PUBLIC_BASE_URL=https://cdn.reactbin.juggalol.com` set, call `GET /api/v1/images` and confirm each item has `file_url` starting with `https://cdn.reactbin.juggalol.com/` and `thumbnail_url` starting with `https://cdn.reactbin.juggalol.com/` (or null). Open the library page in a browser and confirm image requests go to the CDN domain in the network panel.
+
+- [X] T002 [US1] Write unit tests in `api/tests/unit/test_url_construction.py` covering four cases: (1) CDN base set, image has thumbnail — `file_url` and `thumbnail_url` are CDN URLs; (2) CDN base set, image has no thumbnail — `thumbnail_url` is None; (3) CDN base not set, image has thumbnail — `file_url` is `/api/v1/images/{id}/file` and `thumbnail_url` is `/api/v1/images/{id}/thumbnail`; (4) CDN base not set, no thumbnail — `thumbnail_url` is None. Test the trailing-slash normalisation case (CDN base with trailing slash produces no double-slash). Import and call `_image_to_dict` directly with a mock `Image` object.
+
+- [X] T003 [US1] Update `_image_to_dict` in `api/app/routers/images.py`: add `cdn_base: str | None = None` keyword parameter; compute `_base = cdn_base.rstrip("/") if cdn_base else None`; set `file_url = f"{_base}/{image.storage_key}" if _base else f"/api/v1/images/{image.id}/file"`; set `thumbnail_url = (f"{_base}/{image.thumbnail_key}" if _base else f"/api/v1/images/{image.id}/thumbnail") if image.thumbnail_key else None`; add `"file_url": file_url` and `"thumbnail_url": thumbnail_url` to the returned dict. Run `make test-unit` and confirm T002 tests pass.
+
+- [X] T004 [US1] Update every `_image_to_dict(...)` call site in `api/app/routers/images.py`: at the top of each endpoint function that calls `_image_to_dict`, add `_cdn_base = get_settings().s3_public_base_url` (import `get_settings` is already present); pass `cdn_base=_cdn_base` to every `_image_to_dict` call in that endpoint. Affected endpoints: `upload_image`, `list_images`, `get_image`, `patch_image_tags`. Confirm `get_settings()` is called once per endpoint, not once per image in a loop (for `list_images`, call it before the list comprehension).
+
+- [X] T005 [US1] Update integration tests: in `api/tests/integration/test_upload.py`, add assertions after existing response checks that `"file_url"` is present in the response body and starts with `/api/v1/images/` (since no CDN is configured in test env); add the same assertion for `"thumbnail_url"` in `test_upload_returns_thumbnail_key`; add assertion that `thumbnail_url` is None in the test that expects `thumbnail_key` to be None. Run `make test-integration` and confirm all pass.
+
+- [X] T006 [P] [US1] Update `ui/src/app/services/image.service.ts`: add `file_url: string` and `thumbnail_url: string | null` to the `ImageRecord` interface; remove the `getFileUrl(id: string): string` method; remove the `getThumbnailUrl(id: string): string` method.
+
+- [X] T007 [P] [US1] Update `ui/src/app/library/library.component.ts`: replace `[src]="imageService.getThumbnailUrl(img.id)"` (line 77) with `[src]="img.thumbnail_url ?? img.file_url"` — fall back to `file_url` when thumbnail is absent (FR-009); update `ui/src/app/library/library.component.spec.ts` to add `file_url` and `thumbnail_url` to any mock `ImageRecord` objects and remove any references to `getThumbnailUrl()`.
+
+- [X] T008 [P] [US1] Update `ui/src/app/detail/detail.component.ts`: replace `[src]="imageService.getFileUrl(image.id)"` (line 52) with `[src]="image.file_url"`; update `ui/src/app/detail/detail.component.spec.ts` to add `file_url` and `thumbnail_url` to any mock `ImageRecord` objects and remove any references to `getFileUrl()`.
+
+- [X] T009 [US1] Update `ui/src/app/services/image.service.spec.ts`: add `file_url` and `thumbnail_url` fields to any mock `ImageRecord` objects used in tests; remove any test cases that test `getFileUrl()` or `getThumbnailUrl()` (these methods no longer exist). Run UI tests and confirm they pass.
+
+**Checkpoint**: US1 complete. API returns CDN URLs when configured; UI uses response fields to render images.
+
+---
+
+## Phase 3: User Story 2 — Local Development Works Without CDN (Priority: P2)
+
+**Goal**: Confirm that with no `S3_PUBLIC_BASE_URL` configured, `file_url` and `thumbnail_url` fall back to API proxy paths and images load correctly in local dev.
+
+**Independent Test**: Run `make test-unit && make test-integration` with no `S3_PUBLIC_BASE_URL` set (the default). Confirm all tests pass and that `file_url` values in integration test responses begin with `/api/v1/images/`.
+
+- [X] T010 [US2] Verify US2: run `make test-unit` and confirm the url-construction unit tests for the "no CDN base" case (T002 cases 3 and 4) pass; run `make test-integration` and confirm the updated upload tests (T005) pass — they already assert relative proxy paths since the test environment has no `S3_PUBLIC_BASE_URL`. Confirm `docker compose up` starts cleanly and images load in the browser via the proxy paths with no console errors.
+
+**Checkpoint**: US2 verified. Local development requires no additional configuration.
+
+---
+
+## Phase 4: Polish & Cross-Cutting Concerns
+
+- [X] T011 [P] Run `ruff check api/app/routers/images.py api/app/config.py` and fix any lint issues; run `ruff format --check` and format if needed.
+
+- [X] T012 Run end-to-end verification per `specs/014-r2-cdn-serving/quickstart.md`: in production with `S3_PUBLIC_BASE_URL` set, call `GET /api/v1/images` and confirm `file_url` and `thumbnail_url` begin with `https://cdn.reactbin.juggalol.com/`; open the library page in a browser and confirm image requests in the network panel go to `cdn.reactbin.juggalol.com`, not `/api/`.
+
+---
+
+## Dependencies & Execution Order
+
+- T001 must complete before any other task
+- T002 before T003 (tests before implementation — unit test first)
+- T003 before T004 (update helper before call sites)
+- T004 before T005 (implementation before integration tests)
+- T006, T007, T008 can run in parallel after T001 (different files)
+- T009 after T006 (spec depends on updated interface)
+- T010 after T003–T009 (verification requires full implementation)
+- T011 after T003–T004 (lint the changed files)
+- T012 last (manual end-to-end)
+
+### Execution Order Summary
+
+```
+Step 1: T001                          (foundational: config)
+Step 2: T002                          (US1: unit tests first)
+Step 3: T003                          (US1: implement _image_to_dict)
+Step 4: T004 ∥ T006 ∥ T007 ∥ T008    (US1: call sites + UI in parallel)
+Step 5: T005 ∥ T009                   (US1: integration tests + service spec)
+Step 6: T010                          (US2: verify local dev fallback)
+Step 7: T011                          (polish: lint)
+Step 8: T012                          (polish: manual end-to-end)
+```
+
+---
+
+## Implementation Strategy
+
+### MVP (US1 only — CDN URLs in API + UI)
+
+1. T001 — config
+2. T002–T005 — API implementation and tests
+3. T006–T009 — UI updates
+4. **STOP and VALIDATE**: `make test-unit && make test-integration`, check browser network panel
+
+### Incremental Delivery
+
+1. T001–T005 (API only) → deploy → verify CDN URLs appear in API responses
+2. T006–T009 (UI) → deploy → verify browser fetches images from CDN
+3. T010 (local dev verification) → confirm fallback intact
+4. T011–T012 (polish + end-to-end) → ship

ui/public/site.webmanifest

@@ -0,0 +1 @@
+{"name":"","short_name":"","icons":[{"src":"/android-chrome-192x192.png","sizes":"192x192","type":"image/png"},{"src":"/android-chrome-512x512.png","sizes":"512x512","type":"image/png"}],"theme_color":"#ffffff","background_color":"#ffffff","display":"standalone"}

ui/src/app/detail/detail.component.spec.ts

@@ -10,7 +10,8 @@ import { routes } from '../app.routes';
 const MOCK_IMAGE = {
   id: 'img-1', hash: 'abc', filename: 'test.jpg', mime_type: 'image/jpeg',
   size_bytes: 100, width: 10, height: 10, storage_key: 'abc',
-  thumbnail_key: null, created_at: '2026-01-01T00:00:00Z', tags: ['cat', 'funny'],
+  thumbnail_key: null, file_url: '/api/v1/images/img-1/file', thumbnail_url: null,
+  created_at: '2026-01-01T00:00:00Z', tags: ['cat', 'funny'],
 };
 
 describe('DetailComponent', () => {

ui/src/app/detail/detail.component.ts

@@ -49,7 +49,7 @@ const PLACEHOLDER_SVG = `data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/s
 
       <img
         class="full-image"
-        [src]="imageService.getFileUrl(image.id)"
+        [src]="image.file_url"
         [alt]="image.filename"
         (error)="onImgError($event)"
       />

ui/src/app/library/library.component.spec.ts

@@ -19,7 +19,7 @@ function makeActivatedRoute(queryParams: Record<string, string> = {}) {
 
 const EMPTY_PAGE = { items: [], total: 0, limit: 50, offset: 0 };
 const ONE_IMAGE = {
-  items: [{ id: '1', filename: 'a.jpg', tags: ['cat'], hash: '', mime_type: 'image/jpeg', size_bytes: 1, width: 1, height: 1, storage_key: '', thumbnail_key: null, created_at: '' }],
+  items: [{ id: '1', filename: 'a.jpg', tags: ['cat'], hash: '', mime_type: 'image/jpeg', size_bytes: 1, width: 1, height: 1, storage_key: '', thumbnail_key: null, file_url: '/api/v1/images/1/file', thumbnail_url: null, created_at: '' }],
   total: 1, limit: 50, offset: 0,
 };
 

ui/src/app/library/library.component.ts

@@ -74,7 +74,7 @@ const PLACEHOLDER_SVG = `data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/s
           (keydown.enter)="router.navigate(['/images', img.id])"
         >
           <img
-            [src]="imageService.getThumbnailUrl(img.id)"
+            [src]="img.thumbnail_url ?? img.file_url"
             [alt]="img.filename"
             loading="lazy"
             (error)="onImgError($event)"

ui/src/app/services/image.service.ts

@@ -12,6 +12,8 @@ export interface ImageRecord {
   height: number;
   storage_key: string;
   thumbnail_key: string | null;
+  file_url: string;
+  thumbnail_url: string | null;
   created_at: string;
   tags: string[];
   duplicate?: boolean;
@@ -51,14 +53,6 @@ export class ImageService {
     return this.http.get<ImageRecord>(`${this.base}/images/${id}`);
   }
 
-  getFileUrl(id: string): string {
-    return `${this.base}/images/${id}/file`;
-  }
-
-  getThumbnailUrl(id: string): string {
-    return `${this.base}/images/${id}/thumbnail`;
-  }
-
   updateTags(id: string, tags: string[]): Observable<ImageRecord> {
     return this.http.patch<ImageRecord>(`${this.base}/images/${id}/tags`, { tags });
   }

ui/src/index.html

@@ -5,6 +5,11 @@
   <title>Reactbin</title>
   <base href="/">
   <meta name="viewport" content="width=device-width, initial-scale=1">
+  <link rel="apple-touch-icon" sizes="180x180" href="apple-touch-icon.png">
+  <link rel="icon" type="image/png" sizes="32x32" href="favicon-32x32.png">
+  <link rel="icon" type="image/png" sizes="16x16" href="favicon-16x16.png">
+  <link rel="manifest" href="site.webmanifest">
+  <link rel="icon" href="favicon.ico">
 </head>
 <body>
   <app-root></app-root>