Skip to content

Phase 0 — Foundations

Goal: everything the build needs before the first line of business logic: accounts and environments, the single pipeline, the private path from the Workers to the droplet, and a verified picture of what Bifrost actually does.

Milestone M0: a Worker deployed to staging by the pipeline calls Bifrost’s health endpoint through its Workers VPC binding, with no public hostname involved.

Note: the droplet lockdown is not in this phase. It happens in phase 9. Everything here is built so that the lockdown only changes infrastructure, not code.

ID Task Who Needs Status
P0.01 Bitwarden vault and existing secrets You — done (2026-11-01)
P0.02 Cloudflare resources You — done (2026-11-01)
P0.03 Database version and droplet capacity You — done (2026-11-01)
P0.04 GitHub repo settings and secrets You P0.02, P0.03 done (2026-11-01)
P0.05 Third-party accounts You — todo
P0.06 The single pipeline (workflows) Agent P0.04 merged — code #38 (with the reviewer’s least-privilege fixes); real-Postgres job code #54. On main the gates pass, real Postgres included (run 41536379936, 2026-11-02); migrate and every deploy step skip until SELF_HOSTED_RUNNER is set (P0.09). CLOUDFLARE_ACCOUNT_ID and the deploy token are set; PR previews skip until CLOUDFLARE_PAGES_PREVIEW_TOKEN exists
P0.07 Wrangler environments and Pages projects You + agent P0.02 merged — code #37, bindings code #64. The Pages projects exist (2026-11-01). You: custom domains, then the first real deploy
P0.08 Helm layout; staging Bifrost; Postgres for both environments You + agent P0.02, P0.03 done (2026-11-01) — code #57; no staging Bifrost and daily backups by decision (2026-11-02); as-built section 15; the reviewer’s pod hardening applied 2026-11-05
P0.09 Self-hosted runner in the cluster You + agent P0.08 todo
P0.10 Tunnel, gateway route-split proxy, Workers VPC Services You + agent P0.08 installed (2026-11-01) — code #60, bindings on #64 (#37 was merged first); as-built section 16. Hyperdrive creation proved the database path end to end (P1.06). Left: a call from a deployed Worker (after P3.01); route-split and cloudflared upgraded 2026-11-05 (path fix, /api/models/details, pod hardening; checked, as-built section 16)
P0.11 A provider key on staging Bifrost You P0.08 not needed — staging uses a mock gateway (decisions log, Daily backups; no staging Bifrost)
P0.12 Code-quality gates in the repo Agent P0.06 merged — code #13, code #38; history allowlist code #73; Dependabot without major versions code #91
P0.13 Verify Bifrost and the private path Agent P0.10, P0.11 todo
P0.14 M0: staging smoke Agent P0.06, P0.07, P0.10 todo

P0.01 — Bitwarden vault and existing secrets

Section titled “P0.01 — Bitwarden vault and existing secrets”

Who: You · Needs: —

Create the Bitwarden account (free plan) with MFA. Move in what already exists: the Bifrost encryption key and Postgres password (retrieve them from the cluster), the account MFA recovery codes, and the droplet SSH key.

  • Spec: decisions log, Configuration and secrets management; ../infra/secrets-inventory.md
  • Done when: every “Bitwarden only” row in the inventory, plus the two Bifrost secrets, has an entry. The vault itself has MFA on.

Who: You · Needs: —

