@builtbyfriends/bwf 0.0.0-stage → 1.9.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS_TEMPLATE.md +4 -0
- package/LICENSE +22 -0
- package/README.md +48 -2
- package/dist/account-cmd-Cj0I2_bJ.mjs +45 -0
- package/dist/agents-BLiMq9E1.mjs +113 -0
- package/dist/application-analysis-C9Ck2Yeg.mjs +1498 -0
- package/dist/application-routing-DbR-W5lG.mjs +25 -0
- package/dist/atomic-write-DA6eD1Kp.mjs +17 -0
- package/dist/auth-BKsUmWbT.d.mts +77 -0
- package/dist/auth-DkvoW5hB.mjs +33 -0
- package/dist/auth-aKyIWkdS.mjs +1 -0
- package/dist/auth-client-6-Ft9i9T.d.mts +5 -0
- package/dist/auth-client-DwCdwKbw.mjs +5 -0
- package/dist/auth-client-react-CJdeErvM.mjs +5 -0
- package/dist/auth-client-react-DvQLe5Zb.d.mts +5 -0
- package/dist/auth-link-D-DddkCQ.mjs +26 -0
- package/dist/auth-migrations-DDeifS3v.mjs +206 -0
- package/dist/auth-router-tWzIwf8f.mjs +66 -0
- package/dist/auth-xnkmpZUl.mjs +311 -0
- package/dist/base64-ikl9yBy3.mjs +15 -0
- package/dist/better-auth-shared-Br6TNaYJ.mjs +473 -0
- package/dist/better-auth-shared-CsBNvPOU.d.mts +56 -0
- package/dist/build-cmd-BnZezraT.mjs +153 -0
- package/dist/build-output-dir-Clj_unKN.mjs +402 -0
- package/dist/cancel-deploy-DKAj5U1Z.mjs +57 -0
- package/dist/cf-access-Bhz9wX6p.mjs +131 -0
- package/dist/cf-access-CUP5L08W.mjs +67 -0
- package/dist/cf-build-output-DA6uJomQ.mjs +1 -0
- package/dist/cf-build-output-DNQTwMNU.mjs +438 -0
- package/dist/cf-command-values-2kOtxMo1.mjs +26 -0
- package/dist/cf-config-migrate-COOCi4Ge.mjs +330 -0
- package/dist/cf-worker-settings-CIh4t_yG.mjs +41 -0
- package/dist/cli/cli.d.mts +1 -0
- package/dist/cli/cli.mjs +88 -0
- package/dist/cli/cloudflare-operation-process.d.mts +1 -0
- package/dist/cli/cloudflare-operation-process.mjs +1284 -0
- package/dist/cli/env-schema-probe.d.mts +43 -0
- package/dist/cli/env-schema-probe.mjs +165 -0
- package/dist/cli-main-HeXRQml6.mjs +1846 -0
- package/dist/client-D3D5RM5h.mjs +940 -0
- package/dist/client-VF2Nzc7Z.mjs +1 -0
- package/dist/cloudflare-auth-jb-1e43r.mjs +152 -0
- package/dist/cloudflare-cmd-B62t8Fm-.mjs +59 -0
- package/dist/cloudflare-config-i8yanry0.mjs +186 -0
- package/dist/cloudflare-connect-x7IsYghw.mjs +55 -0
- package/dist/cloudflare-operations-BeK7bhnP.mjs +627 -0
- package/dist/cloudflare-operations-C3Uu0Emj.mjs +1 -0
- package/dist/cloudflare-process-Cc6oiJqk.mjs +309 -0
- package/dist/cloudflare-user-output-CqONaAbP.mjs +19 -0
- package/dist/collect-8i0wU63d.mjs +1 -0
- package/dist/collect-C6Blu9yw.mjs +48 -0
- package/dist/config-CN_RFRkS.mjs +86 -0
- package/dist/config-D5G-Tx6o.mjs +1 -0
- package/dist/config-DOaFIK3w.mjs +88 -0
- package/dist/config-entry.d.mts +202 -0
- package/dist/config-entry.mjs +6 -0
- package/dist/config-tNx0HlFv.mjs +516 -0
- package/dist/connect-hLPNppu3.mjs +84 -0
- package/dist/create-project-B35ux-LA.mjs +126 -0
- package/dist/create-project-tJ1KwNss.mjs +1 -0
- package/dist/database-provider-DkZo4VwN.mjs +5 -0
- package/dist/database-provider.d.mts +25 -0
- package/dist/database-provider.mjs +1 -0
- package/dist/db-BH_md90k.mjs +1735 -0
- package/dist/delete-BSKI7V23.mjs +65 -0
- package/dist/deploy-C8KHBNsh.mjs +6512 -0
- package/dist/deploy-DCZBr7Ey.mjs +2 -0
- package/dist/deploy.d.mts +31 -0
- package/dist/deploy.mjs +118 -0
- package/dist/dev-inbox-I0nqTCdf.mjs +216 -0
- package/dist/discover-DJPmQcL5.mjs +36 -0
- package/dist/discover-EVuydEoM.mjs +1 -0
- package/dist/dist-B6eN80gc.mjs +1612 -0
- package/dist/dist-Cp4b1_T9.mjs +1 -0
- package/dist/dist-DMYe8CZJ.mjs +48 -0
- package/dist/dist-STQXl8ck.mjs +1878 -0
- package/dist/domain-C4ZhEiFG.mjs +149 -0
- package/dist/dotenv-4NdUCXbB.mjs +156 -0
- package/dist/drizzle-DqVFXtlc.mjs +306 -0
- package/dist/drizzle-Ds5P0n-S.mjs +1 -0
- package/dist/edge.d.mts +2 -0
- package/dist/edge.mjs +1 -0
- package/dist/email-B3TWga7x.mjs +742 -0
- package/dist/email-C_ATvNIG.mjs +2865 -0
- package/dist/email-cloudflare-DuAc9zny.mjs +854 -0
- package/dist/email-protocol-CZ0bAkI8.mjs +81 -0
- package/dist/env-CTAo8ifZ.mjs +73 -0
- package/dist/env-DUyTzroe.mjs +88 -0
- package/dist/env-Dl4Wggec.mjs +71 -0
- package/dist/env-helpers-BX0APszT.mjs +135 -0
- package/dist/env-helpers-U56xuFgL.d.mts +20 -0
- package/dist/env-mask-BsHxq3R8.mjs +46 -0
- package/dist/env-public-Cw_xPi1D.d.mts +119 -0
- package/dist/env-raw-Bo6TtrHU.mjs +41 -0
- package/dist/env-types-Bg-dTh8u.mjs +56 -0
- package/dist/env-validation-BufZConV.mjs +488 -0
- package/dist/env-validation-DPqDo4DU.mjs +1 -0
- package/dist/fetch-CBgyyhzm.d.mts +87 -0
- package/dist/fetch-error-DmlRM6e4.mjs +264 -0
- package/dist/fetch-stream-2GUN3YN1.mjs +102 -0
- package/dist/fetch-stream-bUXynOyZ.d.mts +32 -0
- package/dist/fetch-tpPiSK10.mjs +25 -0
- package/dist/gen-dc13IRXh.mjs +509 -0
- package/dist/gen-kQqhFyOP.mjs +1 -0
- package/dist/generate-BgtlYpKg.mjs +1 -0
- package/dist/generate-Da9mWKzU.mjs +80 -0
- package/dist/generated-wrangler-config-CoDaaFsA.mjs +17 -0
- package/dist/git-metadata-Cukp5kV5.mjs +82 -0
- package/dist/github-cmd-DT5Onu6E.mjs +690 -0
- package/dist/handler-CJ7DiiRF.mjs +161 -0
- package/dist/handler-CVsIfRv7.d.mts +279 -0
- package/dist/help-Bpv6Qeqn.mjs +1946 -0
- package/dist/help-CfZ4Bsw5.mjs +1 -0
- package/dist/inbound-CqubE-9T.d.mts +311 -0
- package/dist/inbound-lHugZPuK.mjs +509 -0
- package/dist/index.d.mts +64 -0
- package/dist/index.mjs +4163 -0
- package/dist/info-CLQoCenb.mjs +109 -0
- package/dist/init-DRUR0j8C.mjs +2486 -0
- package/dist/limits-CMmYT2l8.d.mts +16 -0
- package/dist/limits-D27Lp6FP.mjs +46 -0
- package/dist/link-DinwJnon.mjs +52 -0
- package/dist/list-B84t4BhW.mjs +130 -0
- package/dist/live-Dui0-aj_.d.mts +105 -0
- package/dist/live-saC8barp.mjs +410 -0
- package/dist/load-user-env-g0ahkZcj.mjs +34 -0
- package/dist/local-d1-C3EeOV7-.mjs +103 -0
- package/dist/log-JDnPc0cF.mjs +23 -0
- package/dist/login-Bl5lH8nH.mjs +87 -0
- package/dist/login-DoI7AsbY.mjs +1 -0
- package/dist/logs-CaT2N2f7.mjs +129 -0
- package/dist/migrate-CbGscX-V.mjs +125 -0
- package/dist/migrate-Ce3JKLVs.mjs +1 -0
- package/dist/migration-handler-22qiuWPq.mjs +469 -0
- package/dist/migration-handler-Bb2BJh6g.d.mts +38 -0
- package/dist/mime-BMUN_QKG.mjs +1004 -0
- package/dist/mysql-migration-sql-CNuBSqdx.mjs +239 -0
- package/dist/neon-CJzQSycr.mjs +52 -0
- package/dist/node-tfv-3v0V.mjs +64 -0
- package/dist/operator-ai-logging-Ay7M4KWw.mjs +121 -0
- package/dist/operator-args-BFg32YyY.mjs +722 -0
- package/dist/operator-auth-DdYZYEkO.mjs +47 -0
- package/dist/operator-client-DBujdELO.mjs +82 -0
- package/dist/operator-cmd-C73WWJBl.mjs +443 -0
- package/dist/operator-cmd-CdZytuAF.mjs +1 -0
- package/dist/output-Bb34lF0w.mjs +173 -0
- package/dist/output-CVolXKC1.mjs +1 -0
- package/dist/package-DO4d3Qz5.mjs +1444 -0
- package/dist/package-json-DvS6IFRv.mjs +43 -0
- package/dist/pg-DoyPxa_X.mjs +15 -0
- package/dist/picocolors-D1NxSLw-.mjs +71 -0
- package/dist/plan-BHNt1QhK.mjs +1 -0
- package/dist/plan-DX4_-OM5.mjs +58 -0
- package/dist/platform-args-NI_vfWvD.mjs +538 -0
- package/dist/platform-args-ZC1-A1N9.mjs +1 -0
- package/dist/platform-auth-config-d-lY5-aY.mjs +371 -0
- package/dist/platform-auth-protection-Dhw7lUCk.mjs +231 -0
- package/dist/platform-auth-recovery-DaCc0tlx.mjs +309 -0
- package/dist/platform-cmd-5Ry-C9im.mjs +193 -0
- package/dist/platform-cmd-5oZq91lI.mjs +1 -0
- package/dist/platform-discovery-Bxg9aZXU.mjs +40 -0
- package/dist/platform-domain-DLVdGvGG.mjs +256 -0
- package/dist/platform-lifecycle-CUgjipXO.mjs +1 -0
- package/dist/platform-lifecycle-fRt5VMls.mjs +8928 -0
- package/dist/platform-management-5hEsRfR2.mjs +1 -0
- package/dist/platform-management-Djh1hzLP.mjs +1607 -0
- package/dist/platform-plans-config-CkbUKFpm.mjs +447 -0
- package/dist/platform-recovery-Cghx7FCR.mjs +96 -0
- package/dist/platform-registry-x1m9HBxf.mjs +450 -0
- package/dist/platform-runtime-logs-kkoiYFpF.mjs +72 -0
- package/dist/platform-setup-SfwCwnZg.mjs +306 -0
- package/dist/prepare-B9mB47T5.mjs +84 -0
- package/dist/prepare-DNIq07so.mjs +13 -0
- package/dist/prepare-LHkyJqxi.mjs +1 -0
- package/dist/project-CC7eN00D.mjs +141 -0
- package/dist/project-DcSd4BeI.mjs +1 -0
- package/dist/project-cmd-DTF19-fC.mjs +109 -0
- package/dist/project-paths-iXHKRTTQ.mjs +159 -0
- package/dist/project-slug-BUy0lmyR.mjs +1 -0
- package/dist/project-slug-CO6ci9XG.mjs +7 -0
- package/dist/project-team-CvdLhDF2.mjs +129 -0
- package/dist/project-token-CwZdUEGu.mjs +70 -0
- package/dist/project-tsconfig-P9X952KG.mjs +98 -0
- package/dist/project-zero-trust-CKDoPdN1.mjs +64 -0
- package/dist/providers-Cd3c7wi0.mjs +64 -0
- package/dist/providers-Df69hb_X.d.mts +5 -0
- package/dist/provision-DGlFJ3T9.mjs +1 -0
- package/dist/provision-mYVLuQiy.mjs +1814 -0
- package/dist/queues-Bc3FsBQT.d.mts +5 -0
- package/dist/r2-conditions-DSLmkiR5.mjs +60 -0
- package/dist/requests-DNhfyF3l.mjs +52 -0
- package/dist/resolve-project-BCsAMDRA.mjs +47 -0
- package/dist/resolve-project-DhU9_lIo.mjs +1 -0
- package/dist/resource-name-DlJ9QXzg.mjs +10 -0
- package/dist/response-HmNjB30w.mjs +29 -0
- package/dist/rollback-BvCHol52.mjs +150 -0
- package/dist/rolldown-runtime-uD8oG6U2.mjs +24 -0
- package/dist/route-types-CRWhr93D.mjs +592 -0
- package/dist/route-url-BIDZT78M.mjs +58 -0
- package/dist/route-url-Bla3Upsy.d.mts +42 -0
- package/dist/routes-stub.d.mts +24 -0
- package/dist/routes-stub.mjs +1 -0
- package/dist/routing-assets-CSheDWWM.mjs +54 -0
- package/dist/rpc-DcByS_q0.d.mts +39 -0
- package/dist/rpc-DtxIN9Tv.mjs +19 -0
- package/dist/runner-CPerdjIl.mjs +163 -0
- package/dist/runner-CUNtS5x7.mjs +1 -0
- package/dist/runner-mysql-7aA5hGoM.mjs +145 -0
- package/dist/runner-mysql-DrMKw203.mjs +1 -0
- package/dist/runner-pg-2pjltt0t.mjs +1 -0
- package/dist/runner-pg-mYc75KfH.mjs +61 -0
- package/dist/runtime/ai.d.mts +50 -0
- package/dist/runtime/ai.mjs +455 -0
- package/dist/runtime/auth-client-react.d.mts +2 -0
- package/dist/runtime/auth-client-react.mjs +1 -0
- package/dist/runtime/auth-client.d.mts +2 -0
- package/dist/runtime/auth-client.mjs +1 -0
- package/dist/runtime/auth.d.mts +2 -0
- package/dist/runtime/auth.mjs +1 -0
- package/dist/runtime/better-auth-mysql.d.mts +5 -0
- package/dist/runtime/better-auth-mysql.mjs +21 -0
- package/dist/runtime/better-auth-pg.d.mts +5 -0
- package/dist/runtime/better-auth-pg.mjs +21 -0
- package/dist/runtime/better-auth.d.mts +6 -0
- package/dist/runtime/better-auth.mjs +22 -0
- package/dist/runtime/client-react.d.mts +5 -0
- package/dist/runtime/client-react.mjs +5 -0
- package/dist/runtime/client.d.mts +5 -0
- package/dist/runtime/client.mjs +5 -0
- package/dist/runtime/db-mysql.d.mts +2 -0
- package/dist/runtime/db-mysql.mjs +1 -0
- package/dist/runtime/db-pg.d.mts +2 -0
- package/dist/runtime/db-pg.mjs +1 -0
- package/dist/runtime/db.d.mts +17 -0
- package/dist/runtime/db.mjs +36 -0
- package/dist/runtime/drizzle-arktype.d.mts +1 -0
- package/dist/runtime/drizzle-arktype.mjs +2 -0
- package/dist/runtime/drizzle-valibot.d.mts +1 -0
- package/dist/runtime/drizzle-valibot.mjs +2 -0
- package/dist/runtime/drizzle-zod.d.mts +1 -0
- package/dist/runtime/drizzle-zod.mjs +2 -0
- package/dist/runtime/durable.d.mts +64 -0
- package/dist/runtime/durable.mjs +165 -0
- package/dist/runtime/email/testing.d.mts +108 -0
- package/dist/runtime/email/testing.mjs +268 -0
- package/dist/runtime/email-protocol.d.mts +25 -0
- package/dist/runtime/email-protocol.mjs +1 -0
- package/dist/runtime/email.d.mts +26 -0
- package/dist/runtime/email.mjs +524 -0
- package/dist/runtime/env-public-client.d.mts +19 -0
- package/dist/runtime/env-public-client.mjs +55 -0
- package/dist/runtime/env-public.d.mts +4 -0
- package/dist/runtime/env-public.mjs +277 -0
- package/dist/runtime/env.d.mts +12 -0
- package/dist/runtime/env.mjs +1 -0
- package/dist/runtime/fetch-server.d.mts +6 -0
- package/dist/runtime/fetch-server.mjs +29 -0
- package/dist/runtime/fetch-stream.d.mts +3 -0
- package/dist/runtime/fetch-stream.mjs +3 -0
- package/dist/runtime/fetch.d.mts +2 -0
- package/dist/runtime/fetch.mjs +3 -0
- package/dist/runtime/handler.d.mts +3 -0
- package/dist/runtime/handler.mjs +1 -0
- package/dist/runtime/kv.d.mts +45 -0
- package/dist/runtime/kv.mjs +103 -0
- package/dist/runtime/limits.d.mts +2 -0
- package/dist/runtime/limits.mjs +1 -0
- package/dist/runtime/live-client.d.mts +40 -0
- package/dist/runtime/live-client.mjs +282 -0
- package/dist/runtime/live-server.d.mts +11 -0
- package/dist/runtime/live-server.mjs +419 -0
- package/dist/runtime/live.d.mts +3 -0
- package/dist/runtime/live.mjs +1 -0
- package/dist/runtime/log.d.mts +24 -0
- package/dist/runtime/log.mjs +57 -0
- package/dist/runtime/migration-handler-mysql.d.mts +2 -0
- package/dist/runtime/migration-handler-mysql.mjs +111 -0
- package/dist/runtime/migration-handler-pg.d.mts +2 -0
- package/dist/runtime/migration-handler-pg.mjs +94 -0
- package/dist/runtime/migration-handler.d.mts +2 -0
- package/dist/runtime/migration-handler.mjs +1 -0
- package/dist/runtime/procedure.d.mts +27 -0
- package/dist/runtime/procedure.mjs +36 -0
- package/dist/runtime/procedures.d.mts +24 -0
- package/dist/runtime/procedures.mjs +56 -0
- package/dist/runtime/queues.d.mts +2 -0
- package/dist/runtime/queues.mjs +8 -0
- package/dist/runtime/remote/binding-handler.d.mts +11 -0
- package/dist/runtime/remote/binding-handler.mjs +227 -0
- package/dist/runtime/remote/index.d.mts +12 -0
- package/dist/runtime/remote/index.mjs +467 -0
- package/dist/runtime/response.d.mts +11 -0
- package/dist/runtime/response.mjs +1 -0
- package/dist/runtime/route-url.d.mts +2 -0
- package/dist/runtime/route-url.mjs +1 -0
- package/dist/runtime/routing.d.mts +53 -0
- package/dist/runtime/routing.mjs +425 -0
- package/dist/runtime/rpc-react.d.mts +16 -0
- package/dist/runtime/rpc-react.mjs +50 -0
- package/dist/runtime/rpc.d.mts +2 -0
- package/dist/runtime/rpc.mjs +1 -0
- package/dist/runtime/sandbox-container.d.mts +3 -0
- package/dist/runtime/sandbox-container.mjs +1 -0
- package/dist/runtime/sandbox.d.mts +5 -0
- package/dist/runtime/sandbox.mjs +196 -0
- package/dist/runtime/schema-d1.d.mts +1 -0
- package/dist/runtime/schema-d1.mjs +2 -0
- package/dist/runtime/schema-mysql.d.mts +1 -0
- package/dist/runtime/schema-mysql.mjs +2 -0
- package/dist/runtime/schema-pg.d.mts +1 -0
- package/dist/runtime/schema-pg.mjs +2 -0
- package/dist/runtime/seed.d.mts +34 -0
- package/dist/runtime/seed.mjs +5 -0
- package/dist/runtime/sse-client.d.mts +31 -0
- package/dist/runtime/sse-client.mjs +42 -0
- package/dist/runtime/sse.d.mts +32 -0
- package/dist/runtime/sse.mjs +1 -0
- package/dist/runtime/storage.d.mts +4 -0
- package/dist/runtime/storage.mjs +13 -0
- package/dist/runtime/validator.d.mts +2 -0
- package/dist/runtime/validator.mjs +1 -0
- package/dist/runtime/ws-server.d.mts +26 -0
- package/dist/runtime/ws-server.mjs +297 -0
- package/dist/runtime/ws.d.mts +2 -0
- package/dist/runtime/ws.mjs +108 -0
- package/dist/sandbox-CWDjoEG2.d.mts +50 -0
- package/dist/sandbox-container-BqamdFCx.d.mts +73 -0
- package/dist/sandbox-container-d1AHLpgn.mjs +291 -0
- package/dist/secret-DCF9RXTc.mjs +146 -0
- package/dist/skills-Dr3AjuBF.mjs +63 -0
- package/dist/sqlite-validation-CLJXXN93.mjs +24 -0
- package/dist/sse-CxR30yMF.mjs +174 -0
- package/dist/standard-schema-CuDawHOC.d.mts +40 -0
- package/dist/static-asset-marker-mWMX2dLa.mjs +38 -0
- package/dist/subcommand-prompt-B9yUo--u.mjs +370 -0
- package/dist/terminal-log-text-DNsWJREL.mjs +31 -0
- package/dist/types-D7-4tBu7.d.mts +1 -0
- package/dist/untrusted-env-lL7RkYiC.mjs +50 -0
- package/dist/validate-B-zsjhiz.mjs +162 -0
- package/dist/validate-DbqGdPPY.mjs +1 -0
- package/dist/validator-8-NZs2Xr.mjs +168 -0
- package/dist/version-metadata-DsSoNsKJ.mjs +23 -0
- package/dist/wrangler-DU784Dkf.mjs +1452 -0
- package/dist/wrangler-Rr9_76DQ.mjs +1 -0
- package/dist/ws-Q_osq9VK.d.mts +137 -0
- package/dist/yarn-pnp-DgWbE7z5.mjs +91 -0
- package/docs/guide/ai.md +273 -0
- package/docs/guide/app-types.md +101 -0
- package/docs/guide/auth.md +255 -0
- package/docs/guide/database/d1.md +86 -0
- package/docs/guide/database/mysql.md +72 -0
- package/docs/guide/database/postgresql.md +94 -0
- package/docs/guide/database.md +454 -0
- package/docs/guide/deployment.md +124 -0
- package/docs/guide/durable-state.md +192 -0
- package/docs/guide/edge/headers.md +47 -0
- package/docs/guide/edge/redirects.md +85 -0
- package/docs/guide/edge/rewrites.md +119 -0
- package/docs/guide/edge/static-assets.md +94 -0
- package/docs/guide/email/domains.md +119 -0
- package/docs/guide/email/receiving.md +142 -0
- package/docs/guide/email/sending.md +262 -0
- package/docs/guide/email.md +23 -0
- package/docs/guide/env-vars.md +115 -0
- package/docs/guide/index.md +37 -0
- package/docs/guide/jobs.md +80 -0
- package/docs/guide/kv.md +100 -0
- package/docs/guide/live.md +181 -0
- package/docs/guide/platform/administration/access.md +165 -0
- package/docs/guide/platform/administration/connected-apps.md +84 -0
- package/docs/guide/platform/administration/email.md +169 -0
- package/docs/guide/platform/administration/operations.md +100 -0
- package/docs/guide/platform/administration/plans.md +156 -0
- package/docs/guide/platform/administration/projects.md +74 -0
- package/docs/guide/platform/administration/zero-trust.md +205 -0
- package/docs/guide/platform/development/local.md +122 -0
- package/docs/guide/platform/development/runtime.md +115 -0
- package/docs/guide/platform/development/schema-ci.md +44 -0
- package/docs/guide/platform/installation/ci.md +62 -0
- package/docs/guide/platform/installation/credentials.md +140 -0
- package/docs/guide/platform/installation/domains.md +120 -0
- package/docs/guide/platform/installation/first-deployment.md +95 -0
- package/docs/guide/platform/installation/maintenance.md +250 -0
- package/docs/guide/platform/installation/prerequisites.md +176 -0
- package/docs/guide/platform/installation/setup.md +300 -0
- package/docs/guide/platform/installation/uninstall.md +110 -0
- package/docs/guide/platform-administration.md +19 -0
- package/docs/guide/platform-development.md +16 -0
- package/docs/guide/procedures.md +48 -0
- package/docs/guide/project-collaboration.md +99 -0
- package/docs/guide/queues.md +149 -0
- package/docs/guide/quickstart.md +129 -0
- package/docs/guide/remote-dev.md +67 -0
- package/docs/guide/sandboxes.md +134 -0
- package/docs/guide/self-hosted-platform.md +45 -0
- package/docs/guide/server-routing.md +283 -0
- package/docs/guide/sse.md +174 -0
- package/docs/guide/storage.md +82 -0
- package/docs/guide/testing.md +64 -0
- package/docs/guide/type-safety.md +270 -0
- package/docs/guide/typed-fetch.md +98 -0
- package/docs/guide/websockets.md +230 -0
- package/docs/index.md +102 -0
- package/docs/integrations/agents.md +38 -0
- package/docs/integrations/cloudflare.md +241 -0
- package/docs/integrations/hono.md +127 -0
- package/docs/reference/api/auth.md +195 -0
- package/docs/reference/api/client.md +90 -0
- package/docs/reference/api/database.md +118 -0
- package/docs/reference/api/deploy.md +63 -0
- package/docs/reference/api/durable.md +47 -0
- package/docs/reference/api/env.md +51 -0
- package/docs/reference/api/handlers.md +189 -0
- package/docs/reference/api/plugin.md +40 -0
- package/docs/reference/api/resources.md +116 -0
- package/docs/reference/api/rewrites.md +111 -0
- package/docs/reference/api/types.md +126 -0
- package/docs/reference/api.md +71 -0
- package/docs/reference/cli/auth.md +87 -0
- package/docs/reference/cli/database.md +159 -0
- package/docs/reference/cli/deploy.md +117 -0
- package/docs/reference/cli/domains.md +42 -0
- package/docs/reference/cli/email.md +145 -0
- package/docs/reference/cli/generate.md +113 -0
- package/docs/reference/cli/github.md +181 -0
- package/docs/reference/cli/platform-config.md +93 -0
- package/docs/reference/cli/platform-email.md +81 -0
- package/docs/reference/cli/platform-installation.md +166 -0
- package/docs/reference/cli/platform-operations.md +90 -0
- package/docs/reference/cli/platform-users.md +159 -0
- package/docs/reference/cli/platform-zero-trust.md +60 -0
- package/docs/reference/cli/platform.md +78 -0
- package/docs/reference/cli/project.md +208 -0
- package/docs/reference/cli/secrets.md +79 -0
- package/docs/reference/cli/setup.md +88 -0
- package/docs/reference/cli.md +115 -0
- package/docs/reference/config.md +478 -0
- package/docs/reference/resource-inference.md +72 -0
- package/docs/reference/structure.md +138 -0
- package/package.json +389 -3
- package/sandbox.Dockerfile +4 -0
- package/schema.json +353 -0
- package/skills/bwf/SKILL.md +100 -0
- package/skills/migrate-vite-cloudflare-to-bwf/SKILL.md +53 -0
- package/templates/assets/bwf.svg +5 -0
- package/templates/assets/icons.svg +49 -0
- package/templates/assets/react.svg +1 -0
- package/templates/assets/stack.svg +35 -0
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: 'Save the credentials an installation asks for, and see which values belong in a password manager or the shell.'
|
|
3
|
+
outline: deep
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Credentials
|
|
7
|
+
|
|
8
|
+
Keep one password-manager entry for this platform. Paste the saved values into the installer when asked; most do not need shell environment variables.
|
|
9
|
+
|
|
10
|
+
| Credential | Created by | Why the platform needs it |
|
|
11
|
+
| -------------------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------- |
|
|
12
|
+
| Management API token | You, in Cloudflare | Lets the CLI create a zone, change DNS, and set up Access. |
|
|
13
|
+
| Runtime API token | You, in Cloudflare | Stored as a Worker secret so the platform can deploy apps after you close your terminal. |
|
|
14
|
+
| PostgreSQL URL | You, with your database provider | Stores platform users, projects, and deployments. |
|
|
15
|
+
| Login provider client ID and secret | You, or bwf for Access login | Signs people in to the platform. |
|
|
16
|
+
| R2 Access Key ID and Secret Access Key | You, in Cloudflare | Lets the platform sign upload links so `bwf deploy` sends static files straight to R2. |
|
|
17
|
+
| Access setup and app-access tokens | You, in Cloudflare | Only with Cloudflare Access: create and manage Access applications. |
|
|
18
|
+
| JWT signing key | bwf, on interactive installs | Signs platform login tokens. |
|
|
19
|
+
| Project encryption key | bwf, on interactive installs | Encrypts app secrets stored by your platform. |
|
|
20
|
+
| Email signing key | bwf, when email is enabled | Signs confirmation links and email requests. |
|
|
21
|
+
|
|
22
|
+
## Cloudflare API Tokens {#runtime-token-permissions}
|
|
23
|
+
|
|
24
|
+
Follow the installer's [token-creation links](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/) to create a runtime token. bwf also asks for a separate management token when it creates a zone, adds wildcard DNS, or configures Access. The links select the permissions and suggest names based on your platform's name.
|
|
25
|
+
|
|
26
|
+
For a domain installation, choose the zone scope in Cloudflare's form:
|
|
27
|
+
|
|
28
|
+
- **Existing zone:** change **All Domains** to **Specified Domains** and select your zone.
|
|
29
|
+
- **New zone:** keep **All Domains** on both tokens. The zone doesn't exist yet, and the runtime token will need cache-purge access to it.
|
|
30
|
+
|
|
31
|
+
Save the tokens in your password manager and paste them into the masked CLI prompts.
|
|
32
|
+
|
|
33
|
+
Browser login can authorize workers.dev setup with the default API hostname. It also works for a domain installation with an existing proxied `*.<application domain>` record. If bwf cannot read the account's Access requirements, it asks for a scoped Access token.
|
|
34
|
+
|
|
35
|
+
Configuring Access requires a management token, including on workers.dev. Protected apps and public apps under Default-Deny also need an ongoing app-management token, which bwf stores encrypted. Skip zone permissions until you add a domain.
|
|
36
|
+
|
|
37
|
+
Browser login does not grant AI Gateway access. Include **Account → AI Gateway → Edit** on the runtime token so bwf can verify and create that resource.
|
|
38
|
+
|
|
39
|
+
The management token lets your CLI install and maintain the platform. The runtime token is stored as a Worker secret so the platform can deploy apps after you close your terminal. They are separate credentials.
|
|
40
|
+
|
|
41
|
+
Compare each token's form with the permission checklist below. The installer saves a management token entered at the prompt in this installation’s encrypted local checkpoint and reuses it on resume. Upgrades, repairs, and other lifecycle maintenance also use that saved management token. During installation, a rejected token can be replaced at the prompt. An explicit `CLOUDFLARE_API_TOKEN` or `CF_API_TOKEN` takes precedence. Keep your password-manager copy for maintenance or another machine; scripts supply it through `CLOUDFLARE_API_TOKEN`.
|
|
42
|
+
|
|
43
|
+
::: details Permissions to select for each token
|
|
44
|
+
|
|
45
|
+
Use the following permissions for the core platform. Cloudflare may label write access as **Edit** or **Write**, depending on the token screen; see its [permission reference](https://developers.cloudflare.com/fundamentals/api/reference/permissions/).
|
|
46
|
+
|
|
47
|
+
| Scope | Permission | Management | Runtime |
|
|
48
|
+
| ------- | ------------------ | ---------- | --------------------------------------- |
|
|
49
|
+
| Account | Account Settings | Read | Read |
|
|
50
|
+
| Account | Workers Scripts | Edit | Edit |
|
|
51
|
+
| Account | Workers Tail | Read | Read |
|
|
52
|
+
| Account | D1 | Edit | Edit |
|
|
53
|
+
| Account | Workers KV Storage | Edit | Edit |
|
|
54
|
+
| Account | Workers R2 Storage | Edit | Edit |
|
|
55
|
+
| Account | Queues | Edit | Edit |
|
|
56
|
+
| Account | Hyperdrive | Write | Write |
|
|
57
|
+
| Account | Account Analytics | Read | Read |
|
|
58
|
+
| Account | AI Gateway | Edit | Edit when installing with browser login |
|
|
59
|
+
| Account | Containers | — | Edit |
|
|
60
|
+
| Account | Cloudchamber | — | Edit |
|
|
61
|
+
| Zone | Zone | Read | — |
|
|
62
|
+
| Zone | DNS | Edit | — |
|
|
63
|
+
| Zone | Workers Routes | Edit | — |
|
|
64
|
+
| Zone | Cache Purge | — | Purge |
|
|
65
|
+
|
|
66
|
+
When bwf configures Access in the installation account, the initial management-token link also selects **Account → Access: Apps and Policies → Edit** and **Account → Access: Organizations, Identity Providers, and Groups → Read**. Protection adds **Account → Access: Service Tokens → Edit**. When the authentication configuration or saved setup selects existing applications, the link requests Read access instead of Edit. These permissions belong to the management token; the runtime token does not need them.
|
|
67
|
+
|
|
68
|
+
The management token also needs **Zone Edit** with authority to create zones if you ask bwf to create the zone. If it already exists, use the selected zone with Zone Read and DNS Edit. Nested application domains additionally need **SSL and Certificates: Read** on the management token. An installation with [project custom domains](/guide/platform/installation/domains#project-custom-domains) needs **SSL and Certificates: Edit** on the runtime token.
|
|
69
|
+
|
|
70
|
+
bwf checks access before provisioning. If it reports a missing permission, update the token's permissions for the selected account or zone and retry.
|
|
71
|
+
|
|
72
|
+
:::
|
|
73
|
+
|
|
74
|
+
## Enable Email {#enable-email}
|
|
75
|
+
|
|
76
|
+
Choose a shared sender domain and its Cloudflare zone ID. The mail zone may differ from the application zone, but it must belong to the platform's Cloudflare account.
|
|
77
|
+
|
|
78
|
+
Before enabling platform email, configure [Cloudflare Email Routing](https://developers.cloudflare.com/email-service/get-started/route-emails/) for the shared sender domain. For a subdomain, add it under **Email Routing → Settings → Subdomains**. Let Cloudflare add the required MX and SPF records, then confirm that the domain's MX records point to Cloudflare.
|
|
79
|
+
|
|
80
|
+
Enabling email lets administrators [register email domains for projects](/guide/platform/administration/email#registering-email-domains-for-projects) and lets projects register destination addresses through the runtime token. The runtime token needs these permissions:
|
|
81
|
+
|
|
82
|
+
| Scope | Permission | Access |
|
|
83
|
+
| ------- | ----------------------- | ------ |
|
|
84
|
+
| Account | Email Routing Addresses | Edit |
|
|
85
|
+
| Account | Email Sending | Edit |
|
|
86
|
+
| Zone | Zone | Read |
|
|
87
|
+
| Zone | Zone Settings | Edit |
|
|
88
|
+
| Zone | Email Routing Rules | Edit |
|
|
89
|
+
|
|
90
|
+
The zone permissions must include each zone that will carry mail, including the mail zone. Email Sending onboarding for arbitrary recipients needs Workers Paid.
|
|
91
|
+
|
|
92
|
+
For a new installation, set `NOSAM_EMAIL_SENDER_DOMAIN` and `NOSAM_EMAIL_SHARED_ZONE_ID` before `bwf platform install`. The runtime-token link then preselects these permissions.
|
|
93
|
+
|
|
94
|
+
For an existing installation, edit its runtime token's permissions in Cloudflare, or supply a replacement with `NOSAM_PLATFORM_RUNTIME_CLOUDFLARE_API_TOKEN`. Then run:
|
|
95
|
+
|
|
96
|
+
```sh
|
|
97
|
+
NOSAM_EMAIL_SENDER_DOMAIN=mail.example.com \
|
|
98
|
+
NOSAM_EMAIL_SHARED_ZONE_ID=your-zone-id \
|
|
99
|
+
bwf platform upgrade your-installation-id
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
bwf saves this domain and zone for later upgrades. Choose them for the lifetime of the installation.
|
|
103
|
+
|
|
104
|
+
If setup reports a missing permission, add it to the runtime token and rerun the command. Select all permissions in the table, including Edit access and Email Sending.
|
|
105
|
+
|
|
106
|
+
When maintaining the platform from another machine, set `NOSAM_PLATFORM_RUNTIME_CLOUDFLARE_API_TOKEN` to the current runtime token so the CLI checks its permissions.
|
|
107
|
+
|
|
108
|
+
The installer configures the email gateway and shared mail route. If setup fails, fix the reported permission, DNS, or routing problem and rerun the command. Resume a fresh installation with `bwf platform install --resume --name <installation-id>`.
|
|
109
|
+
|
|
110
|
+
## R2 Upload Credentials
|
|
111
|
+
|
|
112
|
+
`bwf deploy --platform void` uploads your app's static files straight to R2 instead of through the platform API. The API signs short-lived upload links for them with an R2 key pair.
|
|
113
|
+
|
|
114
|
+
The installer opens the **R2 token creation** form with a token name based on your platform's display name, **Object Read & Write**, and **Apply to all buckets in this account (including newly created buckets)** preselected. Review the settings and create an account token, or a user token if your role requires it. Save its **Access Key ID** and **Secret Access Key** in your password manager, then paste both into the installer. These differ from the management and runtime API tokens. See [R2’s token instructions](https://developers.cloudflare.com/r2/api/tokens/).
|
|
115
|
+
|
|
116
|
+
## Signing and Encryption Keys {#signing-and-encryption-keys}
|
|
117
|
+
|
|
118
|
+
The **JWT signing key** signs platform login tokens. The **Project encryption key** encrypts app secrets stored by your platform. An interactive install generates both and keeps them in this machine's encrypted recovery data. Lifecycle commands on this machine read them from there.
|
|
119
|
+
|
|
120
|
+
To keep your own copy, for example to repair the platform from CI or another machine, create both keys before installing and set `NOSAM_PLATFORM_JWT_SECRET` and `NOSAM_PLATFORM_PROJECT_SECRET_KEY`. Non-interactive installs must set both. Generate a separate key for each by running this command twice:
|
|
121
|
+
|
|
122
|
+
```sh
|
|
123
|
+
openssl rand -base64 32
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
Save each result in your password manager. The command generates 32 random bytes encoded as base64, suitable for either field. Keep the two original keys for recovery; do not regenerate them when resuming or upgrading.
|
|
127
|
+
|
|
128
|
+
::: details Generate the keys without printing them to your terminal
|
|
129
|
+
|
|
130
|
+
On macOS, this copies a suitable random value to the clipboard:
|
|
131
|
+
|
|
132
|
+
```sh
|
|
133
|
+
openssl rand -base64 32 | pbcopy
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
Paste it into your password manager as **JWT signing key**. Run the command again and save the second value as **Project encryption key**. On PowerShell, use `Set-Clipboard` instead of `pbcopy`. If OpenSSL is unavailable, use your secret manager's secure generator for 32 random bytes in base64, or `node -e 'process.stdout.write(require("node:crypto").randomBytes(32).toString("base64"))'`.
|
|
137
|
+
|
|
138
|
+
:::
|
|
139
|
+
|
|
140
|
+
When email is enabled, bwf also creates an independent **Email signing key** for confirmation links and service-to-service email requests. The installer keeps it in encrypted recovery state. Set `NOSAM_PLATFORM_EMAIL_SIGNING_SECRET` to a separate value of at least 32 random bytes when you need an externally custodied copy, including a headless installation whose local recovery files will not persist.
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: 'Add an application domain to an installed platform, including its DNS, routing, and HTTPS certificate.'
|
|
3
|
+
outline: deep
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Domains and Resources
|
|
7
|
+
|
|
8
|
+
## Adding a Domain
|
|
9
|
+
|
|
10
|
+
When your domain is ready, run:
|
|
11
|
+
|
|
12
|
+
```sh
|
|
13
|
+
bwf platform domain set example.app --plan
|
|
14
|
+
bwf platform domain set example.app
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
The command selects your installed platform (or offers a picker), finds or creates its zone, sets up DNS and routing, and verifies HTTPS before publishing the new application URLs. Set the management token as described in [installation setup](/guide/platform/installation/setup) when creating DNS or a zone. Grant the existing runtime token **Cache Purge: Purge** on the new zone; bwf checks that permission through the running platform without asking you to paste its token again.
|
|
18
|
+
|
|
19
|
+
If nameservers, certificates, or project Zero Trust protection are pending, follow the printed guidance and rerun the same command. bwf preserves each project's public or protected setting before making the new URLs available. Your workers.dev app URLs continue working during and after setup. Projects, deployments, secrets, and the platform API URL stay the same, so developers do not reconnect and configured login callbacks do not change. DNS and configuration changes may take time to propagate.
|
|
20
|
+
|
|
21
|
+
Use `--installation <id>` to select an installation explicitly, `--zone example.com` for an app domain such as `apps.example.com`, or `--dedicated-zone` for catch-all routing on a dedicated zone. Nested domains still need the wildcard certificate described below. This command adds the first domain; replacing an existing application domain is not currently supported. It uses the installed runtime and does not require `--runtime` or an app redeploy.
|
|
22
|
+
|
|
23
|
+
Choose an application domain whose wildcard leaves existing Worker Custom Domains reachable. Existing more-specific routes covering all requests can preserve those hostnames. If bwf reports a conflict, choose another application domain; for a new installation, you can start with `bwf platform install --workers-dev` and add a suitable domain later.
|
|
24
|
+
|
|
25
|
+
Browser login sessions are specific to each origin. Apps using their own OAuth providers may need to register their new callback URLs. bwf's built-in auth uses the request origin automatically unless the app overrides that configuration.
|
|
26
|
+
|
|
27
|
+
Apps on one application domain can set cookies that the other apps there receive. With a nested domain such as `apps.example.com`, apps can also set cookies for `example.com` and its other subdomains. Apps on `workers.dev` testing URLs can set cookies that every Worker on your account's `workers.dev` subdomain receives. If people outside your team can deploy, use a domain that serves only bwf apps. A platform that serves thousands of independent developers can also apply to list its application domain on the [Public Suffix List](https://github.com/publicsuffix/list/wiki/Guidelines).
|
|
28
|
+
|
|
29
|
+
### What Changes in Testing Mode?
|
|
30
|
+
|
|
31
|
+
In testing mode, each app gets a `workers.dev` URL. These URLs continue working after you add a domain; new apps then use the domain.
|
|
32
|
+
|
|
33
|
+
Testing URLs support WebSockets and SSE, but skip the extra edge response cache. Their forwarding Workers remain for manual cleanup after uninstall. Platform disablement and project suspension still block their traffic.
|
|
34
|
+
|
|
35
|
+
## Other Domain Options
|
|
36
|
+
|
|
37
|
+
::: details Custom API hostname
|
|
38
|
+
|
|
39
|
+
Pass `--control-plane-domain platform.example.net` during installation. The hostname must belong to a zone the selected account and management token can manage. Omitting it keeps the API on `workers.dev`.
|
|
40
|
+
|
|
41
|
+
:::
|
|
42
|
+
|
|
43
|
+
### Using a Nested Application Domain
|
|
44
|
+
|
|
45
|
+
::: details Use apps.example.com within an existing company zone
|
|
46
|
+
|
|
47
|
+
An app at `my-app.apps.example.com` needs a certificate for `*.apps.example.com`. Universal SSL for `example.com` only covers first-level hostnames. Configure an active wildcard certificate with [Advanced Certificate Manager](https://developers.cloudflare.com/ssl/edge-certificates/advanced-certificate-manager/), a paid add-on, or use an existing custom wildcard certificate before installation:
|
|
48
|
+
|
|
49
|
+
```sh
|
|
50
|
+
bwf platform install --application-domain apps.example.com --zone example.com --plan
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
The management token needs **SSL and Certificates: Read** (or Edit) on that zone for the certificate check. bwf does not order certificates or enable paid products automatically. Leave `--dedicated-zone` off: that flag is only for installations whose application domain is the entire zone and adds catch-all routes for otherwise unmatched traffic.
|
|
54
|
+
|
|
55
|
+
:::
|
|
56
|
+
|
|
57
|
+
## Project Custom Domains
|
|
58
|
+
|
|
59
|
+
Projects can serve their own domains, such as `www.example.com`, through Cloudflare for SaaS custom hostnames. This needs a dedicated application zone. Turn it on when installing, or later with an upgrade:
|
|
60
|
+
|
|
61
|
+
```sh
|
|
62
|
+
bwf platform install --application-domain example.app --zone example.app --dedicated-zone --custom-domains
|
|
63
|
+
bwf platform upgrade <installation-id> --custom-domains
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
The runtime token needs **SSL and Certificates: Edit** on the application zone. bwf includes it in the runtime token's creation link and checks it before deploying; a token created before custom domains were on needs it added. Before adding the first domain, set up Cloudflare for SaaS on that zone once:
|
|
67
|
+
|
|
68
|
+
1. Create a proxied DNS record for `cname.<application domain>`, for example an `AAAA` record pointing to `100::`.
|
|
69
|
+
2. Open **SSL/TLS > Custom Hostnames**, enable Cloudflare for SaaS, and set `cname.<application domain>` as the fallback origin.
|
|
70
|
+
|
|
71
|
+
A project owner then runs `bwf domain add <hostname>`. bwf prints the CNAME target, `cname.<application domain>`, and the TXT records that prove ownership. Once the records resolve and the certificate is issued, the dedicated zone's catch-all routes send the hostname to the project.
|
|
72
|
+
|
|
73
|
+
## Optional Dashboard
|
|
74
|
+
|
|
75
|
+
The API's `/admin/` pages are included in the core installation. You can deploy
|
|
76
|
+
the optional user dashboard separately and configure its HTTPS origin during
|
|
77
|
+
installation with `--dashboard-url https://dash.example.com`.
|
|
78
|
+
|
|
79
|
+
For an existing installation, preview and apply the configuration with:
|
|
80
|
+
|
|
81
|
+
```sh
|
|
82
|
+
bwf platform repair <installation-id> --dashboard-url https://dash.example.com --plan
|
|
83
|
+
bwf platform repair <installation-id> --dashboard-url https://dash.example.com --yes
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
The origin must contain no credentials, path, query, or fragment. bwf saves it
|
|
87
|
+
for login callbacks and keeps it across upgrades and repairs. The command does
|
|
88
|
+
not create a dashboard Worker or DNS records. Follow the source app’s
|
|
89
|
+
[standalone dashboard preparation](https://github.com/voidzero-dev/void/tree/main/platform/packages/dashboard#standalone-deployment)
|
|
90
|
+
to deploy your own copy with an unused Worker name, your dashboard hostname,
|
|
91
|
+
and the installed API Worker’s service binding. Set its `API_URL` to the public
|
|
92
|
+
API origin, `DASHBOARD_URL` to the dashboard origin, and `SITE_DOMAIN` to the
|
|
93
|
+
installation’s application domain. Omit the option to keep the saved origin.
|
|
94
|
+
The dashboard provides sign-in, linked login methods, and sign-out; use the CLI
|
|
95
|
+
for user project and team management.
|
|
96
|
+
|
|
97
|
+
If Access protects the platform, its application must cover this dashboard
|
|
98
|
+
origin too. Configure the origin when installing protection. To change it on an
|
|
99
|
+
already protected platform, deliberately remove protection through authentication
|
|
100
|
+
configuration, apply the origin, then enable protection again. Choose a separate
|
|
101
|
+
admission rule first if signup depends on the Access gate. Maintenance stops if
|
|
102
|
+
the configured origin is outside the active coverage.
|
|
103
|
+
|
|
104
|
+
## Cloudflare footprint
|
|
105
|
+
|
|
106
|
+
New platform resources use deterministic `void-<installation-name>-<role>` names where Cloudflare allows them, such as `nosam-team-api`. Choose an unused installation name in the account; bwf stops on an unowned name conflict instead of replacing that resource. Existing installations keep their recorded names, including older names with suffixes.
|
|
107
|
+
|
|
108
|
+
| Resource | Count | Purpose |
|
|
109
|
+
| ----------------------------------------- | ------------------------------------: | --------------------------------------------------------------------------------------------- |
|
|
110
|
+
| Workers | 5, plus one per app using workers.dev | API/control plane, proxy, tail ingestion, dispatch, email gateway, and test-origin forwarders |
|
|
111
|
+
| KV namespaces | 3 | Routing, ISR cache, and static asset storage |
|
|
112
|
+
| R2 buckets | 1 | Static and deployment assets |
|
|
113
|
+
| Queues | 3 | Usage events, cron firing, and deployments |
|
|
114
|
+
| Workers for Platforms dispatch namespaces | 1 | User application Workers |
|
|
115
|
+
| Hyperdrive configurations | 1 | External platform PostgreSQL |
|
|
116
|
+
| AI Gateways | 1 | Installation-isolated AI routing and metering |
|
|
117
|
+
| Proxied wildcard DNS records | 0 or 1 | Created only when an application domain is configured |
|
|
118
|
+
| Zones | 0 or 1 | Created only when the requested application zone is absent |
|
|
119
|
+
|
|
120
|
+
The API Worker uses four Durable Object classes for usage, cron scheduling, error monitoring, and concurrency. Worker bindings create the request and log datasets in Analytics Engine, which must be [enabled for the account](/guide/platform/installation/prerequisites#if-cloudflare-rejects-analytics-engine). The core installation doesn't create Container applications, a GitHub App, a dashboard Worker, or build Workers.
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: 'Open the platform URL, connect the CLI, and deploy the first app into the shared Cloudflare account.'
|
|
3
|
+
outline: deep
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# First Deployment
|
|
7
|
+
|
|
8
|
+
Open your platform's API URL in a browser to see its welcome page, CLI connection instructions, and a link to the administrator dashboard. Share this URL with teammates so they can connect to your platform.
|
|
9
|
+
|
|
10
|
+
First verify the new platform and sign in with the administrator login method selected during setup:
|
|
11
|
+
|
|
12
|
+
```sh
|
|
13
|
+
bwf platform status
|
|
14
|
+
bwf platform auth login
|
|
15
|
+
bwf platform system health
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
Administrator login is separate from the credentials used to deploy apps. In a new or unlinked bwf app directory, connect using the installed API URL and deploy your first project:
|
|
19
|
+
|
|
20
|
+
```sh
|
|
21
|
+
bwf connect nosam-company-api.example.workers.dev
|
|
22
|
+
bwf deploy --platform void --project my-first-app
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
`bwf connect` validates the platform and signs you in when needed. Confirm project creation when deploy asks. To use a project that already exists, run `bwf project link` instead. An app already linked to another platform keeps its existing destination; use a fresh app directory for your first test.
|
|
26
|
+
|
|
27
|
+
Once accepted by the platform, a deployment continues independently of the CLI connection. The CLI reconnects automatically after a connection failure. Use `bwf project status` to inspect a deployment after closing the CLI, or `bwf project cancel` to request cancellation.
|
|
28
|
+
|
|
29
|
+
The CLI stores login credentials in your system keychain, separately for each platform URL. With no URL, `bwf connect` offers Cloudflare or a bwf platform; `bwf connect --platform void` offers saved platforms and an option to enter another URL.
|
|
30
|
+
|
|
31
|
+
For CI, create a bounded, project-scoped deploy credential while signed in as
|
|
32
|
+
the project owner:
|
|
33
|
+
|
|
34
|
+
```sh
|
|
35
|
+
bwf project token create --name ci --expires-in 30
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Store the printed `BWF_TOKEN` and `BWF_API_URL` in the CI secret manager, then
|
|
39
|
+
run `bwf connect "$BWF_API_URL" --no-login` before deploying in each fresh CI
|
|
40
|
+
environment. Project files do not replace this connection step. CI cannot answer
|
|
41
|
+
the project prompt, so choose the project before `bwf deploy`: set `BWF_PROJECT`,
|
|
42
|
+
pass `--project <slug>`, or commit `.bwf/project.json` from `bwf project link`.
|
|
43
|
+
New apps ignore `.bwf` in `.gitignore`; to commit the link, replace that line
|
|
44
|
+
with `.bwf/*` and `!.bwf/project.json`. Rotate with `bwf project token renew <id>` and revoke with
|
|
45
|
+
`bwf project token revoke <id>`. A human login token is not a CI credential.
|
|
46
|
+
|
|
47
|
+
If Cloudflare Access protects the platform, Access proof and the project
|
|
48
|
+
credential are both required; the service token does not grant bwf user or
|
|
49
|
+
operator authority. A deploy that uses remote bindings calls
|
|
50
|
+
both the API and proxy, so store `NOSAM_ACCESS_CREDENTIALS` in the CI secret
|
|
51
|
+
manager with entries for both exact HTTPS origins. Include both entries even
|
|
52
|
+
when the same admitted service-token pair is used for both origins:
|
|
53
|
+
|
|
54
|
+
```json
|
|
55
|
+
{
|
|
56
|
+
"https://nosam-company-api.example.workers.dev": {
|
|
57
|
+
"CF_ACCESS_CLIENT_ID": "<service-token client ID>",
|
|
58
|
+
"CF_ACCESS_CLIENT_SECRET": "<service-token client secret>"
|
|
59
|
+
},
|
|
60
|
+
"https://nosam-company-proxy.example.workers.dev": {
|
|
61
|
+
"CF_ACCESS_CLIENT_ID": "<service-token client ID>",
|
|
62
|
+
"CF_ACCESS_CLIENT_SECRET": "<service-token client secret>"
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
`NOSAM_ACCESS_ORIGIN` can scope credentials to one origin only; setting it to
|
|
68
|
+
the API origin does not authorize proxy requests.
|
|
69
|
+
|
|
70
|
+
Use these commands to inspect connections and installations:
|
|
71
|
+
|
|
72
|
+
```sh
|
|
73
|
+
bwf platform list
|
|
74
|
+
bwf platform use [id]
|
|
75
|
+
bwf platform status [id]
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
## Managing Access
|
|
79
|
+
|
|
80
|
+
After installation, sign in as the first administrator. For a teammate who uses GitHub, add their login to the signup allowlist:
|
|
81
|
+
|
|
82
|
+
```sh
|
|
83
|
+
bwf platform auth login
|
|
84
|
+
bwf platform signup allow github teammate
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
bwf shows the proposed access change and asks you to confirm it. Once approved, `teammate` can connect to the platform's API URL and sign in with GitHub.
|
|
88
|
+
|
|
89
|
+
To allow email addresses, domains, or OIDC identities, or to open signup, see [Giving People Access](/guide/platform/administration/access#giving-people-access).
|
|
90
|
+
|
|
91
|
+
Your administrator session lasts for one hour. Use it to inspect users, projects, logs, and platform health. The [Platform Administration guide](/guide/platform-administration) walks through those workflows, previews, and automation. You can also open `<API origin>/admin/login` to use the browser admin UI.
|
|
92
|
+
|
|
93
|
+
### Protect Project Hostnames with Zero Trust
|
|
94
|
+
|
|
95
|
+
After installation, an administrator can require Cloudflare Access on new project hostnames while allowing each project owner or project administrator to opt out. This is independent of Access login and protection for the platform API itself, and it needs its own Cloudflare API token. See [Project Zero Trust](/guide/platform/administration/zero-trust) for the requirements, setup command, and recovery.
|
|
@@ -0,0 +1,250 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: 'Resume, repair, upgrade, or recover an installation, including when the keychain or API is unavailable.'
|
|
3
|
+
outline: deep
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Maintenance and Recovery
|
|
7
|
+
|
|
8
|
+
## Resume, repair, recover, and upgrade
|
|
9
|
+
|
|
10
|
+
Run `bwf platform list` to find the installation slug beside its name. Lifecycle commands accept this slug, an installation ID, or a saved connection ID. You can omit the selector when only one installation is configured. With several installations, choose one interactively or pass its slug or ID in CI.
|
|
11
|
+
|
|
12
|
+
### Resume an installation
|
|
13
|
+
|
|
14
|
+
If setup stops or fails, continue from the saved progress:
|
|
15
|
+
|
|
16
|
+
```sh
|
|
17
|
+
bwf platform install --resume --name <id>
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
You can correct the database URL if the initial connection failed. Once bwf has claimed the database or provisioned Hyperdrive, that database is fixed for the installation. A later command with a different URL stops before making changes.
|
|
21
|
+
|
|
22
|
+
### Cloudflare Access blocks the health check {#cloudflare-access}
|
|
23
|
+
|
|
24
|
+
If installation reports **Default-Deny (error 1050)**, Cloudflare blocked the HTTP health check before it reached bwf. This is separate from the API token used to deploy the Workers.
|
|
25
|
+
|
|
26
|
+
Keep the company protection in place. Automatic Access setup saves its scoped
|
|
27
|
+
service credentials with the installation's encrypted recovery material. For an
|
|
28
|
+
existing gate, verify that its service policy admits the installation token and
|
|
29
|
+
that the application covers the printed API and proxy origins. A Cloudflare
|
|
30
|
+
management API token does not authenticate an Access-protected HTTP request.
|
|
31
|
+
|
|
32
|
+
For automatic setup, resuming also creates or verifies an Access exception
|
|
33
|
+
limited to `/health` on the reserved dispatch health hostname. bwf still requires
|
|
34
|
+
its private probe token on that endpoint; requests without it cannot reach an
|
|
35
|
+
application. This lets installation check routing while employee protection and
|
|
36
|
+
account-wide Default-Deny remain enabled. It does not bypass Access for an entire
|
|
37
|
+
Worker or for deployed apps.
|
|
38
|
+
|
|
39
|
+
For externally supplied credentials, set `NOSAM_ACCESS_CREDENTIALS` from your
|
|
40
|
+
secret manager to an object keyed by each exact API/proxy origin, with
|
|
41
|
+
`CF_ACCESS_CLIENT_ID` and `CF_ACCESS_CLIENT_SECRET` in each entry. Then rerun
|
|
42
|
+
`bwf platform install --resume --name <id>`. bwf retains the saved resources
|
|
43
|
+
and stops if the gate still rejects its checks. Account-wide Default-Deny and
|
|
44
|
+
deployed-application policies remain your responsibility.
|
|
45
|
+
|
|
46
|
+
### Expired administrator setup code
|
|
47
|
+
|
|
48
|
+
Resume an unfinished installation with `bwf platform install --resume --name <id>`.
|
|
49
|
+
For completed provisioning whose administrator setup is still pending, run
|
|
50
|
+
`bwf platform repair <id>`. bwf prints a fresh setup code if the earlier code
|
|
51
|
+
expired. Enter it at `/setup`, sign in, and confirm the displayed identity.
|
|
52
|
+
An installation that already has an administrator does not reopen setup.
|
|
53
|
+
|
|
54
|
+
### First administrator sign-in fails
|
|
55
|
+
|
|
56
|
+
If sign-in fails after you enter the setup code, the page shows the reason and an
|
|
57
|
+
error code. When a provider setting may be the cause, it also shows the callback
|
|
58
|
+
URL the provider must have.
|
|
59
|
+
|
|
60
|
+
| Error code | What to check |
|
|
61
|
+
| --------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
|
|
62
|
+
| `github_incorrect_client_credentials`, `github_failed`, `oidc_token_failed` | The client ID and client secret, and that the provider has the callback URL |
|
|
63
|
+
| `github_redirect_uri_mismatch` | The callback URL registered in the GitHub OAuth app |
|
|
64
|
+
| `oidc_discovery_failed` | The issuer URL, exactly, including any trailing slash |
|
|
65
|
+
| `github_unverified_user_email` | Verify the primary email of the GitHub account |
|
|
66
|
+
| `google_domain_not_allowed`, `oidc_group_not_allowed` | Sign in with an allowed account, or change the allowed domains or groups |
|
|
67
|
+
| `login_denied`, `github_bad_verification_code` | Start a new sign-in |
|
|
68
|
+
|
|
69
|
+
If the provider shows its own error page instead, register exactly the callback
|
|
70
|
+
URL printed with your setup code.
|
|
71
|
+
|
|
72
|
+
To change the login settings, run repair on the computer that installed the
|
|
73
|
+
platform:
|
|
74
|
+
|
|
75
|
+
```sh
|
|
76
|
+
bwf platform repair <id>
|
|
77
|
+
bwf platform repair <id> --auth-config <path>
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Interactive repair asks whether to change the login settings, with the saved
|
|
81
|
+
values filled in; leave the client secret blank to keep it. `--auth-config`
|
|
82
|
+
takes a file in the [install format](/guide/platform/installation/setup#finish-login-configuration)
|
|
83
|
+
and is the way to change OIDC allowed groups. Login methods and Access protection
|
|
84
|
+
stay as installed. Repair prints a new setup code and the callback URL.
|
|
85
|
+
|
|
86
|
+
A GitHub-only installation signs in with the GitHub OAuth App from its
|
|
87
|
+
installation settings. To replace its client ID and secret, set
|
|
88
|
+
`NOSAM_PLATFORM_GITHUB_CLIENT_ID` and `NOSAM_PLATFORM_GITHUB_CLIENT_SECRET` when
|
|
89
|
+
you run `bwf platform repair <id>`.
|
|
90
|
+
|
|
91
|
+
### Repair missing resources
|
|
92
|
+
|
|
93
|
+
Preview what needs repair, then apply it:
|
|
94
|
+
|
|
95
|
+
```sh
|
|
96
|
+
bwf platform repair [id] --plan
|
|
97
|
+
bwf platform repair [id]
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
Repair recreates missing infrastructure that the installer owns. It does not restore PostgreSQL rows or data stored in provider resources. If an adopted or external resource is missing, restore it yourself before continuing. A disabled platform stays disabled through repair and upgrade.
|
|
101
|
+
|
|
102
|
+
### Upgrade the platform
|
|
103
|
+
|
|
104
|
+
Upgrade the platform before your team updates its CLI. Install the new CLI on the administrator's machine, run the upgrade below, then have the team update.
|
|
105
|
+
|
|
106
|
+
For apps using `@builtbyfriends/bwf/sandbox`, add **Account → Containers → Edit** and **Account → Cloudchamber → Edit** to the runtime token. Edit its permissions in Cloudflare, or supply a replacement with `NOSAM_PLATFORM_RUNTIME_CLOUDFLARE_API_TOKEN`. See [Cloudflare API Tokens](/guide/platform/installation/credentials#runtime-token-permissions).
|
|
107
|
+
|
|
108
|
+
Use the installed CLI's packaged runtime to upgrade:
|
|
109
|
+
|
|
110
|
+
```sh
|
|
111
|
+
bwf platform upgrade [id] --plan
|
|
112
|
+
bwf platform upgrade [id]
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
An upgrade validates the runtime, applies supported pending migrations, deploys the Workers, and checks their health. Existing Worker secrets are preserved.
|
|
116
|
+
|
|
117
|
+
Install, upgrade, and repair also publish the saved [AI Gateway logging](/reference/cli/platform-users#ai-gateway-logging) settings (**Publishing AI logging settings**). For about 2 minutes afterward, `bwf platform project show` reports projects with a setting other than `inherit` as `pending`, as well as projects it switched back to `inherit`.
|
|
118
|
+
|
|
119
|
+
Before starting, bwf checks access to the installation's Cloudflare account, Workers, and existing R2 buckets. If credentials are rejected, set `CLOUDFLARE_API_TOKEN` to a management token scoped to that account and retry. This overrides the installation's saved management token.
|
|
120
|
+
|
|
121
|
+
Some upgrades pause application traffic until the new version passes health checks. If a command fails while traffic is paused:
|
|
122
|
+
|
|
123
|
+
1. Run `bwf platform status <id>` to see the saved progress.
|
|
124
|
+
2. Fix the reported problem.
|
|
125
|
+
3. Run the printed resume command with the same runtime. Traffic resumes when it succeeds.
|
|
126
|
+
|
|
127
|
+
::: details Migration safety, credential rotation, and rollback
|
|
128
|
+
|
|
129
|
+
To update the runtime Cloudflare token, GitHub OAuth credentials when GitHub login is enabled, or R2 credentials,
|
|
130
|
+
provide their `NOSAM_PLATFORM_*` environment variables when running the upgrade.
|
|
131
|
+
Only the supplied values replace live credentials. Recovery data from an older
|
|
132
|
+
workstation does not overwrite them, and upgrades preserve the live signing keys
|
|
133
|
+
and complete project-encryption keyring. Keep current credentials in your secret
|
|
134
|
+
manager so they can also restore a missing Worker during repair.
|
|
135
|
+
|
|
136
|
+
Database migrations only move forward. bwf checks compatibility before upgrading and tells you if an intermediate release is needed. If deployment fails, it attempts to restore the previous Workers against the compatible database schema. Retrying does not repeat completed migrations.
|
|
137
|
+
|
|
138
|
+
After a successful upgrade, you can restore a declared-compatible earlier runtime without reversing migrations:
|
|
139
|
+
|
|
140
|
+
```sh
|
|
141
|
+
bwf platform rollback [id] --runtime /path/to/earlier/runtime --plan
|
|
142
|
+
bwf platform rollback [id] --runtime /path/to/earlier/runtime
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
Keep the earlier runtime files if you need rollback. If the installed version is a custom build, also pass its files with `--from-runtime /path/to/current/runtime`. bwf checks that the earlier version can run against your current database and refuses incompatible rollbacks. A later `upgrade` can move forward again. See [Platform Development](/guide/platform/development/runtime#deploying-your-runtime) for working with custom builds.
|
|
146
|
+
|
|
147
|
+
Do not roll back to 0.26.0 or earlier after upgrading to a later release. bwf does not refuse this rollback, but those releases reject the credentials that later releases give your apps. Every project deployed or rotated since the upgrade loses AI, email, and remote D1, KV, and R2 until you upgrade again. If you have rolled back that far, upgrade again, then run `bwf platform system rotate-proxy-tokens --all --yes` and check with `--plan` until nothing is pending or failed.
|
|
148
|
+
|
|
149
|
+
After a rollback to 1.8.0, plan [AI Gateway logging](/guide/platform/administration/plans#ai-gateway-logging) defaults are not applied: projects that follow a plan default use the gateway's own setting, which logs prompts and responses on a new installation. Project settings still apply. Plan defaults stay saved, and the next upgrade publishes them again. A rollback to a release before 1.8.0 applies no AI logging settings.
|
|
150
|
+
|
|
151
|
+
Let running rotations finish before you roll back. If an older proxy runs next to a newer API, remote D1, KV, and R2 fail until both run the same release. After a rollback to the release just before credential rotation, projects deployed since the upgrade lose remote D1, KV, and R2 until they are deployed again or you upgrade again. A rotated project deployed during any rollback stays broken after you upgrade again, and 0.26.0 and earlier also drop rotations that have not finished. After upgrading again from any rollback, run the same `rotate-proxy-tokens` commands.
|
|
152
|
+
|
|
153
|
+
:::
|
|
154
|
+
|
|
155
|
+
### Change runtime logs {#runtime-logs}
|
|
156
|
+
|
|
157
|
+
Switch an installed platform between [full and minimal runtime logs](/guide/platform/installation/setup#runtime-logs) with an upgrade:
|
|
158
|
+
|
|
159
|
+
```sh
|
|
160
|
+
bwf platform upgrade [id] --runtime-logs minimal
|
|
161
|
+
bwf platform upgrade [id] --runtime-logs full
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
The setting also applies to existing project deployments, and later upgrades keep it. Previously stored logs remain until Cloudflare's retention period ends.
|
|
165
|
+
|
|
166
|
+
If updating project logs fails, the platform upgrade still completes and prints a recovery command. Run `bwf platform repair [id]` after switching to minimal, or repeat the upgrade after switching to full.
|
|
167
|
+
|
|
168
|
+
While runtime logs are minimal, `bwf platform rollback` refuses a runtime that does not support the setting. Run `bwf platform upgrade [id] --runtime-logs full` first.
|
|
169
|
+
|
|
170
|
+
### Platform Workers changed outside bwf {#workers-changed-outside-nosam}
|
|
171
|
+
|
|
172
|
+
Use bwf commands to manage the platform's Workers. If their configuration was changed in Cloudflare, or bwf cannot identify the active version, maintenance asks you to approve replacing it. Preview the affected Workers with `--plan`.
|
|
173
|
+
|
|
174
|
+
Run the printed command in a terminal and review **Replace the configuration of these Workers?** The default is No. Accepting restores bwf's configuration, including removing manually added variables. You may see another confirmation with the configuration differences before deployment. Declining that later prompt leaves any resource and database preparation in place.
|
|
175
|
+
|
|
176
|
+
CI and `--yes` runs stop when this approval is needed. Complete the interactive command once, then resume automation. If a Worker uses a gradual deployment, first select one version for 100% of traffic in Cloudflare.
|
|
177
|
+
|
|
178
|
+
If traffic was already paused by an earlier failed run, follow [Upgrade the platform](#upgrade-the-platform) to resume it.
|
|
179
|
+
|
|
180
|
+
### Follow upgrade and rollback progress
|
|
181
|
+
|
|
182
|
+
Watching progress is optional: a running upgrade or rollback proceeds through
|
|
183
|
+
the CLI without action on the status page. During maintenance, navigating the
|
|
184
|
+
admin UI automatically redirects to `/admin/status`. You can also open it
|
|
185
|
+
directly on your platform API origin and sign in as an administrator.
|
|
186
|
+
|
|
187
|
+
The read-only page shows the saved operation, source and target versions, and
|
|
188
|
+
the traffic state reported by the API. It refreshes automatically every five
|
|
189
|
+
seconds while visible. If updates fail, it keeps the last confirmed snapshot
|
|
190
|
+
and marks it as out of date. Normal administrator changes remain paused.
|
|
191
|
+
|
|
192
|
+
Sign-in and status remain available while the API and authentication database
|
|
193
|
+
are reachable. An operation completing
|
|
194
|
+
does not confirm every project's health. A disabled installation keeps traffic
|
|
195
|
+
paused after an upgrade or rollback.
|
|
196
|
+
|
|
197
|
+
If an operation fails or waits for DNS or Sandbox drain work, the CLI prints
|
|
198
|
+
the recovery instructions and command needed to resume. Resolve the reported
|
|
199
|
+
problem, then resume with the same runtime files. For a custom rollback, retain
|
|
200
|
+
the source runtime files too. `bwf platform status <id>` also prints locally saved progress
|
|
201
|
+
before checking the live API; this local checkpoint can be out of date if another
|
|
202
|
+
administrator changed the installation.
|
|
203
|
+
|
|
204
|
+
When application traffic is paused, visitors receive a temporary-unavailability
|
|
205
|
+
page with a **Try again** link. API requests and form submissions still receive
|
|
206
|
+
HTTP 503 responses. bwf does not automatically replay requests; visitors who
|
|
207
|
+
submitted a form should check its result before submitting it again.
|
|
208
|
+
|
|
209
|
+
### Manage an installation from another machine
|
|
210
|
+
|
|
211
|
+
Use `discover` to restore the administrator's local installation records:
|
|
212
|
+
|
|
213
|
+
```sh
|
|
214
|
+
bwf platform discover --account <account-id> --installation <id-or-name>
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
Discovery restores local installation records after verifying the resources belong to your platform. It also works for interrupted or disabled installations. If infrastructure is missing, run `bwf platform repair [id]` after discovery. If ownership cannot be verified, the command stops without changing resources.
|
|
218
|
+
|
|
219
|
+
After discovery, provide `NOSAM_PLATFORM_DATABASE_URL` for migrations and to coordinate administrator commands. You don't need to re-enter the other secrets for an upgrade that preserves every deployed Worker. For an email-enabled installation without its encrypted recovery file, restore `NOSAM_PLATFORM_EMAIL_SIGNING_SECRET`; recreating only the email gateway needs that key and no Cloudflare runtime token or JWT signing key. Recreating the API or proxy also requires the email key when email is enabled, in addition to their normal secrets. Recreating the API requires its original runtime token (`NOSAM_PLATFORM_RUNTIME_CLOUDFLARE_API_TOKEN`), R2, JWT, and project-encryption values through the `NOSAM_PLATFORM_*` variables; a GitHub-only installation also needs its original GitHub OAuth values. Recreating the proxy requires the runtime token and JWT signing key. Cloudflare can't return these values, so keep them in your organization's secret manager.
|
|
220
|
+
|
|
221
|
+
If you have not rotated the project-encryption key, restore it with `NOSAM_PLATFORM_PROJECT_SECRET_KEY`. After rotation, supply `NOSAM_PLATFORM_PROJECT_SECRET_KEYS_JSON` with all retained keys and `NOSAM_PLATFORM_PROJECT_SECRET_ACTIVE_KEY_VERSION` with the active key's name. Keep older keys needed to decrypt existing project secrets. These values are used to recreate a missing API Worker; they do not replace the live keys during an ordinary upgrade. Supply them from your secret manager.
|
|
222
|
+
|
|
223
|
+
### Prepare for disaster recovery
|
|
224
|
+
|
|
225
|
+
`discover` reconstructs verified installation metadata on another machine. It does not download credentials, key material, or backed-up data. `repair` can then recreate missing installer-owned infrastructure, but it does not recover the data that infrastructure previously held.
|
|
226
|
+
|
|
227
|
+
Keep a coordinated recovery set for each installation:
|
|
228
|
+
|
|
229
|
+
- a PostgreSQL backup;
|
|
230
|
+
- the installation identity—the JWT signing secret, the email signing secret when email is enabled, and the complete project-encryption keyring—in a secret manager;
|
|
231
|
+
- provider-supported backups or exports for every data-bearing provider resource;
|
|
232
|
+
- the immutable runtime artifacts and manifest for the installed version or custom source revision.
|
|
233
|
+
|
|
234
|
+
Capture and label these items as one recovery point so PostgreSQL, provider data, identity, and encryption keys match. Backup and retention capabilities vary by provider and resource; choose and test the supported recovery process for each resource you use.
|
|
235
|
+
|
|
236
|
+
During a restore, keep platform and application traffic disabled before changing resources. Restore the matching PostgreSQL and provider data with their supported recovery tools, supply the original identity and keyring, and use the preserved runtime artifact. Then run `discover`, preview `repair` with `--plan`, and review every ownership decision and proposed resource change before applying it. Enable traffic only after the restored data and platform health have been verified. Discovery and repair are not substitutes for those backups and do not provide a recovery bypass when required secrets or data are unavailable.
|
|
237
|
+
|
|
238
|
+
### Where local state lives
|
|
239
|
+
|
|
240
|
+
Installation records live in `~/.bwf/platforms/`. Credentials are stored separately in encrypted recovery files, with the encryption key in your operating system's keychain. Keep your original secrets in a password manager for recovery on another machine. Signing and encryption keys that bwf generated exist only in these files; to keep your own copy, [supply them when installing](/guide/platform/installation/credentials#signing-and-encryption-keys).
|
|
241
|
+
|
|
242
|
+
If the keychain isn't available, bwf stops before writing secrets. Headless environments can supply `NOSAM_PLATFORM_RECOVERY_KEY`: a canonical base64-encoded 32-byte key from a secret manager. A temporary CI runner can use a new recovery-encryption key for each run only when every original credential remains available in protected CI secrets, including `NOSAM_PLATFORM_JWT_SECRET`, `NOSAM_PLATFORM_EMAIL_SIGNING_SECRET` for an email-enabled installation, and either the original `NOSAM_PLATFORM_PROJECT_SECRET_KEY` or the complete rotated keyring and active-version pair.
|
|
243
|
+
|
|
244
|
+
::: details Ownership and interrupted maintenance
|
|
245
|
+
|
|
246
|
+
bwf checks resource ownership and the configured database before making changes. Concurrent maintenance commands are coordinated so one administrator cannot overwrite another's work.
|
|
247
|
+
|
|
248
|
+
If maintenance is interrupted, rerun the same command. Traffic may stay paused until verification succeeds. Existing routes, domains, and data are preserved.
|
|
249
|
+
|
|
250
|
+
:::
|