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.
P0.02 — Cloudflare resources
Section titled “P0.02 — Cloudflare resources”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., notstaging.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.andapi-staging.:apps/apiapp.andapp-staging.: the dashboard, withapps/dashboard-apion/api/*admin.andadmin-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-stagingandrouter-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-productiononly. Keep its S3 access key and secret; the production database uses them (P0.08).
- deploy token: edit on Workers Scripts, Workers Routes (zone
Do not connect Workers Builds or the Pages Git integration.
- Spec:
../architecture/cicd.mdsection 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
mainorrelease/*by rule, stated in the code repo’sCLAUDE.md. - Repository secret
CLOUDFLARE_API_TOKEN(the deploy token) and variableCLOUDFLARE_ACCOUNT_ID. No database credentials in GitHub: both databases are private, so migrations run on the self-hosted runner withmigratorcredentials from a Kubernetes secret (P1.06). - GHCR: nothing to switch on; workflows request
packages: writethemselves, and the default workflow permission stays read-only. Create the classicread:packagespull token for K3s and keep it in Bitwarden. - Delete any
stagingbranch. - Spec: decisions log, Release and branch flow;
../architecture/cicd.mdsection 8 - Done when: the secret, the variable and the pull token exist.
P0.05 — Third-party accounts
Section titled “P0.05 — Third-party accounts”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.africasending 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.
P0.06 — The single pipeline (workflows)
Section titled “P0.06 — The single pipeline (workflows)”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 tomain.deploy-production.yml:workflow_dispatch, with a requiredtaginput.
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.mdsections 1, 2 and 8 - Done when: a PR runs the gates, a merge to
mainruns 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 forapps/apiandapps/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-dashboardandrouter-africa-admin(wrangler pages project create). - Spec:
../architecture/cicd.mdsections 1 and 5; decisions log, Admin hosting - You: attach the custom domains (P0.02 lists them) for both environments, except
admin.andadmin-staging., which wait for Access (P8.01). - Done when:
wrangler deploy --dry-runpasses 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.mdintoinfra/gateways/bifrost-1/asvalues-production.yaml, plus avalues-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 withkubectl topfirst, 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-productionwith the R2 backup token, kept 30 days (point-in-time recovery). - Staging: local storage, no backups; its data is disposable and reseeded.
- Production: data on the droplet’s disk; continuous WAL archiving plus a daily base backup to
- Put the validated Bifrost values from
- 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 upgradethat changes nothing else.
- Install the operator, the staging and production Postgres (namespaces
- Spec: decisions log, Gateway abstraction;
../infra/installation-as-built.md;../architecture/cicd.mdsection 5 - Done when: both namespaces run Bifrost from tracked values,
helm diffon 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.mdsection 1). - Spec:
../architecture/cicd.mdsection 1, Reaching the cluster - Done when: a test job in
deploy-staging.ymlrunshelm liston 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
cloudflaredin 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), andpostgres(TCP) for Hyperdrive. - Bindings:
apps/apibinds inference only;apps/dashboard-apibinds management andniobi-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.
- Spec:
../infra/installation-as-built.mdremaining work, item 1 - Done when: the staging Bifrost lists at least one model with pricing.
P0.12 — Code-quality gates in the repo
Section titled “P0.12 — Code-quality gates in the repo”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.mdsections 2 and 8;../architecture/api-key-security.mdsection 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-idbecomes the log idGET /api/logsparameters, 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/messagesand/v1/responseswork - 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.mdsection 6 - Done when: every item has a recorded result, and both
/messagesand/responsesship at launch (decided 2026-11-07); record whether each works end to end inapi-surface.md, and if one fails verification, the website copy changes instead.
P0.14 — M0: staging smoke
Section titled “P0.14 — M0: staging smoke”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/healthresponds, the temporary route returns Bifrost’s health through the binding, and no public Bifrost hostname is used. Then remove the temporary route.