Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

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.md
index 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.sh
index 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, which
diff --git a/scripts/restore.sh b/scripts/restore.sh
index 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