demo.runbook

---
name: Getting Started Demo
version: 1.0.0
description: |
  A self-contained runbook you can run immediately — no external services,
  no Docker, no cloud credentials. It simulates a full deployment workflow
  (backup → migrate → deploy → verify → cleanup) using only standard Unix
  shell tools and a temporary directory.

  Every feature is demonstrated: check blocks, step blocks with rollback,
  a wait block with health polling, depends_on chaining, confirm gates,
  environment filters, kill_grace, and built-in template variables.
owners: [you]
environments: [staging, production]
timeout: 5m
---

# Getting Started Demo

This runbook simulates deploying **{{runbook_name}}** version
**{{runbook_version}}** to **{{env}}**.

All state is written to `/tmp/runbook-demo-{{run_id}}/` and cleaned up at
the end. The run ID `{{run_id}}` is unique to each execution, so concurrent
runs do not interfere.

Run it with:

```bash
# Staging (no confirmation prompts)
runbook run demo.runbook --env staging

# Production (prompts before deploy)
runbook run demo.runbook --env production
```

---

## Prerequisites

```check name="tmp-writable"
test -w /tmp
echo "/tmp is writable"
```

```check name="env-recognised"
./scripts/check-env.sh "{{env}}"
```

---

## Step 1 — Set Up Workspace

Creates the temporary workspace that represents the running service.

```step name="setup-workspace" rollback="teardown-workspace"
  timeout: 10s
---
./scripts/setup-workspace.sh "{{run_id}}" "{{runbook_version}}"
```

```rollback name="teardown-workspace"
./scripts/teardown-workspace.sh "{{run_id}}"
```

---

## Step 2 — Back Up Current State

Snapshot the service version and database state before making any changes.
If anything goes wrong after this point the rollback blocks below can
restore the system to exactly this snapshot.

```step name="backup-state" depends_on="setup-workspace"
  timeout: 10s
---
./scripts/backup-state.sh "{{run_id}}"
```

---

## Step 3 — Run Database Migration

Applies schema migration `0002_add_payments_table`. The rollback handler
restores the database snapshot taken in Step 2.

```step name="apply-migration" depends_on="backup-state" rollback="undo-migration"
  timeout: 30s
---
./scripts/apply-migration.sh "{{run_id}}"
```

```rollback name="undo-migration"
./scripts/undo-migration.sh "{{run_id}}"
```

---

## Step 4 — Deploy New Version

Simulates a graceful service restart: the old process is stopped with
`SIGTERM`, given 5 seconds to drain, then the new version is started.
`confirm: production` prompts for approval before this step runs in
production. The rollback handler re-pins the previous version.

```step name="deploy-version" depends_on="apply-migration" rollback="rollback-version"
  timeout: 30s
  confirm: production
  kill_grace: 5s
---
./scripts/deploy-version.sh "{{run_id}}" "{{runbook_version}}"
```

```rollback name="rollback-version"
./scripts/rollback-version.sh "{{run_id}}"
```

---

## Step 5 — Health Soak

Polls the service every 3 seconds for 15 seconds. Exits non-zero if
the service ever reports the wrong version, which triggers rollback of
all preceding steps.

```wait name="health-soak" duration="15s"
  abort_if: error_rate > 0%
---
./scripts/health-soak.sh "{{run_id}}" "{{runbook_version}}"
```

---

## Step 6 — Smoke Tests

Verifies the deployed version, migration log, and updated DB schema.

```step name="smoke-test" depends_on="deploy-version"
  timeout: 15s
---
./scripts/smoke-test.sh "{{run_id}}" "{{runbook_version}}"
```

---

## Step 7 — Extended Tests (staging only)

Runs additional integration checks that are safe to skip in production
because the confirmation gate and health soak already provide confidence.

```step name="extended-tests" depends_on="smoke-test"
  timeout: 15s
  env: [staging]
---
./scripts/extended-tests.sh
```

---

## Step 8 — Finalize

Prints a deployment summary and removes the temporary workspace.

```step name="finalize" depends_on="smoke-test" rollback="rollback-finalize"
  timeout: 10s
---
./scripts/finalize.sh "{{run_id}}" "{{runbook_name}}" "{{runbook_version}}" "{{env}}" "{{user}}" "{{timestamp}}"
```

```rollback name="rollback-finalize"
# teardown-workspace (the rollback for setup-workspace) will remove the
# workspace directory as part of the LIFO rollback chain, so there is
# nothing extra to undo here.
echo "Nothing to undo for finalize — workspace will be removed by teardown-workspace"
```