Skip to main content
This page explains how Tuturuuu moves from code to running environments.

​
Branch-to-Environment Map

​
Hosted Web Release Flow

​
Preview

  • Preview workflows are named vercel-preview-<app>.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-<app> 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-<app>.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-<app> 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 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.

​
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.