← All articles

Deployments

Atomic deployments: the release-directory pattern

Build beside the live app, check the new release, then switch one symlink. A practical guide to safer SSH deployments and fast rollbacks.

A release moving through build, health check, symlink switch, and rollback

A deployment should have a clear answer to one question: which version is serving traffic right now? Updating a live directory in place makes that answer harder. A release-directory layout keeps each version separate until it is ready.

Keep each release immutable

Create a new directory for every build, usually with a timestamp or commit identifier. Install dependencies and prepare configuration there, while the current release keeps serving requests.

When the new release is ready, run its health check before changing production traffic. If the check fails, leave the current symlink alone and inspect the new directory without affecting users.

Switch in one operation

Keep a stable path such as `current` pointing at the active release. Once the health check passes, update that symlink to the new release. The application sees a complete version rather than a directory halfway through a copy.

Retain a small number of previous releases. A rollback then points `current` at a known-good version instead of rebuilding under pressure.

Make rollback part of the deploy

Agree on the health check, release retention policy, and rollback command before the first production run. Also decide how database migrations behave: a code rollback cannot safely reverse every schema change.

  • Keep build output separate from uploaded user data.
  • Keep secrets outside release directories or link them from a protected shared path.
  • Verify the active release after the switch.
  • Clean up old releases only after the new version is confirmed healthy.

The pattern is deliberately simple. It does not require a container platform, but it does make the deploy boundary visible and the recovery path testable.

Atomic deployments: the release-directory pattern | PlainShip Blog