
Editorial illustration; the interface is representative and is not a real monitoring system.
A small website can run smoothly for months on one developer’s memory. That person knows which VPS holds the Nginx config, which systemd service runs the ASP.NET or Node app, where the daily pg_dump lands, and which “temporary” Cloudflare Page Rule is quietly keeping checkout working. Everything feels lean until that person is asleep at 2 a.m., stuck on a flight, or away on leave when the client messages on WhatsApp that the site is showing a 502.
A short runbook turns that private mental map into a calm, repeatable sequence. It is not a 40-page architecture document, and it is definitely not a dump of every Linux command you know. It is a decision aid for a stressful moment.
Start with symptoms, not guesses
When an alert fires or a client sends a screenshot, start the runbook entry from what the visitor sees rather than what you suspect broke. “Homepage returns HTTP 500” or “Cloudflare shows Error 522 Connection timed out” is much more useful than “Nginx issue”, because DNS, TLS, edge caching, and the origin process can all produce similar-looking failures.
For each of the three or four failures your site is most likely to hit—a bad deploy, an expired certificate, a full disk, or a wedged database connection—keep a single-page entry with:
- Symptom and scope: Does it affect
/,/wp-admin, API routes, or static assets? - Read-only checks: Commands that gather evidence without mutating production.
- Smallest reversible fix: One change you can undo cleanly if it doesn’t help.
- Visitor verification: What must load in a fresh private browser window before closing the incident.
- Escalation point: When to stop improvising and who holds the keys if deeper access is needed.
Keep actual secrets out of the runbook. Never paste SSH private keys, database passwords, or Cloudflare API tokens into a Markdown file or Notion page. Point to the vault item name in Bitwarden or 1Password instead.
Read-only checks before touching production
The worst habit during an outage is panicking into a chain of destructive actions: restarting the server, purging the entire Cloudflare cache, toggling DNS proxy mode, and updating a plugin all in thirty seconds. Even if the site comes back, you’ve destroyed the evidence and have no idea what actually fixed it—or what will break next.
Put read-only commands at the top of the runbook so any capable developer can separate edge issues from origin issues in two minutes:
# 1. Check what the public edge returns (status, headers, CF-Ray, cache status)
curl -sI https://example.com | grep -iE '^(HTTP/|cf-cache-status|cf-ray|server|location)'
# 2. Bypass the CDN and test the origin IP directly
curl -sI --resolve example.com:443:203.0.113.10 https://example.com
# 3. On the origin host, check disk space and recent service logs
df -h /
sudo systemctl status nginx --no-pager
sudo journalctl -u myapp-web -n 50 --no-pager
Testing the origin directly with curl --resolve is a lifesaver when a site sits behind Cloudflare. Within ten seconds you know whether the origin itself is returning 500/502 or whether the edge can’t reach the origin (for example, after a firewall change or IP rotation).
Make one reversible change at a time
Once the read-only checks point to a cause, the runbook should steer you toward the smallest reversible fix:
- Stale edge cache after a deploy: Purge only the affected URLs (
/,/sitemap.xml, or the specific CSS bundle) rather than hitting “Purge Everything” on a busy site and slamming the origin with uncached traffic. - Broken release: Roll back to the previous known-good Git commit or container tag rather than hot-editing files directly on the server.
- Full disk from runaway logs: Truncate or rotate the offending log file safely rather than deleting directories blindly.
If a static site or Hugo/Eleventy blog deploy finishes in CI but visitors still see yesterday’s homepage, a short runbook sequence keeps you honest: confirm the intended commit hash, check the build log, request the page with a cache-busting query (?cb=123) to compare origin vs cached edge output, and only purge cache if the build itself is genuinely updated.
Verify from the visitor’s seat
A green systemctl status output does not mean the website works. A process can be running while returning an empty white page, broken CSS, or a database read-only error.
Write exact, testable verification steps into the runbook. Instead of “check the site”, write: “Open / and one article in a private browser window, confirm the hero image loads, submit the contact form with a test email, and verify the confirmation message appears.” If your users are mostly on mobile data in Malaysia (where CGNAT or specific telco DNS resolvers occasionally cache stale records longer), test from a phone off Wi-Fi as well.
Test the runbook when nothing is on fire
The fastest way to find gaps in a runbook is to hand it to a teammate—or read it yourself a month later—and walk through it on a staging environment. Every time they ask “Which SSH user?”, “Where are the Nginx logs stored?”, or “How do I undo this if it fails?”, add that one line to the document.
Review the runbook whenever you migrate hosting, change a deployment pipeline, or swap a reverse proxy. An outdated command in a runbook is worse than a blank page because it wastes precious minutes when things are already broken. Close every real incident with a three-line handoff note—what broke, what changed, and what needs follow-up—so the next person on call isn’t starting from zero.
For related guides that complement this checklist, see:
- A Better Website Search Starts With Better Content Paths
- A Project Handoff Checklist That Lets the Next Person Actually Run the Work
- How to Build a Software Inventory You Can Actually Maintain