Skip to main content
Slices S9 and S10 of ADR 074. A browser tab on an old Next.js build asks for old /_next/static/<hash> chunks and server action ids after a cutover. This describes what the deploy side does and what the ingress slice (S11) must add.

Done

  • deploy.next_deployment_id (seed APP_DEPLOY_NEXT_DEPLOYMENT_ID, default on): for Next.js sources (build.DetectNext) the Railpack deploy path sets NEXT_DEPLOYMENT_ID to the deploy attempt id (commit sha when there is none) as a build env var and as a container env var. A NEXT_DEPLOYMENT_ID the app sets itself is never overridden. Dockerfile builds are not touched: the Dockerfile owns its build and the user can declare the variable themselves.
  • deploy.next_asset_grace_seconds (seed APP_DEPLOY_NEXT_ASSET_GRACE_SECONDS, default 1800, 0 off): NextGraceBook in internal/deploy/next_assets.go records the superseded release (service, deployment id, image, until).

Design decision

Old assets are served by the old containers, not copied out of the image. The ingress must route only /_next/static/ and /_next/data/ requests that carry the old id (?dpl=<id>, or the x-deployment-id header) to the held previous release; everything else goes to the new release. The previous release hold (deploy.previous_release_hold, default 3m, ADR open question 4) is too short for a 30 minute grace. Answer: the hold must be extended to the grace window for Next.js apps in the reconciler (internal/reconcile/application, WithPreviousReleaseHold), which this slice may not touch.

Cutover wiring (S11)

  • Deploy tail: finishDeploy reads the previous desired service before saving the new one and, once the new release is current, calls NextGraceBook.Begin with the previous NEXT_DEPLOYMENT_ID and image. Only Next.js apps whose deploy set an id, with the setting on and grace above 0, open a window. Previews never do.
  • Durable: windows live in next_asset_grace (migration 3202). The shared book writes through and Load restores it at boot, so a control plane restart keeps the window.
  • Hold: application.WithNextGraceHold extends the previous release hold to the end of the window. The same logic keeps only the newest previous release, and deploy.next_asset_grace_max_held (default 1, max 3) caps how many generations get a window. Rollback and the next deploy use the normal retire path, so a release that is no longer the newest previous one is removed as before.
  • Ingress: internal/ingress/next_skew.go adds a route before the host route. It matches /_next/static/* and /_next/data/* carrying ?dpl=<old id> or the x-deployment-id header and proxies to the held previous containers. Everything else goes to the current release. The held containers are never in the normal upstream pool. The route is rebuilt by the normal ingress pass, so it appears with the deploy and disappears at the next resync after the window ends.

Cost

A held generation keeps its containers running for the whole window (default 30 minutes): one extra copy of the app’s memory and CPU. Lower deploy.next_asset_grace_seconds or set it to 0 to avoid that. By default only the immediately previous release is held: once the next cutover happens, requests for an older release’s deployment id return 404.

Still needs a real host

  • A real cutover on a Next.js app with deploymentId honored by the build: confirm an old tab’s chunk request with ?dpl=<old> is answered by the held container, a request without it by the new one, and that the held container goes away after the window.
  • The held upstream is the best ranked other running container of the service. With multi node placement or a failover pool that ranking is unproven.
  • A control plane restart in the middle of a window, with the held containers still up.
Last modified on November 17, 2026