Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

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.md
index 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 Hazards
export 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 services
docker 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 image
git 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 authenticates
diff --git a/docs/12-troubleshooting-faq.md b/docs/12-troubleshooting-faq.md
index 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. Apply
retention/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.md
index 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) |