Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs: correct the backup and rollback steps for volume and Postgres
Yudhi Armyndharis282ee0e08368
diff --git a/docs/11-operational-runbooks.md b/docs/11-operational-runbooks.mdindex 1197916d2..6544e9ab5 100644--- a/docs/11-operational-runbooks.md+++ b/docs/11-operational-runbooks.md@@ -349,8 +349,11 @@ docker stats --no-stream# 2. Notify users (via webhook or external system)# Send maintenance notification-# 3. Create backup-./scripts/backup.sh+# 3. Create a backup in the running container, where the data is mounted, and copy it off the+# volume (see Runbook: Database Backup). A host run of ./scripts/backup.sh archives ./data in the+# checkout, which only a bare-metal install or docker-compose.dev.yml reads+docker exec -e BACKUP_DIR=/app/data/backups -e TMPDIR=/app/data/backups openwa-api ./scripts/backup.sh+docker cp openwa-api:/app/data/backups/. ./backups/# Verify backup (backup.sh writes $BACKUP_DIR/openwa-backup-<timestamp>.tar.gz,# BACKUP_DIR defaults to ./backups — it creates no dated subdirectories)@@ -425,7 +428,8 @@ curl -H "X-API-Key: $API_KEY" \# 2. Create a backup in the running container, where the data is mounted, then copy it to# $BACKUP_DIR as openwa-backup-<timestamp>.tar.gz, where the Rollback block reads it. Both compose# files name the container openwa-api. Running ./scripts/backup.sh on the host instead archives-# ./data in the checkout, which the production compose never reads (see Runbook: Database Backup)+# ./data in the checkout, which the production compose never reads (see Runbook: Database Backup).+# An image older than 0.19.0 has no scripts/backup.sh: see 14 - Known Upgrade Hazardsexport BACKUP_DIR="/backups/openwa"mkdir -p "$BACKUP_DIR"docker exec -e BACKUP_DIR=/app/data/backups -e TMPDIR=/app/data/backups openwa-api ./scripts/backup.sh@@ -507,7 +511,8 @@ curl -H "X-API-Key: $API_KEY" \# 1. Stop servicesdocker compose down-# 2. Restore from the pre-upgrade backup (both DBs + sessions). The archive upgrade step 2 produced is+# 2. Restore from the pre-upgrade backup (main.sqlite, a SQLite data store and the auth state). The+# archive upgrade step 2 produced is# "$BACKUP_DIR/openwa-backup-<timestamp>.tar.gz". The databases in place still hold the failed# upgrade's data, so the restore refuses to touch them without --force. That state is not lost: it# is kept in "$BACKUP_DIR/data.pre-restore-<ts>", the path the script prints. It runs in the image@@ -518,6 +523,11 @@ docker compose run --rm --no-deps --entrypoint /app/scripts/restore.sh \-v "$BACKUP_DIR:/backups" -e OPENWA_RESTORE_SNAPSHOT_DIR=/backups -e TMPDIR=/backups -e HOME=/tmp \openwa-api /backups/openwa-backup-<timestamp>.tar.gz --force+# On a PostgreSQL data store, step 2 leaves the upgraded database in place. Load the pre-upgrade dump+# into an empty database: replayed over the upgraded tables, its CREATE statements fail and its rows+# mix with theirs+tar -xzOf "$BACKUP_DIR/openwa-backup-<timestamp>.tar.gz" ./database.sql | psql "$DATABASE_URL"+# 3. Check out the previous release and rebuild the imagegit checkout v<old-version>docker compose build openwa-api@@ -670,7 +680,8 @@ docker compose down# refuses to overwrite them)./scripts/restore.sh ./backups/openwa-backup-<timestamp>.tar.gz-# 3. (Postgres only) the archive contains database.sql — import it manually:+# 3. (Postgres only) the archive contains database.sql — import it manually into an empty+# database (its CREATE statements fail against tables that already exist):# psql "$DATABASE_URL" < ./data/database.sql# 4. Start the app and CONFIRM an existing API key still authenticatesdiff --git a/docs/12-troubleshooting-faq.md b/docs/12-troubleshooting-faq.mdindex a6a8846a0..32d35ccb6 100644--- a/docs/12-troubleshooting-faq.md+++ b/docs/12-troubleshooting-faq.md@@ -1347,10 +1347,18 @@ Remember OpenWA is **single-port**: the Dashboard, REST API, and Socket.IO all s**Q: How to backup sessions automatically?**```bash-# Add to crontab, for example: 0 */6 * * * cd /path/to/openwa && ./scripts/backup.sh-BACKUP_DIR=/backups/openwa ./scripts/backup.sh+# Production compose, whose data is the openwa-data volume: back up inside the container, then copy+# the archive off the volume. In crontab, for example every six hours:+# 0 */6 * * * docker exec -e BACKUP_DIR=/app/data/backups -e TMPDIR=/app/data/backups openwa-api ./scripts/backup.sh && docker cp openwa-api:/app/data/backups/. /backups/openwa/+docker exec -e BACKUP_DIR=/app/data/backups -e TMPDIR=/app/data/backups openwa-api ./scripts/backup.sh+docker cp openwa-api:/app/data/backups/. /backups/openwa/++# Bare metal or docker-compose.dev.yml, whose data is ./data in the checkout:+# 0 */6 * * * cd /path/to/openwa && BACKUP_DIR=/backups/openwa ./scripts/backup.sh```+The archives stay in `/app/data/backups` on the volume as well, so prune them there too.+The shipped script also covers `main.sqlite`, the selected data store, whatsapp-web.js state,`BAILEYS_AUTH_DIR` (default `./data/baileys`), media, plugin packages/state, and generated secrets. Applyretention/encryption to completed archives externally; see the [backup and restore runbooks](./11-operational-runbooks.md#runbook-database-backup).diff --git a/docs/14-migration-guide.md b/docs/14-migration-guide.mdindex c39895635..03b9ade16 100644--- a/docs/14-migration-guide.md+++ b/docs/14-migration-guide.md@@ -796,6 +796,7 @@ docker compose run --rm openwa-api npm run migration:run:prod| `0.21.0` | The ingress route gained a per-client-IP rate bound (`INGRESS_IP_LIMIT`, default 1200 per window) alongside its per-instance one; previously the route had no bound a caller could not walk around by varying the path | Raise `INGRESS_IP_LIMIT` if one provider IP legitimately drives more than 1200 ingress requests per window || `0.20.0` | With `WEBHOOK_SSRF_PROTECT=false`, deliveries no longer follow redirects, and `SSRF_ALLOWED_HOSTS` entries pin to their resolved addresses (must resolve at registration) | Set `WEBHOOK_SSRF_REDIRECTS=true` for a receiver legitimately behind a 3xx; ensure allowlisted hostnames resolve when the webhook is saved || `0.20.0` | Plugin installs from a URL require a `#sha256=<64 hex>` pin under `NODE_ENV=production` (the compose default) | Pin catalog URLs, or set `PLUGIN_INSTALL_REQUIRE_PIN=false` to lift the requirement |+| `0.19.0` | Older images ship no `scripts/backup.sh`, so step 1 of the upgrade script fails on a 0.18.x or earlier container, before anything is stopped | Stop the app and archive the volume: `docker run --rm -v openwa_openwa-data:/data:ro -v "$PWD/backups:/o" alpine tar czf /o/data.tgz -C /data .`, with a `pg_dump` of a PostgreSQL data store. To roll back, extract it into the emptied volume || `0.19.0` | Production boot refuses a set `API_MASTER_KEY` shorter than 32 characters | Strengthen a short key before upgrading; unset stays allowed (first boot generates one) || `0.19.0` | `POST /sessions/:id/messages/send-catalog` and `PUT /api/settings` are removed (both always answered `501`) | Drop calls to either; catalog reads and `GET /api/settings` are unchanged || `0.18.0` | `NODE_ENV` outside `production`/`development`/`test` fails boot with a named error | Set a legal value or unset it (unset remains valid) |