API and Studio deployment

apps/api and apps/studio are Next.js applications with two supported deployment shapes:

• Staging: separate OpenNext workers on Cloudflare, which exercises the browser/edge topology before promotion.
• Production: separate OpenNext workers on the canonical Cloudflare domains, backed by the production Lakebase database through a dedicated, cache-disabled Hyperdrive configuration.

Staging on Cloudflare

The public staging hosts are https://api-staging.experiments.fabric.pro and https://studio-staging.experiments.fabric.pro.

Cloudflare Builds is the primary deployment path. Manual fallback:

pnpm install --frozen-lockfile
pnpm --filter @fabricorg/experiments-api run cf:deploy:staging
pnpm --filter @fabricorg/experiments-studio run cf:deploy:staging

The API deploy command then applies every pending SQL migration through a short-lived, token-protected Worker bound to the same Hyperdrive configuration. The migrator records filenames in fx._migrations, rolls back a failed file, and deletes itself after the run. This avoids distributing the Neon origin password to developer machines while keeping schema promotion repeatable. To repair or verify staging independently:

node scripts/migrate-cloudflare-hyperdrive.mjs staging

Treat a migration failure as a failed deployment. Do not start the live smoke against an older schema.

API configuration includes:

• Neon Postgres through the HYPERDRIVE binding, with DATABASE_URL only as a controlled fallback;
• BETTER_AUTH_SECRET, MANIFEST_KEY_ENC_KEY_HEX, and WORKER_API_TOKEN as Worker secrets;
• FX_BASE_URL, FX_AUTH_COOKIE_DOMAIN, FX_TRUSTED_ORIGINS, manifest and ingestion worker URLs as non-secret variables;
• Databricks aggregate configuration when the staging warehouse path is enabled.

Studio sets FX_API_BASE_URL and NEXT_PUBLIC_FX_API_BASE_URL to the staging API. Better Auth cookies use .experiments.fabric.pro so server-rendered Studio requests and API authentication share the intended sibling-domain boundary.

Cloudflare production

Production configuration uses api.experiments.fabric.pro and studio.experiments.fabric.pro. The API and Studio compute run on Cloudflare; operational Postgres state remains in the existing Databricks Lakebase project.

Production operational state remains in the existing Databricks Lakebase project. Enable password connections, create a native Postgres role with runtime-only grants, and bind it through a cache-disabled Hyperdrive configuration on the API. Production migrations remain owner-governed Databricks operations; the Cloudflare runtime role does not receive DDL privileges. The readiness command fails closed if the binding is missing, if staging Hyperdrive is reused, or if the production secret inventory is incomplete:

node scripts/check-cloudflare-production-readiness.mjs
pnpm --filter @fabricorg/experiments-api run cf:deploy:production
pnpm --filter @fabricorg/experiments-studio run cf:deploy:production

Confirm the canonical Lakebase migration ledger is current before deploying. Follow the repository's docs/runbooks/cloudflare-production-cutover.md for database rehearsal, tenant/auth acceptance, the 24-hour canonical rollback soak, routing, and rollback.

Databricks rollback runtime

The repository root contains the Databricks Asset Bundle and combined runtime.

databricks bundle validate -t prod
databricks bundle deploy -t prod

The combined Databricks App is retained only for the initial rollback soak and owner-governed migration operations. It is not the canonical web entry point. After the 24-hour healthy-traffic gate, stop the App while retaining its last deployment and the unchanged Lakebase state for rollback.

Continue with the Databricks deployment guide for bindings, health checks, secret scope, and troubleshooting, or Publish and test from cloud for the full release sequence.