In the Cloudflare dashboard, for both staging and production, created once so the pipeline is set up once:

  • Zone settings for router.africa: SSL/TLS Full (strict), Always Use HTTPS, Universal SSL on. Staging hostnames stay one level deep (api-staging., not staging.api.) so Universal SSL covers them.
  • Hostnames: no DNS records by hand. Attaching the Worker and Pages custom domains in P0.07 creates them:
    • api. and api-staging.: apps/api
    • app. and app-staging.: the dashboard, with apps/dashboard-api on /api/*
    • admin. and admin-staging.: the admin app, with /api/*; attached only once Access protects them (P8.01)
    • no public hostname for Bifrost, Postgres or niobi-proxy; prod-bifrost-core. stays until P9.01
  • R2 buckets: router-africa-content-staging and router-africa-content-production (stored content); router-africa-db-backups-production (database backups).
  • Queues: usage-events-staging, usage-events-production, niobi-callbacks-staging, niobi-callbacks-production.
  • Zero Trust: enable it (free plan) and choose the team name; Access and the tunnel use it later.
  • API tokens, scoped to this account:
    • deploy token: edit on Workers Scripts, Workers Routes (zone router.africa), Pages, Queues, R2 and Hyperdrive. One token serves both environments; Cloudflare can’t scope a token to one environment’s resources, so two would carry the same power.
    • R2 backup token: Object Read & Write on router-africa-db-backups-production only. Keep its S3 access key and secret; the production database uses them (P0.08).

Do not connect Workers Builds or the Pages Git integration.

  • Spec: ../architecture/cicd.md section 1; decisions log, CI/CD pipeline
  • Done when: the resources exist per environment, the token is in Bitwarden, and the inventory rows are filled in.

P0.03 — Database version and droplet capacity

Section titled “P0.03 — Database version and droplet capacity”

Who: You · Needs: —

Both environments run self-hosted Postgres in the cluster for now; PlanetScale comes later (decisions log, Ledger database). The databases themselves are installed in P0.08. Here:

  • Version: Postgres 17 for staging, production and CI.
  • Storage: the production database lives on the droplet’s own disk; a separate Volume was declined (2026-11-01). A resize keeps the disk; a rebuild means restoring from the R2 backups.
  • Droplet size: record the droplet’s CPU, memory and disk. Two Postgres instances and two Bifrost releases share it; P0.08 sets resource limits from these numbers.
  • Spec: decisions log, Ledger database, Migrations and the staging database
  • Done when: the version and droplet size are recorded in ../infra/installation-as-built.md.

P0.04 — GitHub repo settings and secrets

Section titled “P0.04 — GitHub repo settings and secrets”

Who: You · Needs: P0.02, P0.03

  • Branch rules: not enforced (GitHub Free, private repo; Pro declined). No direct pushes to main or release/* by rule, stated in the code repo’s CLAUDE.md.
  • Repository secret CLOUDFLARE_API_TOKEN (the deploy token) and variable CLOUDFLARE_ACCOUNT_ID. No database credentials in GitHub: both databases are private, so migrations run on the self-hosted runner with migrator credentials from a Kubernetes secret (P1.06).
  • GHCR: nothing to switch on; workflows request packages: write themselves, and the default workflow permission stays read-only. Create the classic read:packages pull token for K3s and keep it in Bitwarden.
  • Delete any staging branch.
  • Spec: decisions log, Release and branch flow; ../architecture/cicd.md section 8
  • Done when: the secret, the variable and the pull token exist.

Who: You · Needs: —

For staging and production:

  • OAuth apps for Google, GitHub (user:email) and GitLab (read_user). Callbacks: https://app.router.africa/api/auth/callback/<provider> and the staging equivalent.
  • Cloudflare Turnstile site key and secret.
  • Resend: verify the router.africa sending domain (SPF, DKIM and DMARC records in Cloudflare DNS) and pick the from-address.
  • Datadog account.
  • Niobi: request the API credentials, the signing reference implementation, sandbox access if they offer it, and the list of webhook source IPs.
  • Spec: backlog #18 Auth setup; ../infra/secrets-inventory.md
  • Done when: every value is in Bitwarden and has an inventory row. The Resend domain shows as verified.

Who: Agent · Needs: P0.04

Replace ci.yml and niobi-proxy-deploy.yml with three workflows:

  • pr.yml: gates on every PR.
  • deploy-staging.yml: runs on push to main.
  • deploy-production.yml: workflow_dispatch, with a required tag input.

Both deploy workflows run the fixed order: gates → migrate → dashboard-api → dashboard → admin → api → droplet services → smoke. Steps for code that doesn’t exist yet are present and skip cleanly. Remove every staging-branch trigger.

  • Spec: ../architecture/cicd.md sections 1, 2 and 8
  • Done when: a PR runs the gates, a merge to main runs the staging workflow end to end (no-op steps skipped), and running the production workflow without a tag fails fast.

P0.07 — Wrangler environments and Pages projects

Section titled “P0.07 — Wrangler environments and Pages projects”

Who: You + agent · Needs: P0.02

  • Agent: fill the [env.staging] / [env.production] blocks for apps/api and apps/dashboard-api: routes, Queues and R2 bindings, and placeholders for Hyperdrive (P1.04) and VPC bindings (P0.10).
  • You: create the Pages projects router-africa-dashboard and router-africa-admin (wrangler pages project create).
  • Spec: ../architecture/cicd.md sections 1 and 5; decisions log, Admin hosting
  • You: attach the custom domains (P0.02 lists them) for both environments, except admin. and admin-staging., which wait for Access (P8.01).
  • Done when: wrangler deploy --dry-run passes for both Workers in both environments, both Pages projects exist, and the custom domains resolve.

P0.08 — Helm layout; staging Bifrost; Postgres for both environments

Section titled “P0.08 — Helm layout; staging Bifrost; Postgres for both environments”

Who: You + agent · Needs: P0.02, P0.03

  • Agent:
    • Put the validated Bifrost values from installation-as-built.md into infra/gateways/bifrost-1/ as values-production.yaml, plus a values-staging.yaml. Pin the exact image version.
    • Add an infra/niobi-proxy/ chart skeleton.
    • Add infra/postgres/: the CloudNativePG operator and one single-instance cluster per environment (values-staging.yaml, values-production.yaml), Postgres 17 at a pinned image, the superuser password from a Kubernetes secret, and resource requests and limits that fit the droplet (2 vCPU, 4 GB) alongside both Bifrost releases; measure with kubectl top first, and if they don’t fit, resize the droplet (memory first) rather than starve production. Separate from Bifrost’s bundled Postgres.
      • Production: data on the droplet’s disk; continuous WAL archiving plus a daily base backup to router-africa-db-backups-production with the R2 backup token, kept 30 days (point-in-time recovery).
      • Staging: local storage, no backups; its data is disposable and reseeded.
  • You:
    • Install the operator, the staging and production Postgres (namespaces postgres-staging, postgres-production) and a staging Bifrost release, each in its own namespace.
    • Bring the existing production release under the tracked values with a helm upgrade that changes nothing else.
  • Spec: decisions log, Gateway abstraction; ../infra/installation-as-built.md; ../architecture/cicd.md section 5
  • Done when: both namespaces run Bifrost from tracked values, helm diff on production shows no drift, both databases accept connections inside the cluster, and the production database’s first base backup and WAL files are in R2.

P0.09 — Self-hosted runner in the cluster

Section titled “P0.09 — Self-hosted runner in the cluster”

Who: You + agent · Needs: P0.08

Install a GitHub Actions runner inside the cluster: a single runner pod (decided 2026-11-05, decisions log, Self-hosted runner and droplet deploys), which runs every job of a deploy.

  • It picks up jobs only from the two deploy workflows on main (a job-started hook), never from PRs.
  • Its service account can get and patch only the named objects of the shared droplet releases, and no Secrets (cicd.md section 1).
  • Spec: ../architecture/cicd.md section 1, Reaching the cluster
  • Done when: a test job in deploy-staging.yml runs helm list on the runner, and the runner’s service account is refused access to any other namespace.

P0.10 — Tunnel, gateway route-split proxy, Workers VPC Services

Section titled “P0.10 — Tunnel, gateway route-split proxy, Workers VPC Services”

Who: You + agent · Needs: P0.08

  • Tunnel: run cloudflared in the cluster (2 replicas, outbound only).
  • Route-split proxy: Traefik on internal entrypoints, with two Kubernetes Services per environment:
    • one exposing only Bifrost’s inference routes
    • one exposing only the allow-listed management routes and methods: create/update/delete a virtual key, list models, read logs. Start from the documented paths; P0.13 confirms them.
  • Workers VPC Services per environment: gateway-inference, gateway-management, niobi-proxy (the last one waits for P6.01), and postgres (TCP) for Hyperdrive.
  • Bindings: apps/api binds inference only; apps/dashboard-api binds management and niobi-proxy.
  • Spec: decisions log, Private service access, Gateway management route allow-list; ../architecture/network-security-map.md (A1, C1)
  • Done when: both bindings resolve from a deployed staging Worker, and a management path called through the inference Service is refused.

P0.11 — A provider key on staging Bifrost

Section titled “P0.11 — A provider key on staging Bifrost”

Who: You · Needs: P0.08

Add one provider key, with a low spend limit at the provider, to staging Bifrost through its dashboard. Choose a cheap model. Production provider keys wait for phase 9.

Who: Agent · Needs: P0.06

Add to pr.yml:

  • a secret scan (e.g. gitleaks)
  • a lint rule that forbids logging header objects
  • dependency pinning for the auth stack, with an automated update PR
  • Turborepo caching
  • Spec: ../architecture/cicd.md sections 2 and 8; ../architecture/api-key-security.md section 6
  • Done when: a PR that adds a fake key or logs c.req.header() fails.

P0.13 — Verify Bifrost and the private path

Section titled “P0.13 — Verify Bifrost and the private path”

Who: Agent · Needs: P0.10, P0.11

Run every item in backlog #18 Verify against the running Bifrost instance and Verify for the private network path against staging. In particular:

  • x-request-id becomes the log id
  • GET /api/logs parameters, and whether log rows carry the virtual key id
  • the model-listing endpoint and its pricing fields (the input for phase 2)
  • the virtual key fields, and whether the key’s value is returned only at creation
  • the exact management paths (finalises the allow-list in P0.10)
  • whether Anthropic-format /v1/messages and /v1/responses work
  • whether SSE streams arrive unbuffered through the VPC binding, and the latency it adds
  • that Hyperdrive connects to the staging Postgres through its Workers VPC Service (if it can’t, fall back to a Tunnel hostname behind a Cloudflare Access service token, as Hyperdrive documents for private databases)

Write the results to ../infra/bifrost-verification.md. Update the backlog checkboxes and any spec a result contradicts.

  • Spec: backlog #18; ../product/api-surface.md section 6
  • Done when: every item has a recorded result, and both /messages and /responses ship at launch (decided 2026-11-07); record whether each works end to end in api-surface.md, and if one fails verification, the website copy changes instead.

Who: Agent · Needs: P0.06, P0.07, P0.10

Deploy the scaffold apps/api and apps/dashboard-api to staging through the pipeline. Add a temporary route that calls Bifrost’s /health through the inference binding.

  • Done when: https://api-staging.router.africa/health responds, the temporary route returns Bifrost’s health through the binding, and no public Bifrost hostname is used. Then remove the temporary route.