Deploy Lumen

Outcome

A verified commit can produce four bounded deployment targets: static workbench, app, worker, and static documentation, without adding another control plane.

Prerequisites

Use separate staging resources and an immutable verified commit. Snapshot current DNS and deployment aliases. Confirm the existing provider plans can support the change without an upgrade or disabled spend cap.

Steps

1. Configure the Vercel project's Root Directory as the repository root (.). Install with corepack pnpm install --frozen-lockfile, build with corepack pnpm --filter @lumen/web build, and publish apps/web/dist. The static rewrite sends /projects/:path* to /index.html; it is not a catch-all rewrite. Vercel therefore serves /assets/* directly, and a missing /assets/* path remains an HTTP 404. Do not add a Vercel Function for routing or application behavior.
2. Build one digest-pinned Python image and select the app or worker entry point on Railway.
3. Build apps/docs/build/client with DOCS_BASE_PATH=/ for the custom documentation domain.
4. Apply Alembic through the migration role before compatible process rollout.
5. Verify previews, including a hard refresh on a run-qualified workbench route, then change one hostname class at a time.
6. Verify TLS, static deep links, CORS, authentication, SSE, worker polling, and every documentation route from the final public hosts.
7. Retain the previous deployment and DNS snapshot until rollback proof passes.

A local build or slice checkpoint does not constitute a production deployment. Provider creation and DNS mutation belong to the release slice and require saved live evidence.

Verify

Check the exact deployed commit and artifact digests. Static hosts must serve no function or privileged runtime. app readiness checks database and configuration; worker health checks Temporal polling, database access, and reconciliation progress.

On both the preview and final apex/www hosts, hard-refresh the project, settings, run, and one nested object route. Exercise back/forward navigation and confirm the selected inspector object remains stable. An unknown /projects/* route must load the static shell and render the client not-found state. An unknown /assets/* path must remain an HTTP 404 instead of receiving index.html. Do not generalize that asset assertion to arbitrary paths beneath /projects/*, because those paths are intentionally inside the SPA rewrite. Inspect the network log to confirm that Vercel served only the static artifact and that REST and resumable SSE use the configured API origin.

Recover

Restore the prior static artifacts and backend image, then restore only the DNS records changed by this rollout. Do not remove the prior project until apex, www, TLS, and SPA deep links are proven.

Next task

Set and measure capacity.