[bosbaber]

No description provided.

[linear]

WAL-1205 Migrate protea and admin portals to configuration files

Plan: TypeScript configa for protea & botanist

Goal

Create a TypeScript library — the equivalent of the Go go/configa library — that both protea (frontend/wallet) and botanist (admin portal) use to load their server-side configuration.

After this work, the server side ("backend") of both React Router apps depends on a minimal set of environment variables and instead reads configuration from a YAML config file:

• Local: the YAML file is bind-mounted into the container.
• Kubernetes: the YAML is delivered via a ConfigMap and mounted as a volume.
• Secrets: handled exactly like the Go configa library — {{ secret "name" "key" }} templates resolved at runtime by calling the Kubernetes API in-cluster.

The same YAML files and the same {{ secret … }} template syntax must work for both the Go services and the new TS services, so ops writes config once.

Branch context

This branch (stephan/wal-1205) is based on stephan/wal-1157, which has already migrated the Go backend to the YAML/configa scheme. That is a large, working reference implementation we build on — we are not pioneering the pattern, we are following it for the two TypeScript apps.

What stephan/wal-1157 already delivers (our reference — do not redo)

• Backend Go config loader: go/backend/config/start.go + migration.go. Typed StartConfig struct with validate tags, CONFIG env var (comma-separated YAML files, later overlays win), {{ secret … }} resolution via configa.InClusterSecretClient, applyStartDefaults, and mode-based validation (prod/dev/local/test).
• Helm RBAC (in the interledger-app chart): helm/interledger-app/templates/rbac.backend.yaml — renders a scoped Role (get on named secrets, no wildcards) + RoleBinding, driven by .Values.backend.secretAccess + .Values.backend.server.serviceAccount.name. This is the exact template to mirror for frontend/admin.
• Helm config delivery: backend ConfigMap templates + deployment env CONFIG=/etc/backend/config.yaml, plus validation.backend.yaml.
• Local docker-compose config pattern: local/config/backend.yaml (+ backend.migration.yaml), mounted read-only, with a config-override/ overlay. CONFIG=/etc/backend/config.yaml,/etc/backend/config-override.yaml (see local/wallet.yaml). make prep creates empty override files; config-override/ is gitignored.
• kind harness (in k8s/): the k8s/Makefile already builds, loads, and deploys backend protea botanist and the full interledger-app chart via k8s/kind/values.interledger-app.yaml, with certs, ingressroutes, manifests/app-secrets.yaml, and scripts/validate.sh.

What is NOT yet done (this project)

• No TypeScript configa library exists.
• protea and botanist are still env-var based. In the kind values, the frontend: and admin: sections still use the old config: block with *_ref keys that render secretKeyRef env injection — not configa YAML. protea's app/env.server.ts still validates a long knownEnvKeys* list; botanist has no validation.
• The two TS apps are still independent pnpm projects (built with per-app Docker context ./typescript/protea / ./typescript/botanist in both the kind Makefile and tooling/github-scripts/constants.js). No workspace, so no shared library is reachable at build time.

Scope

• Everything lands in interledger-app. No interledger-app-deploy changes in this project — rollout there happens later, once we have confidence.
• Confidence is proven two ways:
  1. Local docker-compose (the primary target — get this fully working first).
  2. kind, via the k8s/ harness (proves in-cluster secret resolution + RBAC).
• The Helm chart owns the RBAC, mirroring rbac.backend.yaml.

---

Prerequisite (separate PR — NOT part of this project)

Upgrade protea and botanist to the current Node LTS (Node 24.x at time of writing).

Today the two apps diverge: protea's Dockerfile uses node:20-alpine, botanist's engines require >=22.19, and each app pins pnpm@8.5.0 independently. A single pnpm workspace needs one consistent Node + pnpm baseline. Do this first in its own PR:

• Bump both Dockerfiles and engines to the current Node LTS.
• Align the pnpm version across both apps.
• Confirm both apps build, boot, and pass their existing checks on the new Node.

This PR is a hard prerequisite — the workspace and library work below assumes both apps are already on the same Node LTS and pnpm version.

---

Development approach (read first)

