Web deployment

Web Deployment

Purpose

Plan how each web app ships: a platform that actually supports the framework's features, per-environment configuration, preview flows, caching, domains, and rollback. Executes nothing — deployment and publishing happen only with explicit approval (../../release-planning, Gate 7).

When to Use

• After the framework/foundation is decided (hosting needs differ sharply), before first release planning.
• When an existing app's hosting fights its framework (missing SPA fallback, unsupported SSR features).
• Not for release readiness itself (../../release-planning) or CI test wiring (playwright-e2e).

Inputs

• Framework decisions per app (web-stack-selection) and rendering strategy (nextjs-foundation).
• Dashboard placement (dashboard-architecture) — separate apps may deploy to separate targets/restrictions.
• Environments, domains, and compliance/network constraints (VPN/IP-restricted admin, data residency).

Discovery Questions

• Which Next.js features are used — SSR/ISR/middleware/server actions (need a Node/edge-capable platform) or is static export viable?
• (Vite) Where does the static bundle live (CDN/static host), and is the SPA fallback rewrite to index.html configured for deep links?
• What environments exist, and how do env vars/secrets flow per environment (build-time public vars vs server-side secrets)?
• Are preview deployments per PR wanted? What are the domain/TLS/redirect requirements? Must the dashboard sit behind network restrictions?

Responsibilities

• Select the platform per app with justification: Next.js with server features → Vercel-class platform, container/Node self-hosting, or equivalent — verify feature support (ISR, middleware, image optimization) on the actual target; Vite SPA → static hosting + CDN with fallback rewrites.
• Plan environment config: per-environment values, secrets held server-side/in the platform's secret store — public build-time vars (NEXT_PUBLIC_/VITE_) contain nothing sensitive (../../environment-audit).
• Plan preview deployments per PR where valuable — with staging/preview kept non-indexable (web-seo) and auth-gated where content is private.
• Plan caching/CDN: hashed immutable assets cached long; HTML/data responses with deliberate cache headers; ISR/CDN invalidation understood before it surprises anyone.
• Plan domains/TLS/redirects: canonical host (apex vs www), HTTPS everywhere, redirect map for moved content; separate admin domain/network restrictions if dashboard-architecture requires.
• Plan rollback and release safety: instant rollback to a previous build, stale-client handling after deploys (chunk-load reloads, web-error-handling), and what gates a deploy (CI green including playwright-e2e).

Required Workflow

1. Collect framework features, environments, and constraints per app.
2. Select the platform(s) with justification; verify feature support explicitly.
3. Define env/secret flow, preview strategy, and caching/domain plans.
4. Define rollback + deploy gating.
5. Record the plan for approval — execute no deployment without it.

Decision Rules

• The platform must support the framework's used features — "mostly works" is a rejected option.
• Static export/static hosting wins when nothing needs a server; don't pay for SSR infrastructure out of habit.
• One platform per app is the default; the embedded dashboard ships with its host app, a separate dashboard app decides independently.
• Admin surfaces get network restrictions when the placement decision called for them — hosting implements dashboard-architecture, not the other way around.

Rules

• No deploy, platform signup, domain purchase, or publish without explicit user approval.
• Secrets never enter client bundles, repo files, or logs; per-environment separation is absolute.
• Production deploys are gated on the agreed checks (build, tests, E2E) — bypassing gates is a decision the user makes explicitly, recorded.

Anti-Patterns

• Deploying a Vite SPA with no fallback rewrite — every deep link 404s.
• Choosing a platform, then discovering middleware/ISR silently no-ops there.
• Staging indexable by search engines or open to the world with production data.
• "Rollback" meaning re-running a full build under incident pressure.

Validation Checklist

• Platform selected per app with feature-support verification.
• Env/secret flow defined; nothing sensitive in public vars.
• Preview deployments planned; staging non-indexable and gated.
• Caching/CDN and domain/TLS/redirect plans recorded.
• Rollback path and deploy gating defined.
• No deployment executed without explicit approval.

Definition of Done

A recorded deployment plan per app — justified platform, environment/secret flow, preview and caching strategy, domains, rollback, and gating — ready for ../../release-planning, with all execution awaiting explicit approval.

Related Skills

../../release-planning, ../../environment-audit, web-stack-selection, nextjs-foundation, vite-react-foundation, dashboard-architecture, web-seo, web-performance, playwright-e2e, ../../github-repository.

Related Knowledge

../../../knowledge/ (environment topology, compliance constraints).

Related References

../../../references/web/ (platform evaluation notes — when populated).

Context Loading Guidance

• Requires: framework decisions, environments/domains, constraints.
• Does not require: feature-level source, component detail.
• May load: ../../environment-audit for secret flow; ../../release-planning when readiness starts.
• Stop when: the deployment plan is recorded for approval.

Token Efficiency Guidance

One platform-decision table per app (features needed → platform → verified?). Keep header/caching rules as a short table, not prose.