Runbook Generator#

Generate operational runbooks by scanning project infrastructure files. Produces structured Markdown runbooks with procedures for common ops tasks.

Quick Generate#

bash

python3 scripts/generate_runbook.py /path/to/project

Output Formats#

bash

# Markdown (default)
python3 scripts/generate_runbook.py /path/to/project

# JSON (structured)
python3 scripts/generate_runbook.py /path/to/project --format json

# Specific output file
python3 scripts/generate_runbook.py /path/to/project -o RUNBOOK.md

What It Scans#

FileWhat It ExtractsDockerfileBase image, exposed ports, entrypoint, build stepsdocker-compose.ymlServices, ports, volumes, dependencies, env varssystemd units (.service)ExecStart/Stop/Reload, dependencies, restart policyMakefileTargets (build, test, deploy, clean, etc.)package.jsonScripts (start, build, test, dev, deploy).env / .env.exampleRequired environment variablesnginx.confUpstream servers, listen ports, locations

Generated Sections#

1. Overview — Service name, description, tech stack
2. Prerequisites — Required tools, access, credentials
3. Environment Variables — Required vars with descriptions
4. Build — How to build the project
5. Deploy — Step-by-step deployment procedure
6. Start/Stop/Restart — Service lifecycle commands
7. Health Check — How to verify the service is running
8. Rollback — How to revert to previous version
9. Troubleshooting — Common issues and solutions
10. Monitoring — Logs, metrics, alerts
11. Contacts — On-call, escalation (template)

Workflow#

1. User points to a project directory
2. Script scans for infrastructure files
3. Extracts operational information
4. Generates structured runbook
5. Present to user for review and customization