← All articles

Operations

What belongs in a server deployment runbook?

Turn the reliable parts of a deploy into a short runbook: preflight checks, observable steps, rollback criteria, and clear ownership.

A server connected to a deployment dashboard over SSH

A runbook is useful when it helps someone act safely without needing the author in the room. It should describe the decision points and recovery steps, not just preserve a long shell history.

Start with the preflight

Record the target environment, the release identifier, required approvals, and the checks that must pass before a deploy begins. Include the expected service health signal and where to find logs.

Keep the preflight short enough that it is practical to use: confirm the target hosts, ensure the build is available, check free disk space when it matters, and verify that the previous release can be restored.

Make the sequence observable

Each step should say what success looks like. “Restart the app” is less helpful than “restart the app, wait for the health endpoint, and confirm the new release identifier in the response.”

  • Name the operator or role responsible for each approval.
  • Link to the dashboard, logs, and relevant configuration.
  • Separate routine deploy steps from exceptional repair commands.
  • Avoid storing credentials in the document.

Define the stop and rollback conditions

Write down which failure means “stop here” and which failure means “roll back.” Include the exact path to the previous release and how to verify it is serving traffic again.

Finally, review the runbook after incidents and major changes. A small, current document beats a complete but stale encyclopedia when production is waiting.

What belongs in a server deployment runbook? | PlainShip Blog