Runbooks

Step-by-step operational procedures — as opposed to docs/architecture.md, which is the design spec, or CONTRIBUTING.md, which is the engineering rules. A runbook is what you actually run, in order, to get a specific outcome.

If you are integrating an application rather than running or operating vsms, ../integrating.md is the guide you want instead.

Runbook	For
Local development	Daily development: just demo brings the whole stack up against a fake carrier, with no Orange or MTN account and no real SMS. Credentials per developer, fault injection, and troubleshooting.
Showcase	The fastest way to see vsms working with no source build: compose.demo.yaml pulls every image from GHCR and brings up a console you can open, with a message reaching a terminal state. Not for development — see compose.demo.yaml's own header for how it differs from just demo and from Deployment.
Getting started	First-time setup, the long way: clone, build, apply migrations, run both binaries by hand, send a real message through the whole pipeline against a scratch database. Read this when something in just demo fails and you need to know which link broke.
Testing	just ci runs the ENTIRE CI gate — every job .github/workflows/ci.yml runs — with nothing on the host but docker, docker compose and just. Start here to verify a change before opening a PR.
Deployment	Running it for real: the compose stack, the Caddy edge, the one-shot migration job, image builds and the GHCR release path.
Sending through AWS End User Messaging SMS	Using aws_sms as a provider, the go-live route while the Orange and MTN contracts are pending: the data-residency prerequisite (sending to AWS is a cross-border transfer), the AWS resources to create (sandbox exit, sender ID, SNS topic with SignatureVersion 2, configuration set, IAM user), the manual subscription confirmation, a delivery policy and dead-letter queue, the worker and gateway settings, seeding an AWS-only deployment, routing between AWS and the operator routes, and troubleshooting. Not yet run against a live AWS account.
Backup and restore	The backup job, and the restore drill that proves a backup is actually restorable.
#36 — real handset delivery gate	The milestone 2 acceptance gate: a real SMS to a real Orange handset, and a kill -9 lease-reclaim proof. Needs real Orange Cameroon credentials and a real phone — not runnable in CI or by an agent.
#160 — the joined integration story	just e2e-integration (the scripts/e2e-integration.sh this used to be is gone — see AGENTS.md’s "containerize-tooling" section): an external client (examples/rust/sms-send) sends over real HTTP, and that exact message id is read back through the admin console’s own data path and credential, reaching delivered. Proves integration readiness, not carrier readiness — #36 above is unaffected.
#70/#71 — alerting	What each of the five Prometheus alerts in deploy/prometheus/alerts.yml means and what to do when it fires, plus how to correlate one message across sms-gateway and sms-worker's logs end to end.