Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(devops): describe the backup the shipped script takes

Yudhi Armyndharis6ec3d854aa3f
diff --git a/docs/05-database-design.md b/docs/05-database-design.md
index 671259d54..28bcc7b12 100644
--- a/docs/05-database-design.md
+++ b/docs/05-database-design.md
@@ -970,50 +970,10 @@ The 24-hour TTL itself is a fixed constant (`STATUS_TTL_MS`) and is not configur
## 5.8 Backup Strategy
> [!NOTE]
-> This section is **operational guidance**, not a built-in feature. OpenWA ships no scheduler, encryption step, or S3 uploader for backups — the diagram and script below are a recommended setup you wire up externally (cron, your host's backup tooling, etc.). For SQLite, back up the `./data/*.sqlite` files (including `./data/main.sqlite`); for PostgreSQL, use `pg_dump`. The JSON export/import endpoints in §5.1 are a portability path, not a backup mechanism.
+> This section is **operational guidance**, not a built-in feature. OpenWA ships no scheduler, encryption step, S3 uploader or pruning for backups; wire those up externally (cron, your host's backup tooling, etc.). The JSON export/import endpoints in §5.1 are a portability path, not a backup mechanism.
> The authoritative full-system backup is [`scripts/backup.sh`](../scripts/backup.sh), documented in the [operational runbook](./11-operational-runbooks.md#runbook-database-backup); it also captures engine auth state, including `BAILEYS_AUTH_DIR` for Baileys.
-### Backup Components
-
-```mermaid
-flowchart TB
- subgraph Backup["Backup Strategy"]
- DB[(Database)] --> DUMP[pg_dump]
- DUMP --> COMPRESS[Compress]
- COMPRESS --> ENCRYPT[Encrypt]
- ENCRYPT --> S3[S3/Cloud Storage]
- end
-
- subgraph Schedule["Schedule (external, e.g. cron)"]
- FULL[Full Backup<br/>Daily]
- INCR[Incremental<br/>Hourly]
- end
-
- Schedule --> Backup
-```
-
-### Backup Script Example
-
-```bash
-#!/bin/bash
-# backup.sh
-
-DATE=$(date +%Y%m%d_%H%M%S)
-BACKUP_DIR="/backups"
-DB_NAME="openwa"
-
-# Create backup
-pg_dump -Fc $DB_NAME > $BACKUP_DIR/openwa_$DATE.dump
-
-# Compress
-gzip $BACKUP_DIR/openwa_$DATE.dump
-
-# Upload to S3 (optional)
-aws s3 cp $BACKUP_DIR/openwa_$DATE.dump.gz s3://backups/openwa/
-
-# Cleanup old backups (keep last 7 days)
-find $BACKUP_DIR -name "*.dump.gz" -mtime +7 -delete
-```
+Build any scheduled or off-site pipeline around the archive `scripts/backup.sh` writes, not around a bare `pg_dump` or a copy of the `.sqlite` files. The data store alone omits `main.sqlite` (API keys and the audit log) and the engine auth state, so a restore from it comes back with no API keys and every session unpaired. The flow, and which steps stay with the operator, is in [10.7 Backup & Recovery](./10-devops-infrastructure.md#107-backup--recovery).
---
diff --git a/docs/10-devops-infrastructure.md b/docs/10-devops-infrastructure.md
index c3d378439..ea859adb0 100644
--- a/docs/10-devops-infrastructure.md
+++ b/docs/10-devops-infrastructure.md
@@ -1142,20 +1142,39 @@ These are the metrics OpenWA actually exports at `GET /api/metrics`:
### Backup Strategy
+`scripts/backup.sh` writes one local, unencrypted archive per run, created under `umask 077`. It does
+not schedule itself, encrypt, copy off-host or prune: a schedule, encryption at rest, an off-site copy
+and retention are the operator's to set up around the archive (see the
+[backup runbook](./11-operational-runbooks.md#runbook-database-backup)).
+
```mermaid
flowchart TB
- subgraph Daily["Daily Backup"]
- DB[(Database)] --> DUMP[pg_dump]
- DUMP --> COMPRESS[gzip]
- COMPRESS --> ENCRYPT[encrypt]
- ENCRYPT --> S3[S3 Storage]
+ subgraph Script["scripts/backup.sh (one run)"]
+ MAIN[(main.sqlite)] --> SNAP[sqlite3 .backup]
+ DATA[(data store)] --> SNAP
+ DATA -. DATABASE_TYPE=postgres .-> DUMP[pg_dump]
+ STATE["sessions/, baileys/, media/,<br/>plugin-packages/, plugin-state/,<br/>.env.generated, .api-key"] --> COPY[copy]
+ SNAP --> STAGE[staging dir]
+ DUMP --> STAGE
+ COPY --> STAGE
+ STAGE --> TAR[tar -czf + min-content check]
+ TAR --> ARCHIVE["BACKUP_DIR/openwa-backup-TIMESTAMP.tar.gz"]
end
- subgraph Retention["Retention Policy"]
- D7[Daily: 7 days]
- W4[Weekly: 4 weeks]
- M12[Monthly: 12 months]
+ subgraph Operator["Operator-managed (not in the script)"]
+ CRON[schedule, e.g. cron]
+ ENC[encryption at rest]
+ OFF[off-host copy]
+ PRUNE[retention]
end
+
+ ARCHIVE --> Operator
+```
+
+A retention step matching the script's default location and name, for example 30 days:
+
+```bash
+find ./backups -name 'openwa-backup-*.tar.gz' -mtime +30 -delete
```
### Backup Script