Incident Response Best Practices for Solo Dev Teams
Summary
Building incident response tooling as a solo dev does not require PagerDuty pricing or enterprise runbooks. The core of incident response best practices fits in three things: know when something broke, know what to do, and tell your users about it. This guide covers what to build, what to wire together, and what to skip until you actually hit enough traffic to justify the complexity.
Incident response best practices get written for enterprise teams, not solo devs. You ship a side project, it finds users, and one morning someone tweets it has been down for three hours. You did not know. No alerting. No runbook. No status page.
That is the failure mode for 90% of solo-built products. Not a breach, not a catastrophic infrastructure event, just: nobody told you it was broken, you had no plan, and your users found out before you did.
This does not require a 40-page playbook or an enterprise tool stack. It requires three things: know when something broke, know what to do about it, and communicate status to anyone who cares. This guide covers each one from a builder's perspective, including what to build yourself and what to wire together from existing tools.
What breaks first when you are solo and on-call
The first incident you manage solo, you will spend 12 minutes figuring out where things are before you spend 4 minutes actually fixing them.
That is the real cost. Not downtime. The coordination overhead of a one-person team who has not written anything down. Where are the environment variables? Which service is actually failing? Does this affect all users or just one customer? You spend the golden window of an incident searching for answers you should have pre-answered.
The fix is not complex tooling. It is having answered those questions before 3 AM.
There is a useful test: imagine your production API goes down right now. You have 10 minutes. Can you find the relevant logs, identify the failing component, and roll back or hotfix without opening more than two tabs you did not already have open? If the answer is no, that is exactly what incident response solves for.
The three things every indie incident response setup actually needs
Before you build anything, name what the system has to do:
Detect the problem before a user DMs you about it
Tell you what to do when you are half-asleep and only have context from the alert
Tell your users what is happening without making it worse
Every incident response tool, from PagerDuty to your own cron job, maps to one of these three jobs. Build the simplest version that does all three, then stop.
The temptation is to build toward the enterprise version: on-call schedules, escalation policies, severity levels P0 through P5, postmortem templates. That is appropriate at 20 engineers and 500K users. At one dev and 500 users, those abstractions burn your weekends and stay unused. The minimal version is faisable this weekend. Ship that first.
Building your alerting layer: the false positive problem comes first
Every dev who has built their own alerting has the same story: the first rule they wrote was wrong, and they turned off the pager after two weeks of noise.
Start with one check that matters. A failing health check endpoint is enough.
# Simple health check endpoint (Express/Node)
app.get('/health', (req, res) => {
res.json({ status: 'ok', timestamp: Date.now() });
});Then wire a cron job to ping it every 60 seconds. If it fails three consecutive times, you get a text. That is your first alerting layer. It catches 80% of the incidents that affect users.
The false positive rate on this setup is near zero. You get paged when the service is actually down, not when a CPU spike triggered a threshold that was never calibrated. That is the hardest thing to get right in alerting: the alert has to be true, every time, or you train yourself to ignore it.
Log-based alerting comes after the uptime check is working and trusted. For self-hosted stacks, Grafana handles this well at lower cost. Datadog starts making sense when you are managing more than two or three services and want a unified view with easy integration to your deployment pipeline.
Runbooks are the document you write at 11 PM to read at 3 AM
A runbook is not documentation. Documentation explains how something works. A runbook tells a future version of you who is stressed, barely awake, and under pressure exactly what to do right now.
The format that works for solo projects:
What is broken? One sentence, observable symptoms only
Is it urgent? Does it affect paying customers right now?
What do I do? Three to five numbered steps, starting with the fastest thing to try first
That is it. Write it when you are not in an incident. Review and update it after an incident to see if it was actually useful.
Where you store runbooks matters less than the habit of writing them. A Notion page, a Markdown file in your repo, a shared doc. The test: can you open it on your phone in 30 seconds, half-awake, at 3 AM?
The practical argument for Notion over a repo file is mobile access. If you are sleeping next to your phone because you have production traffic and a bad feeling about a deploy you just shipped, that matters. GitBook is another solid option if you prefer something more structured that doubles as public developer docs.
Building a public status page: what users actually want when things break
Your users do not need a real-time observability dashboard. They need to know two things: is it broken for everyone, and are you aware of it?
The minimum viable status page has three elements:
A status indicator with at most three states: operational, degraded, down
A timestamp for when the current state was last updated
One line of plain English when something is wrong
Users checking a status page during an incident are not reading architecture diagrams. They want to stop troubleshooting their own setup because they now know it is not them.
Building this takes under four hours:
A static HTML page with a JavaScript snippet that fetches status from an endpoint
A Supabase table with two fields:
status(enum) andmessage(text)A cron job that updates the status based on your health check result
An admin endpoint behind auth to write a manual message when needed
The hard part is not the build. It is the habit of updating it during an incident instead of diving straight into the fix. The update takes 30 seconds and saves 15 customer support emails.
The other argument for building this yourself: commercial status page tools charge $30 to $100 per month for what is fundamentally a JSON endpoint and a static HTML page. Build it once, own it. Your users do not need Statuspage.io. They need a URL that still works when your main domain goes down.
Post-mortems when you are the only person to blame
Post-mortems in enterprise settings are about not blaming individuals and identifying systemic failures. Solo, you are the system. The psychology is different, but the practice still matters.
The reason to write post-mortems alone: you will solve the same class of problem twice if you do not. Three months later you will be looking at a database query that locked because of an index you did not add, and you will have a vague memory of fixing something like this before, but not remember what.
A five-minute format that holds up:
What happened (one paragraph, facts only, no blame language)
What you did to fix it
One thing to change in the system
One thing to change in your process
Write it in the same place as your runbooks. It becomes the input for the next runbook update. Over six months, this creates a lightweight record of your system's failure modes that no enterprise postmortem tool replicates for a solo builder.
Should you build this or stitch existing tools together?
The honest answer depends on where you are.
If you have zero paying customers: build the whole thing yourself. Health check cron, status page, Notion runbooks. This is the right project to learn the patterns. It ships in a weekend. It teaches you what incident response actually requires. And if you decide later to build and sell it as a product, you have validated the requirements on yourself first.
If you have paying customers who depend on uptime today: start with existing tools. Wire Grafana Cloud free tier, set up an uptime monitor, and open a Notion runbook page this afternoon. You need coverage now, not after three weekends of building.
The piece worth building yourself regardless of stage: the status page. Own it, host it on a separate domain, build it this weekend. Everything else you can stitch together from existing free tiers until the complexity justifies building it.
The gap no incident response guide talks about
The problem is not tooling. It is the 48 hours between "I should set up alerting" and "I actually set up alerting."
Most solo dev stacks have enough observability primitives to build a first incident response layer in a single day. The health check endpoint exists somewhere. The logs are somewhere. The deploy pipeline has some error handling. What is missing is 90 minutes of focused wiring: health check to uptime monitor, uptime monitor to SMS or Telegram alert, one Notion page with three runbooks, static page with a Supabase status endpoint.
This is not the project you ship to users. This is the project you ship for yourself.
Build it this weekend. The first time something breaks at 3 AM and you spend 4 minutes fixing it instead of 40 minutes finding it, you will understand why incident response best practices exist. Not because enterprise teams mandated it, but because the alternative is worse.