Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs(scripts): describe the real path resolution of backup and restore
Yudhi Armyndharisa7aae6d1aa03
diff --git a/docs/11-operational-runbooks.md b/docs/11-operational-runbooks.mdindex 4ec0da325..9cc9b9ce3 100644--- a/docs/11-operational-runbooks.md+++ b/docs/11-operational-runbooks.md@@ -609,16 +609,17 @@ User-managed files outside that list (for example the project-level `.env`) must# - plugin-packages/ — installed plugin code from PLUGINS_DIR# (not packages in a legacy ./plugins, which the app still loads while# PLUGINS_DIR is unset; backup.sh warns about those)-# - plugin-state/ — registry + ctx.storage state under OPENWA_DATA_DIR+# - plugin-state/ — registry + ctx.storage state under PLUGIN_STATE_DIR/plugins+# (default: <OPENWA_DATA_DIR>/plugins)# - .env.generated / .api-key — generated configuration and bootstrap secret# (.api-key from BOOTSTRAP_KEY_FILE when that is set)#-# The database paths resolve exactly like the app: the explicit MAIN_DATABASE_NAME /-# DATABASE_NAME env path wins, otherwise the fixed ./data defaults — they are NOT derived from-# OPENWA_DATA_DIR. A missing source database fails the run (no silent empty backup), the finished-# archive is checked to contain every configured database, and with the sqlite3 CLI present the-# databases are snapshotted online via .backup (otherwise plain-copied with a CONSISTENCY-WARNING-# marker inside the archive).+# The database paths resolve exactly like the app: MAIN_DATABASE_NAME / DATABASE_NAME from the+# environment, then ./.env, then <data dir>/.env.generated, otherwise the fixed ./data defaults — they+# are NOT derived from OPENWA_DATA_DIR. A missing source database fails the run (no silent empty+# backup), the finished archive is checked to contain every configured database, and with the sqlite3+# CLI present the databases are snapshotted online via .backup (otherwise plain-copied with a+# CONSISTENCY-WARNING marker inside the archive).# Run from the repo root (database defaults are ./data/...; state dirs follow OPENWA_DATA_DIR):./scripts/backup.sh@@ -703,7 +704,8 @@ docker compose down# 2. Restore from an archive produced by scripts/backup.sh# (databases land on MAIN_DATABASE_NAME / DATABASE_NAME, default ./data/... — the same paths-# the app reads; non-DB state follows OPENWA_DATA_DIR. Pass --strict to refuse an archive+# the app reads, as the environment, ./.env or the archive's .env.generated set them; non-DB+# state follows OPENWA_DATA_DIR. Pass --strict to refuse an archive# whose CONSISTENCY-WARNING marker reports plain-copied, possibly-torn database snapshots.# Restoring over an existing install's live databases requires --force; without it the script# refuses to overwrite them)diff --git a/scripts/backup.sh b/scripts/backup.shindex ceec7653a..9bd310f89 100755--- a/scripts/backup.sh+++ b/scripts/backup.sh@@ -12,7 +12,8 @@# (unreachable, or no credentials); the bucket's contents are not archived and# need a backup of their own# - plugin-packages/ — installed plugin packages from PLUGINS_DIR-# - plugin-state/ — registry and persisted ctx.storage state under OPENWA_DATA_DIR+# - plugin-state/ — registry and persisted ctx.storage state under PLUGIN_STATE_DIR/plugins+# (default: <data dir>/plugins)# - .env.generated and .api-key — dashboard config and plaintext bootstrap admin key## The previous runbook backed up the wrong file (openwa.db) and omitted main.sqlite,@@ -32,7 +33,10 @@# DATABASE_TYPE sqlite (default) | postgres# SESSION_DATA_PATH, BAILEYS_AUTH_DIR, STORAGE_LOCAL_PATH, PLUGINS_DIR# override the corresponding state directories+# PLUGIN_STATE_DIR root whose plugins/ holds the plugin registry and ctx.storage (default: the+# data dir)# BOOTSTRAP_KEY_FILE the plaintext admin key to archive (default: <data dir>/.api-key)+# These paths resolve through the same layers as the databases.# For postgres: DATABASE_URL, or DATABASE_HOST/PORT/USERNAME/PASSWORD/NAME# DATABASE_URL is read by this script only (the app uses the DATABASE_* keys)# and wins over them when set. It is passed to pg_dump as an argument, whichdiff --git a/scripts/restore.sh b/scripts/restore.shindex a01eae4df..686d0d1bc 100755--- a/scripts/restore.sh+++ b/scripts/restore.sh@@ -17,14 +17,18 @@# Environment:# MAIN_DATABASE_NAME restore target for the auth/audit DB (default: ./data/main.sqlite)# DATABASE_NAME restore target for the SQLite data store (default: ./data/openwa.sqlite)-# Both resolve EXACTLY like the app (src/config/configuration.ts): the-# explicit env path wins, otherwise the fixed ./data default. They are NOT-# derived from OPENWA_DATA_DIR — restoring there would write databases the-# app never reads (fresh-empty boot + new master key).+# Both resolve EXACTLY like the app: the environment first, then ./.env, then+# .env.generated (the archive's copy when it carries one, else the data dir's),+# otherwise the fixed ./data default (see lib-env.sh). They are NOT derived+# from OPENWA_DATA_DIR — restoring there would write databases the app never+# reads (fresh-empty boot + new master key).# OPENWA_DATA_DIR data directory to restore non-DB state into (default: ./data)# SESSION_DATA_PATH, BAILEYS_AUTH_DIR, STORAGE_LOCAL_PATH, PLUGINS_DIR# override the corresponding state directories+# PLUGIN_STATE_DIR root whose plugins/ holds the plugin registry and ctx.storage (default: the+# data dir)# BOOTSTRAP_KEY_FILE where the plaintext admin key goes (default: <data dir>/.api-key)+# These paths resolve through the same layers as the databases.# OPENWA_RESTORE_SNAPSHOT_DIR# where the safety snapshots go (default: next to the data dir, and next to# each target outside it); needed when a parent is read-only, as in the