> ## Documentation Index > Fetch the complete documentation index at: https://docs.tuturuuu.com/llms.txt > Use this file to discover all available pages before exploring further. # Environments & Release Flow > How branches map to environments, and what happens between preview, staging, production, and self-hosted deploys. This page explains how Tuturuuu moves from code to running environments. ## Branch-to-Environment Map | Branch or event | What deploys | Follow-up automation | | ----------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | Feature branch push | CI only; Vercel preview deployments require trusted manual dispatch from `main` with `preview_ref` | None by default | | `main` push | Platform Vercel preview build validation | `supabase-staging.yaml` can apply staging migrations after the preview build succeeds | | `production` push | Platform Vercel production deployment | `supabase-production.yaml` can apply production migrations after the deployment and staging prerequisites pass | | `main` push for `apps/discord` | Discord Modal deployment after Python CI succeeds | None | | Manual `workflow_dispatch` | Depends on workflow | Bypasses normal branch trigger timing, but not the workflow logic; production Supabase migration dispatches must select `production` | | Self-hosted server after `git pull` | Docker deploy from current checkout | Optional blue/green cutover through `bun serve:web:docker:bg` | ## Hosted Web Release Flow ### Preview * Preview workflows are named `vercel-preview-.yaml`. * Most preview workflows are manual-only from `main` with a required `preview_ref`; `vercel-preview-platform.yaml` also triggers on protected `main` pushes so the staging database workflow receives a same-SHA platform build signal. * `e2e-tests.yaml` also runs only on non-`production` pushes; production promotion relies on the already-green validation before the branch is promoted plus the production build-validation gates below. * Each workflow checks whether a newer commit exists on the same branch before spending time on install/build/deploy. * Each deploy job is bound to a `vercel-preview-` GitHub Environment and introduces Vercel credentials only after dependency installation. * Platform preview is build validation only; on-premise machines own the actual `apps/web` runtime deployment. * Satellite preview deploys remain the normal Vercel validation surface for branch work and merged `main` changes. * Platform preview can reuse a successful same-SHA production platform build marker to avoid redundant preview builds. Production does not reuse preview markers because it must build and deploy the prebuilt production artifacts. ### Staging Database * `supabase-staging.yaml` is tied to the `Vercel Platform Preview Deployment` workflow on `main`. * The staging migration runs only when the triggering platform preview build concludes successfully, or when manually dispatched. * The staging deploy step runs `supabase db push --include-all` after linking the staging Supabase project, so staging can converge after `main` migration history changes. * This means `main` is where app preview and staging schema advancement are meant to stay aligned. * If a production commit was promoted before the same-SHA staging migration run existed, manually dispatch `supabase-staging.yaml` from `main`; production migration re-evaluates after that staging run succeeds. ### Production * Satellite production web deploys run through `vercel-production-.yaml`. * Hosted `apps/web` production deploys run through `vercel-production-platform.yaml`; self-hosted machines still use the Docker release flow below for their own runtime deployment. * `apps/apps` production deploys are handled by `vercel-production-apps.yaml`. * `apps/qr` production deploys are handled by `vercel-production-qr.yaml`. * The production workflow also skips if a newer commit already exists on `production`. * Production deploy jobs are bound to `vercel-production-` GitHub Environments and reject manual dispatches unless the selected branch is `production`. ### Browser App Version Metadata * Browser apps share one platform version from `packages/utils/src/platform-release.ts`; do not read visible app versions from individual app `package.json` files. * The shared browser app version is the `TUTURUUU_PLATFORM_VERSION` constant exported from `packages/utils/src/platform-release.ts`. Release Please owns that value (it carries the `x-release-please-version` annotation), so do not pin a literal version in docs or bump it by hand. Read the constant directly when you need the current value. * Every Vercel browser app workflow runs `bun run --silent scripts/ci/generate-build-metadata.ts` before `vercel build`. The generated metadata includes the commit hash, short hash, commit message, ref, environment, deployment URL, deployment stamp, and build timestamp. * The account-scoped version badge uses `public.user_configs` key `SHOW_VERSION_BADGE`. It is hidden by default and only exact `@tuturuuu.com` accounts may enable a truthy value. * Exact-domain enforcement happens on the server through `isExactTuturuuuDotComEmail`; subdomains such as `@xwf.tuturuuu.com` are not eligible, and client cookies cannot make the badge render for ineligible users. ### Production Database `supabase-production.yaml` is stricter than staging: 1. It re-evaluates automatically after either `Vercel Platform Production Deployment` completes its production deploy on `production` or `Supabase Staging Migration` completes on `main`. 2. The production platform deployment for the target commit must have concluded successfully on `production` and recorded the successful `vercel-production-platform` deployment marker for the same SHA. A workflow run that skipped because package releases were still publishing is not enough. 3. The `main` staging migration for the same target commit must have completed with a `success` conclusion. 4. A manual dispatch can still be used when an operator explicitly wants to run it, but the dispatch must select the `production` branch and still satisfy the same production-deployment and staging-migration SHA checks. The staging-triggered path is an automatic retry for the case where production production deploy finishes before staging migration does. The production migration job still checks out the verified target commit explicitly before running `supabase db push --include-all`. This keeps production schema changes behind application deployment, staging validation, and branch promotion for the same commit. ## Self-Hosted Web Release Flow If a server receives code through `git pull`, use the Docker production commands from the checked-out commit: * `bun serve:web:docker` for in-place replacement * `bun serve:web:docker:bg` for blue/green rebuild-before-cutover deployment Blue/green is the safer path when uptime matters because the new image is built and health-checked before the proxy is reloaded. ## Migration Release Path (TanStack + Rust) `apps/web` (Next.js, port `7803`) is being replaced by `apps/tanstack-web` (TanStack Start) plus `apps/backend` (the Rust HTTP core, port `7820`). See [the TanStack/Rust migration overview](/platform/architecture/tanstack-rust-migration) for the full plan. While that migration is incomplete, Docker blue/green remains the canonical production rollout and rollback mechanism for the live hostname. Cloudflare Workers are used as a separate, incremental **preview** surface to prove Worker compatibility for `apps/tanstack-web` and `apps/backend` before any cutover: * Validate the Wrangler deploy configs without contacting Cloudflare with `bun check:cloudflare`. * Deploy the Rust backend Worker (`apps/backend/wrangler.jsonc`) and the TanStack Start Worker (`apps/tanstack-web/wrangler.jsonc`) to preview, then smoke both returned origins with `bun smoke:cloudflare`. * Do not route the production hostname to preview Workers until the TanStack/Rust route manifest, compare-mode Docker E2E, benchmark report, and cutover gates (`bun migration:tanstack:gates`) all pass. * Rollback from the preview path is DNS/routing-based (remove the Cloudflare route or roll back the Worker version); the Docker blue/green `apps/web` stack keeps serving the canonical hostname throughout. The full Cloudflare preview, secret-bootstrap, smoke, and cutover-gate runbook lives in [Web Docker Deployment → Cloudflare Preview Path](/build/devops/web-docker-deployment). ## Team Release Checklist 1. Merge the change set with green CI. 2. If Docker behavior changed, make sure `docker-setup-check.yaml` is green. 3. If database migrations changed, confirm the `main`-driven staging path first. 4. Promote to `production` only after preview and staging behavior is understood. 5. Confirm the follow-up Supabase workflow after production deployment. 6. For self-hosted rollout, deploy from the intended commit and prefer `bun serve:web:docker:bg`. ## Rollback Guidance * Vercel-hosted rollback: for satellite apps, redeploy the previous known-good commit or use Vercel rollback tooling. * Supabase rollback: use a corrective migration instead of editing applied migration history. * Self-hosted Docker rollback: checkout the previous known-good commit and rerun `bun serve:web:docker:bg`. ## What Not To Do * Do not push production schema changes directly from a laptop as the normal path. * Do not assume staging and production migrations are interchangeable; they are gated differently. * Do not manually dispatch production Supabase migration from `main`; the only valid `main` path is the automatic staging-migration re-evaluation, and the production gate still requires the same commit to have both a successful production platform deployment and a completed successful `main` staging migration. * Do not use the in-place Docker path when you specifically need rebuild-before-restart semantics.