Skip to content

OPERATIONS_RUNBOOK.md

Latest commit

 

History

History
160 lines (114 loc) · 5.09 KB

OPERATIONS_RUNBOOK.md

File metadata and controls

160 lines (114 loc) · 5.09 KB

Operations Runbook

This runbook is the operator checklist for the read-only Steam-Pulse MVP. It keeps routine actions, recovery steps and smoke checks in one place.

Operating principles

  • Keep the MVP read-only. Do not add Steam account actions or marketplace trading actions to operator flows.
  • Stop the worker before restore, migrations or manual database file changes.
  • Prefer dry-run commands before destructive storage cleanup.
  • Create a backup before maintenance, migrations or deploys that can change persisted data.
  • Treat marketplace 403, 429, CAPTCHA or antifraud responses as a signal to slow down or pause that adapter.

Pre-flight checks

Run these before first deployment, after config changes, and after dependency upgrades:

steam-pulse doctor --offline
steam-pulse status
steam-pulse storage stats
steam-pulse storage runs --limit 5
steam-pulse health

For real marketplace validation:

steam-pulse doctor --online --real
steam-pulse scan --real

If CSFloat or another external marketplace reports HTTP 403 or HTTP 429, keep the system in degraded mode, lower the adapter rate limit, configure credentials if required, or disable that adapter until access is resolved.

Routine operations

Daily quick check:

steam-pulse status
steam-pulse health
steam-pulse storage runs --limit 10
steam-pulse storage stats

Weekly or scheduled storage maintenance:

steam-pulse storage maintenance --dry-run
steam-pulse storage maintenance
steam-pulse storage stats

Maintenance creates a SQLite backup before deleting rows. Use --no-backup only when another verified backup already exists.

Scheduler strategy

For the production-ready read-only MVP, keep periodic maintenance on an external scheduler such as cron, systemd timer, Windows Task Scheduler, Docker host automation or orchestration primitives.

Use steam-pulse status or steam-pulse status --json as the compact operator snapshot for the host scheduler, dashboards or smoke checks. It reports the latest persisted scan run, marketplace health summary, retention settings and storage state without printing secrets.

Do not add persistent in-app scheduler state yet. That complexity starts to pay off only when schedules themselves become product data, multiple workers need coordinated leases, or missed-run recovery and backfill become first-class requirements.

Backup and restore

Create an explicit backup before deploys, migrations or manual cleanup:

steam-pulse storage backup --output backups/steam_pulse-before-change.db

Restore only after stopping the worker:

docker compose stop
steam-pulse storage restore --input backups/steam_pulse-before-change.db --confirm
steam-pulse storage stats
steam-pulse storage runs --limit 5

Restore validates the backup with SQLite PRAGMA integrity_check, checks that it is a Steam-Pulse database, and creates a pre-restore backup of the active database before replacing it.

Deploy procedure

  1. Stop or pause the worker.
  2. Create a backup with steam-pulse storage backup.
  3. Run local checks.
  4. Apply the deploy or config change.
  5. Run steam-pulse doctor --offline.
  6. Run one steam-pulse scan --demo or steam-pulse scan --real depending on the environment.
  7. Restart the worker and inspect steam-pulse storage runs --limit 5.

Local checks:

python -m pytest
python -m ruff check .
python -m mypy src
python -m pip check
docker compose config --quiet

Use quiet compose validation when local .env contains real secrets.

Incident triage

Marketplace degraded or in cooldown:

steam-pulse health
steam-pulse health --json

Review adapter config, reduce *_RPS, increase *_DEGRADED_COOLDOWN_SECONDS, or disable the adapter. After fixing credentials or profile settings, reset only the affected marketplace:

steam-pulse health reset csfloat

Database growth:

steam-pulse storage stats
steam-pulse storage maintenance --dry-run
steam-pulse storage maintenance

Bad deploy or bad migration:

docker compose stop
steam-pulse storage restore --input backups/steam_pulse-before-change.db --confirm
docker compose up -d

Telegram alerts not arriving:

steam-pulse doctor --offline
steam-pulse telegram chats
steam-pulse telegram test
steam-pulse scan --demo --send-alerts

Verify STEAM_PULSE_TELEGRAM_ENABLED, STEAM_PULSE_TELEGRAM_BOT_TOKEN and STEAM_PULSE_TELEGRAM_CHAT_ID in the runtime environment. Do not print token values in logs or tickets.

CLI smoke test

Use a temporary database for a safe local smoke test:

$env:STEAM_PULSE_DATABASE_URL="sqlite:///data/steam_pulse-smoke.db"
steam-pulse doctor --offline
steam-pulse scan --demo
steam-pulse storage stats
steam-pulse storage runs --limit 5
steam-pulse storage maintenance --dry-run --json
Get-ChildItem data -Filter 'steam_pulse-smoke.db*' -ErrorAction SilentlyContinue | Remove-Item -Force -ErrorAction SilentlyContinue

The smoke test should not call real marketplaces unless --real or doctor --online --real is used explicitly.