1. Local docker-compose is the primary target. Get the entire flow working end-to-end in the local environment before touching kind or CI. The backend already runs this way locally — mirror its local/config/*.yaml + config-override/ + CONFIG mount pattern for protea/botanist.
2. Reuse the existing backend patterns. The reference is already in the tree and working:
   • Config loader shape → mirror go/backend/config/start.go.
   • RBAC → mirror rbac.backend.yaml.
   • Local mount + override → mirror local/wallet.yaml + local/config/backend.yaml + make prep.
   • kind → the Makefile already builds/deploys protea & botanist; we only change how they're configured.
3. Preserve live reload. Developers rely on live reload (Vite dev / react-router dev). The local setup uses target: dev and bind-mounts app/ into the container (see local/protea.yaml, local/botanist.yaml). This must keep working. Loading config from a bind-mounted YAML file must not break hot reload of app code. Verify live reload still functions after the change.
4. Use the e2e tests to check your work — incrementally, not all at once. See Verification. Running the whole suite from the start takes too long; run the targeted subsets in order and always with concurrency.

---

Decisions (already agreed)

Decision	Choice
Sharing mechanism	pnpm workspace under typescript/ (expand Docker build context, bundle via Vite)
Secret handling	Full parity — in-cluster Kubernetes API fetch, identical {{ secret … }} syntax
Validation	Zod schemas
RBAC	Helm chart owns it, mirroring rbac.backend.yaml

---

Work breakdown

1. pnpm workspace under typescript/

protea and botanist are independent pnpm projects today. Establish a workspace:

• Add typescript/pnpm-workspace.yaml:

  packages:
    - "protea"
    - "botanist"
    - "packages/*"

• Add a private typescript/package.json with a single packageManager (pnpm version from the prerequisite PR) and shared engines.

• Generate a single typescript/pnpm-lock.yaml. (protea/botanist already live at typescript/protea / typescript/botanist — just workspace membership.)

2. Library — @interledger/configa at typescript/packages/configa

Faithful TypeScript port of go/configa, ESM, built with tsup (or tsc). Match the Go public surface and the behaviour the backend already relies on:

• parseConfig(files: string[], opts?) — read the first file, deep-merge overlays in order (maps deep-merge; scalars/arrays overlay-wins; last file wins — port of merge.go). Detect {{.
• resolve<T>(schema: ZodType<T>): Promise<T> — if templates present and no secret client → throw ErrNoSecretClient; resolve templates; yaml.parse; schema.parse(...) → typed + validated result.
• Template resolver — regex match of {{ secret "name" "key" }} (whitespace-tolerant, byte-compatible with the YAML the Go services already consume). Walk all string leaves; per-resolve cache keyed by secret name (mirrors resolve.go). Only the secret function — not a full Go-template engine.
• InClusterSecretClient — port of k8s.go: lazy-load SA token/CA/namespace from /var/run/secrets/kubernetes.io/serviceaccount/*, read KUBERNETES_SERVICE_HOST/PORT, GET /api/v1/namespaces/{ns}/secrets/{name} over CA-pinned TLS (Node undici dispatcher with the SA CA), base64-decode .data. Same sentinel errors: ErrNoSecretClient, ErrSecretNotFound, ErrSecretForbidden, ErrSecretFetchFailed.
• SecretClient interface + a fake for tests.
• Vitest suite porting the cases from configa_test.go / k8s_test.go.

Dependencies: yaml, zod (peer), undici (or Node global fetch with a custom dispatcher).

3. Wire the library into protea & botanist

• Add "@interledger/configa": "workspace:*" to both apps.
• Add the package to ssr.noExternal in both Vite configs so it is bundled into the server output (the runner image copies only the app's own artifacts).
• protea: replace app/env.server.ts with a Zod ConfigSchema (the TS analogue of the backend's StartConfig) loaded once at server startup from CONFIG via InClusterSecretClient. Reduce env vars to the bootstrap set: CONFIG, NODE_ENV, INTERLEDGER_APP_VERSION, KUBERNETES_SERVICE_*.
• botanist: introduce the same startup path (it has no validation today).

4. Local docker-compose (do this before kind/CI)

Mirror the backend's local pattern exactly:

• Author local/config/protea.yaml and local/config/botanist.yaml (base config; non-secret values in plaintext, no {{ secret }} needed locally).
• Add config-override/protea.yaml / config-override/botanist.yaml to make prep (empty override files; config-override/ is gitignored) so devs can override locally like they do for the backend.
• In local/protea.yaml / local/botanist.yaml: mount the config read-only, set CONFIG=/etc/<app>/config.yaml,/etc/<app>/config-override.yaml, and shrink the environment: blocks to the bootstrap set.
• No secret client needed locally — no {{ secret }} templates survive, so configa skips all Kubernetes calls (same as the backend's local path).
• Keep target: dev and the app/ bind-mount so live reload keeps working. Verify hot reload after the change.
• Start the stack with make all-nowatch in local/ and verify both apps boot and serve.

5. Docker & CI build context

• Change the TS build context from ./typescript/protea / ./typescript/botanist to ./typescript in both:
  • tooling/github-scripts/constants.js (CI), and
  • k8s/Makefile build-app (currently docker build --file …/protea/Dockerfile …/typescript/protea).
• Rewrite both Dockerfiles for workspace installs: copy pnpm-workspace.yaml + lockfile + packages/ + the target app, pnpm install --frozen-lockfile --filter <app>..., then pnpm --filter <app> build. Runner stage copies the built app only (library bundled in via ssr.noExternal).
• Verify each image builds and boots.

6. Helm chart: config delivery + RBAC (chart-owned)

• ConfigMap + volume: add configMap.frontend.yaml / configMap.admin.yaml templates rendering the app YAML from values; mount as a volume; set CONFIG to the mounted path(s) on the frontend/admin deployments (mirror how the backend deployment does it).
• RBAC: add rbac.frontend.yaml / rbac.admin.yaml mirroring rbac.backend.yaml, driven by .Values.frontend.secretAccess / .Values.admin.secretAccess + the frontend/admin SA name. The frontend SA is "" today, so this assigns it a real SA.
• helm-unittest: add tests under helm/interledger-app/tests/ for the new ConfigMaps, Roles, and RoleBindings — the existing backend.*_test.yaml / mock *serviceaccount_test.yaml files are the template.

7. kind end-to-end testing (extend k8s/)

The harness already builds/loads/deploys protea & botanist and the interledger-app chart. The remaining work is to switch their configuration from env vars to configa YAML:

• Values migration: in k8s/kind/values.interledger-app.yaml, convert the frontend: and admin: config: blocks (currently *_ref env-injection style) to configa YAML with {{ secret … }} templates, plus serviceAccount.create: true + secretAccess: [...] — exactly like the backend: section already does.
• Secrets: add the frontend/admin secret keys to k8s/manifests/app-secrets.yaml so the templates resolve.
• Build context: update build-app for the new ./typescript context (see step 5).
• Validate: extend k8s/scripts/validate.sh to hit protea/botanist health endpoints (/healthz) and confirm pods are 1/1 Running with secrets resolved (no CrashLoop). This is the kind acceptance gate.

---

Verification with e2e tests

The e2e suite is a Go/godog BDD suite. Scenarios are tagged (-tags) and run concurrently (-concurrency).

Do NOT run the whole suite from the start — it takes too long. Run these targeted subsets in this order, only moving on once the previous is green:

1. Signup
2. P2P payments
3. Deposit

Always use --concurrency=5.

Bring up the full local stack first (make all-nowatch in local/), then from e2e/:

# 1. Signup
go test -v -timeout 10m -args -tags signup --concurrency=5

# 2. P2P payments (only after signup passes)
go test -v -timeout 10m -args -tags p2p --concurrency=5

# 3. Deposit (only after p2p passes)
go test -v -timeout 10m -args -tags deposit --concurrency=5

Notes:

• Tags live in e2e/features/*.feature (@signup, @p2p, @deposit).
• Keep -timeout 10m — some flows (multiple KYC steps) exceed 5 minutes.
• On failure, check screenshots under e2e/debug/<feature>__<scenario>/.
• See e2e/AGENTS.md and e2e/README.md for environment gotchas (e.g. make reset for stale tel validation issues).

---

Suggested sequencing (each step independently reviewable)

0. (Prerequisite PR) Upgrade protea & botanist to the current Node LTS + unify pnpm.
1. pnpm workspace scaffold.
2. @interledger/configa package + Vitest tests (nothing depends on it yet).
3. Adopt in protea; get local docker-compose fully working (live reload preserved).
4. Verify with e2e: signup → p2p → deposit (--concurrency=5), in order.
5. protea Dockerfile + build-context changes (CI + kind Makefile); image builds & boots.
6. Helm: ConfigMap + rbac.frontend.yaml for frontend; helm-unittest green.
7. kind: migrate frontend values to configa; deploy + validate protea end-to-end (secret resolution proven).
8. Repeat 3–7 for botanist (rbac.admin.yaml, admin values, botanist e2e tags @botanist/admin features).

---

Residual risks

• Vite SSR externalization of undici / yaml — confirm they're bundled into, or present in, the runner image.
• Live reload regression — the highest-risk day-to-day impact; explicitly verify dev hot-reload after the config change.
• Config/secret split — be deliberate about which keys are non-secret (ConfigMap) vs secret ({{ secret … }}); the kind *_ref keys today are a guide to what's currently treated as secret.
• kind image builds are slow — TS multi-stage builds add minutes; keep the split build-app / build-mock targets so mock-only runs stay fast.

Review in Linear

[github-actions]

E2E Test Report

E2E markdown report is available as an artifact:

• Run artifacts: https://github.com/interledger/interledger-app/actions/runs/28925909432
• Artifact name: e2e-markdown-report