Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(scripts): resolve app-relative paths from the data directory in host runs (#1784)

Yudhi Armyndharisbdf955a8f93e
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 200ffd477..a7c767b8e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -24,6 +24,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Fixed
+- Resolve `./data/...` paths from `.env.generated` under `OPENWA_DATA_DIR` in host-side `backup.sh` and `restore.sh` runs.
- Stop `backup.sh` and `restore.sh` on an env line they cannot parse instead of falling back to the default path.
- Verify the PostgreSQL server certificate in `backup.sh` when `DATABASE_SSL=true`, as the app does.
- Dead-letter undispatched ingress events instead of deleting them when they age out of the dedup window.
diff --git a/docs/11-operational-runbooks.md b/docs/11-operational-runbooks.md
index fcc6b53f9..b5bd91bc2 100644
--- a/docs/11-operational-runbooks.md
+++ b/docs/11-operational-runbooks.md
@@ -674,7 +674,7 @@ User-managed files outside that list (for example the project-level `.env`) must
# (.api-key from BOOTSTRAP_KEY_FILE when that is set)
#
# 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
+# environment, then ./.env, then <data dir>/.env.generated, otherwise the fixed ./data defaults, which
# 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
@@ -682,7 +682,8 @@ User-managed files outside that list (for example the project-level `.env`) must
# whatsapp-web.js profile is open or Baileys state is present, the archive carries an
# ENGINE-STATE-NOTE naming them, which restore.sh prints and never refuses.
-# Run from the repo root (database defaults are ./data/...; state dirs follow OPENWA_DATA_DIR):
+# Run from the repo root (database defaults are ./data/... there; other state defaults to
+# OPENWA_DATA_DIR; a ./data/... path from .env.generated, database paths included, is read under it):
./scripts/backup.sh
# Customize via environment. Keep the password out of DATABASE_URL: the URL is passed to pg_dump as
@@ -726,9 +727,16 @@ OPENWA_DATA_DIR=/srv/openwa/data \
> first, then `./.env`, then `<data dir>/.env.generated`. Settings made through Dashboard >
> Infrastructure therefore apply without being restated on the command line. A restore reads that
> third layer from the archive's `.env.generated` when the archive carries one, because that copy
-> replaces the target's and is the one the restored app reads. When operating directly on the host
-> mount, a path recorded inside the container (`/app/data/...`) is not host-visible, so override it in
-> the environment.
+> replaces the target's and is the one the restored app reads. A relative `./data/...` path in
+> `.env.generated`, such as the `STORAGE_LOCAL_PATH=./data/media` the app writes on first run, names a
+> path in the data directory and is read under `OPENWA_DATA_DIR`; one from the environment or `./.env`
+> is read against the current directory. When operating directly on the host mount, a path recorded
+> inside the container (`/app/data/...`) is not host-visible, so override it in the environment. The
+> database defaults are relative to the current directory too, so pass `MAIN_DATABASE_NAME` and, for
+> SQLite, `DATABASE_NAME` with their paths on the mount. A `./data/...` path in `./.env` needs the same
+> override, such as the `PLUGINS_DIR=./data/plugins` that `.env.example` sets: compose passes it to
+> the container, where it names a path in the volume, while the scripts read it against the current
+> directory.
>
> On every install, inside a container or not, a quoted value followed by a `#` comment or not
> closed on its line, a quoted value containing its own quote character or ending in a backslash, a
@@ -796,8 +804,9 @@ 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, 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;
+# state defaults to OPENWA_DATA_DIR; a ./data/... path from .env.generated, database paths
+# included, is read under it. Pass --strict to refuse an archive whose CONSISTENCY-WARNING
+# marker reports plain-copied, possibly-torn database snapshots;
# an ENGINE-STATE-NOTE (engine auth state that may have been copied while the app ran) is only printed.
# 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 ad9bc0974..d859f4d7b 100755
--- a/scripts/backup.sh
+++ b/scripts/backup.sh
@@ -26,9 +26,10 @@
# DATABASE_NAME data-store SQLite file (default: ./data/openwa.sqlite; sqlite only)
# Both resolve EXACTLY like the app: the environment first, then ./.env, then
# <data dir>/.env.generated, otherwise the fixed ./data default (see
-# lib-env.sh). They are NOT derived from OPENWA_DATA_DIR — the app never does
-# that either.
-# OPENWA_DATA_DIR data directory for the non-DB state below (default: ./data)
+# lib-env.sh). The defaults are NOT derived from OPENWA_DATA_DIR, as the app
+# never does that either.
+# OPENWA_DATA_DIR data directory for the non-DB state below (default: ./data); a ./data/...
+# path read from .env.generated, database paths included, is taken under it
# BACKUP_DIR where archives are written (default: ./backups)
# DATABASE_TYPE sqlite (default) | postgres
# SESSION_DATA_PATH, BAILEYS_AUTH_DIR, STORAGE_LOCAL_PATH, PLUGINS_DIR
@@ -77,32 +78,32 @@ TIMESTAMP="$(date +%Y%m%d-%H%M%S)"
# Database paths resolve exactly like the app: an explicit environment value wins, then ./.env, then
# the dashboard's <data dir>/.env.generated, otherwise the fixed ./data default. OPENWA_DATA_DIR
-# below only bases the non-DB state directories — deriving DB paths from it would back up files the
-# app never reads.
-MAIN_DB="$(openwa_resolve MAIN_DATABASE_NAME ./data/main.sqlite)"
+# bases the defaults of the non-DB state directories below and a ./data/... path from .env.generated,
+# never the database defaults: deriving those from it would back up files the app never reads.
+MAIN_DB="$(openwa_resolve MAIN_DATABASE_NAME ./data/main.sqlite path)"
# With DATABASE_TYPE=postgres, DATABASE_NAME names the database instead, read below only when pg_dump
# needs it, so a line for it the scripts cannot parse stops only a backup that uses it.
if [ "$DATABASE_TYPE" != "postgres" ]; then
- DATA_DB="$(openwa_resolve DATABASE_NAME ./data/openwa.sqlite)"
+ DATA_DB="$(openwa_resolve DATABASE_NAME ./data/openwa.sqlite path)"
fi
-SESSIONS_DIR="$(openwa_resolve SESSION_DATA_PATH "$DATA_DIR/sessions")"
-BAILEYS_DIR="$(openwa_resolve BAILEYS_AUTH_DIR "$DATA_DIR/baileys")"
+SESSIONS_DIR="$(openwa_resolve SESSION_DATA_PATH "$DATA_DIR/sessions" path)"
+BAILEYS_DIR="$(openwa_resolve BAILEYS_AUTH_DIR "$DATA_DIR/baileys" path)"
MEDIA_DIR="$(openwa_media_dir)"
# Installed plugin code. The app defaults this to <dataDir>/plugins — the same tree as the
# registry and each plugin's ctx.storage below — so an unset PLUGINS_DIR must resolve there
# too, or the archive silently omits the plugin packages.
-PLUGIN_PACKAGES_DIR="$(openwa_resolve PLUGINS_DIR "$DATA_DIR/plugins")"
+PLUGIN_PACKAGES_DIR="$(openwa_resolve PLUGINS_DIR "$DATA_DIR/plugins" path)"
# Plugin registry + every plugin's persisted ctx.storage. The app puts them at <dataDir>/plugins,
# where dataDir is PLUGIN_STATE_DIR when that is set and ./data otherwise, so the knob has to be
# resolved here exactly like PLUGINS_DIR above. Hardcoding $DATA_DIR/plugins meant an operator who
# moved plugin state got an archive with neither the registry nor any plugin's storage in it, and
# a restore that put nothing back. Resolved under its own name because the knob names the ROOT,
# not the plugins directory inside it.
-PLUGIN_STATE_ROOT="$(openwa_resolve PLUGIN_STATE_DIR "$DATA_DIR")"
+PLUGIN_STATE_ROOT="$(openwa_resolve PLUGIN_STATE_DIR "$DATA_DIR" path)"
PLUGIN_STATE_DIR="$PLUGIN_STATE_ROOT/plugins"
GENERATED_ENV="$DATA_DIR/.env.generated"
# The app writes the generated admin key to BOOTSTRAP_KEY_FILE when that is set.
-ADMIN_KEY_FILE="$(openwa_resolve BOOTSTRAP_KEY_FILE "$DATA_DIR/.api-key")"
+ADMIN_KEY_FILE="$(openwa_resolve BOOTSTRAP_KEY_FILE "$DATA_DIR/.api-key" path)"
log() { echo "[backup] $*"; }
diff --git a/scripts/lib-env.sh b/scripts/lib-env.sh
index 7a0e99c30..829f3e491 100644
--- a/scripts/lib-env.sh
+++ b/scripts/lib-env.sh
@@ -160,19 +160,19 @@ openwa_writable() {
# openwa_media_dir - STORAGE_LOCAL_PATH as the app settles it (src/config/storage-root.ts). v0.2.0 to
# v0.7.3 persisted ./uploads into .env.generated; where that cannot be created, as under the image's
-# root-owned /app, the app keeps media in ./data/media instead, so the scripts have to look there too.
-# Writability alone cannot tell: `docker exec` runs these as root, which can create /app/uploads while
-# the app's own user cannot. The app creates a ./uploads it uses at boot, so a missing one beside an
-# existing ./data/media means ./data/media is in use.
+# root-owned /app, the app keeps media in ./data/media (<data dir>/media) instead, so the scripts have
+# to look there too. Writability alone cannot tell: `docker exec` runs these as root, which can create
+# /app/uploads while the app's own user cannot. The app creates a ./uploads it uses at boot, so a
+# missing one beside an existing <data dir>/media means that one is in use.
openwa_media_dir() {
local dir
- dir="$(openwa_resolve STORAGE_LOCAL_PATH "$DATA_DIR/media")" || return
+ dir="$(openwa_resolve STORAGE_LOCAL_PATH "$DATA_DIR/media" path)" || return
case "$dir" in
./uploads | uploads)
- if ! openwa_writable "$dir" || { [ ! -d "$dir" ] && [ -d ./data/media ]; }; then
+ if ! openwa_writable "$dir" || { [ ! -d "$dir" ] && [ -d "$DATA_DIR/media" ]; }; then
echo "[config] WARN: STORAGE_LOCAL_PATH=$dir is a leftover the app does not use here, so it keeps" >&2
- echo "[config] media in ./data/media; using that. Remove the line from .env.generated." >&2
- dir=./data/media
+ echo "[config] media in ./data/media; using $DATA_DIR/media. Remove the line from .env.generated." >&2
+ dir="$DATA_DIR/media"
fi
;;
esac
@@ -183,13 +183,17 @@ openwa_media_dir() {
# shell; restore.sh points it at the archive's copy, which replaces this file during the restore.
OPENWA_GENERATED_ENV="${DATA_DIR:-./data}/.env.generated"
-# openwa_resolve <key> <default> - the application's precedence: environment, then ./.env, then
-# $OPENWA_GENERATED_ENV, then the built-in default. Requires DATA_DIR to be set before sourcing.
+# openwa_resolve <key> <default> [path] - the application's precedence: environment, then ./.env,
+# then $OPENWA_GENERATED_ENV, then the built-in default. Requires DATA_DIR to be set before sourcing.
+# With a third argument of `path`, the value names a filesystem path: the app reads .env.generated as
+# ./data/.env.generated, so a ./data or ./data/... value there names a path in the data dir and is
+# taken under DATA_DIR, which on the host is the volume's mountpoint rather than the working
+# directory's ./data. Other keys (a PostgreSQL name, user or password) are returned as written.
# Fails, printing nothing, when a layer sets the key in a form openwa_env_file_value rejects. Callers
# must act on that status: set -e does for a top-level assignment, but not inside a function called
# from a command substitution or for a substitution in a command's arguments.
openwa_resolve() {
- local key="$1" fallback="$2" current value layer rc
+ local key="$1" fallback="$2" kind="${3:-}" current value layer rc
current="$(printenv "$key" 2>/dev/null || true)"
if [ -n "$current" ]; then
printf '%s' "$current"
@@ -203,6 +207,12 @@ openwa_resolve() {
value="$(openwa_env_file_value "$layer" "$key")" || rc=$?
case "$rc" in
0)
+ if [ "$kind" = path ] && [ "$layer" = "$OPENWA_GENERATED_ENV" ]; then
+ case "$value" in
+ ./data | data) value="$DATA_DIR" ;;
+ ./data/* | data/*) value="${DATA_DIR%/}/${value#*data/}" ;;
+ esac
+ fi
printf '%s' "${value:-$fallback}"
return 0
;;
diff --git a/scripts/restore.sh b/scripts/restore.sh
index 8cc05dff4..addf9ef9d 100755
--- a/scripts/restore.sh
+++ b/scripts/restore.sh
@@ -20,10 +20,11 @@
# DATABASE_NAME restore target for the SQLite data store (default: ./data/openwa.sqlite)
# 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)
+# otherwise the fixed ./data default (see lib-env.sh). The defaults 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); a ./data/...
+# path read from .env.generated, database paths included, is taken under it
# 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
@@ -303,29 +304,29 @@ if [ -f "$STAGE/.env.generated" ]; then
OPENWA_GENERATED_ENV="$STAGE/.env.generated"
log "Paths not set in the environment or ./.env come from the archive's .env.generated."
fi
-MAIN_DB="$(openwa_resolve MAIN_DATABASE_NAME ./data/main.sqlite)"
+MAIN_DB="$(openwa_resolve MAIN_DATABASE_NAME ./data/main.sqlite path)"
# DATABASE_NAME is only a target for an archive carrying the SQLite data store; a PostgreSQL dump is
# loaded by hand, so a line for it the scripts cannot parse does not stop that restore.
if [ -f "$STAGE/openwa.sqlite" ]; then
- DATA_DB="$(openwa_resolve DATABASE_NAME ./data/openwa.sqlite)"
+ DATA_DB="$(openwa_resolve DATABASE_NAME ./data/openwa.sqlite path)"
fi
-SESSIONS_DIR="$(openwa_resolve SESSION_DATA_PATH "$DATA_DIR/sessions")"
-BAILEYS_DIR="$(openwa_resolve BAILEYS_AUTH_DIR "$DATA_DIR/baileys")"
+SESSIONS_DIR="$(openwa_resolve SESSION_DATA_PATH "$DATA_DIR/sessions" path)"
+BAILEYS_DIR="$(openwa_resolve BAILEYS_AUTH_DIR "$DATA_DIR/baileys" path)"
MEDIA_DIR="$(openwa_media_dir)"
# Installed plugin code. The app defaults this to <dataDir>/plugins — the same tree as the
# registry and each plugin's ctx.storage below — so an unset PLUGINS_DIR must resolve there
# too, or the archive silently omits the plugin packages.
-PLUGIN_PACKAGES_DIR="$(openwa_resolve PLUGINS_DIR "$DATA_DIR/plugins")"
+PLUGIN_PACKAGES_DIR="$(openwa_resolve PLUGINS_DIR "$DATA_DIR/plugins" path)"
# Plugin registry + every plugin's persisted ctx.storage. The app puts them at <dataDir>/plugins,
# where dataDir is PLUGIN_STATE_DIR when that is set and ./data otherwise, so the knob has to be
# resolved here exactly like PLUGINS_DIR above. Hardcoding $DATA_DIR/plugins meant an operator who
# moved plugin state got an archive with neither the registry nor any plugin's storage in it, and
# a restore that put nothing back. Resolved under its own name because the knob names the ROOT,
# not the plugins directory inside it.
-PLUGIN_STATE_ROOT="$(openwa_resolve PLUGIN_STATE_DIR "$DATA_DIR")"
+PLUGIN_STATE_ROOT="$(openwa_resolve PLUGIN_STATE_DIR "$DATA_DIR" path)"
PLUGIN_STATE_DIR="$PLUGIN_STATE_ROOT/plugins"
# The app reads the plaintext admin key from BOOTSTRAP_KEY_FILE when that is set.
-ADMIN_KEY_FILE="$(openwa_resolve BOOTSTRAP_KEY_FILE "$DATA_DIR/.api-key")"
+ADMIN_KEY_FILE="$(openwa_resolve BOOTSTRAP_KEY_FILE "$DATA_DIR/.api-key" path)"
# backup.sh archives state directories by content. An archive from before it followed symlinks
# carries a link instead, which on this host may point at the very directory the restore empties
diff --git a/scripts/smoke-test-backup-restore.sh b/scripts/smoke-test-backup-restore.sh
index ed47f4c32..f08c18526 100755
--- a/scripts/smoke-test-backup-restore.sh
+++ b/scripts/smoke-test-backup-restore.sh
@@ -53,6 +53,8 @@
# may not read
# (ah) pg_dump makes the app's TLS check when DATABASE_SSL=true (falling back to the system CA store
# without node), and connects as before when it is not
+# (ai) ./data paths in .env.generated follow OPENWA_DATA_DIR in a run on the host, in both scripts,
+# while non-path settings there are read as written
#
# Usage: ./scripts/smoke-test-backup-restore.sh
# Requires: bash, tar, node (restore.sh path resolution). sqlite3 is optional (see (c) and (k)).
@@ -1762,6 +1764,74 @@ if [ "$(PATH="$AH/nonode" backup_ah "${PG_AH}DATABASE_SSL=true\n")" != "mode=ver
fail "(ah) without node the system CA store was not used, or the log gave no hint: $(cat "$AH/out.log")"
fi
pass "(ah) pg_dump verifies the server under DATABASE_SSL=true and is unchanged without it"
+echo "==> (ai) ./data paths in .env.generated follow OPENWA_DATA_DIR in a run on the host"
+# The app writes STORAGE_LOCAL_PATH=./data/media on first run, and a dashboard save adds
+# SESSION_DATA_PATH=./data/sessions, both relative to /app in the image. Run on the host with
+# OPENWA_DATA_DIR at the volume's mountpoint, the scripts read them against the host's working
+# directory: the backup left the volume's media and sessions out, or took a stale ./data there, and
+# exited 0, and the restore put them where the app never reads them.
+AI="$WORK/ai"
+mkdir -p "$AI/vol/media" "$AI/vol/sessions/session-1" "$AI/host/data/media" "$AI/vol2" "$AI/x"
+make_fixture "$AI/vol/main.sqlite" "ai-main"
+make_fixture "$AI/vol/openwa.sqlite" "ai-data"
+printf 'ai-media\n' >"$AI/vol/media/a.jpg"
+printf 'ai-session\n' >"$AI/vol/sessions/session-1/marker"
+printf 'host-stale\n' >"$AI/host/data/media/stale.jpg"
+# The database paths come from the same file here, so they follow the volume too.
+printf '%s\n' STORAGE_LOCAL_PATH=./data/media SESSION_DATA_PATH=./data/sessions \
+ MAIN_DATABASE_NAME=./data/main.sqlite DATABASE_NAME=./data/openwa.sqlite >"$AI/vol/.env.generated"
+(cd "$AI/host" && OPENWA_DATA_DIR="$AI/vol" BACKUP_DIR="$AI/out" "$BACKUP" >/dev/null 2>&1) ||
+ fail "(ai) backup from the host failed"
+ARCHIVE_AI="$(ls "$AI"/out/openwa-backup-*.tar.gz)"
+tar -xzf "$ARCHIVE_AI" -C "$AI/x"
+if [ "$(db_fingerprint "$AI/x/main.sqlite")" != "ai-main" ] ||
+ [ "$(db_fingerprint "$AI/x/openwa.sqlite")" != "ai-data" ]; then
+ fail "(ai) backup did not archive the volume's databases"
+fi
+if [ "$(cat "$AI/x/media/a.jpg" 2>/dev/null || true)" != "ai-media" ] || [ -e "$AI/x/media/stale.jpg" ]; then
+ fail "(ai) backup did not archive the volume's media: $(find "$AI/x/media" 2>&1 | tr '\n' ' ')"
+fi
+if [ "$(cat "$AI/x/sessions/session-1/marker" 2>/dev/null || true)" != "ai-session" ]; then
+ fail "(ai) backup did not archive the volume's sessions"
+fi
+(cd "$AI/host" && OPENWA_DATA_DIR="$AI/vol2" "$RESTORE" "$ARCHIVE_AI" >/dev/null 2>&1) ||
+ fail "(ai) restore from the host failed"
+if [ "$(cat "$AI/vol2/media/a.jpg" 2>/dev/null || true)" != "ai-media" ] ||
+ [ "$(cat "$AI/vol2/sessions/session-1/marker" 2>/dev/null || true)" != "ai-session" ] ||
+ [ "$(db_fingerprint "$AI/vol2/main.sqlite" 2>/dev/null || true)" != "ai-main" ] ||
+ [ "$(db_fingerprint "$AI/vol2/openwa.sqlite" 2>/dev/null || true)" != "ai-data" ]; then
+ fail "(ai) restore did not put media, sessions and databases in the volume"
+fi
+if [ "$(ls -A "$AI/host/data")" != media ] || [ "$(ls -A "$AI/host/data/media")" != stale.jpg ]; then
+ fail "(ai) restore wrote into the host's working directory: $(find "$AI/host/data" | tr '\n' ' ')"
+fi
+# A leftover ./uploads falls back to the volume's media as well, not to the host's ./data/media.
+printf 'STORAGE_LOCAL_PATH=./uploads\n' >"$AI/vol/.env.generated"
+(
+ cd "$AI/host"
+ MAIN_DATABASE_NAME="$AI/vol/main.sqlite" DATABASE_NAME="$AI/vol/openwa.sqlite" \
+ OPENWA_DATA_DIR="$AI/vol" BACKUP_DIR="$AI/out-uploads" "$BACKUP" >/dev/null 2>&1
+) || fail "(ai) backup with a leftover ./uploads failed"
+if ! tar -tzf "$(ls "$AI"/out-uploads/openwa-backup-*.tar.gz)" | grep -qx './media/a.jpg'; then
+ fail "(ai) a leftover ./uploads did not fall back to the volume's media"
+fi
+# Only path settings are mapped: a dashboard-provisioned Postgres named, owned or reached as "data", or
+# a password under "data/", reaches pg_dump as written, with the default data dir too.
+mkdir -p "$AI/pg/data" "$AI/pg/bin"
+make_fixture "$AI/pg/data/main.sqlite" "ai-pg-main"
+cat >"$AI/pg/bin/pg_dump" <<EOF
+#!/bin/sh
+printf '%s|' "\$PGPASSWORD" "\$@" >"$AI/pg/pg_dump-args"
+EOF
+chmod +x "$AI/pg/bin/pg_dump"
+printf 'DATABASE_TYPE=postgres\nDATABASE_HOST=data\nDATABASE_USERNAME=data\nDATABASE_PASSWORD=data/s3cret\nDATABASE_NAME=data\n' \
+ >"$AI/pg/data/.env.generated"
+(cd "$AI/pg" && PATH="$AI/pg/bin:$PATH" BACKUP_DIR="$AI/pg/out" "$BACKUP" >/dev/null 2>&1) ||
+ fail "(ai) Postgres backup with settings named data failed"
+if [ "$(cat "$AI/pg/pg_dump-args" 2>/dev/null || true)" != "data/s3cret|-h|data|-p|5432|-U|data|data|" ]; then
+ fail "(ai) Postgres settings from .env.generated were rewritten: $(cat "$AI/pg/pg_dump-args" 2>&1)"
+fi
+pass "(ai) a host run backs up and restores the volume's databases, media and sessions, not the working directory's"
echo ""
echo "All smoke tests passed!"
diff --git a/src/common/docs-governance.spec.ts b/src/common/docs-governance.spec.ts
index cd04f11e2..81a4494f2 100644
--- a/src/common/docs-governance.spec.ts
+++ b/src/common/docs-governance.spec.ts
@@ -145,6 +145,16 @@ describe('governance docs match the repository', () => {
expect(note).toContain('`docker compose up -d --no-build`');
});
+ // Compose hands `./.env`'s PLUGINS_DIR to the container, where `./data/plugins` is in the volume;
+ // the backup scripts read the same line against the host's working directory.
+ it('tells a host-mount backup to override the ./data paths ./.env sets', () => {
+ expect(read('.env.example')).toMatch(/^PLUGINS_DIR=\.\/data\/plugins\b/m);
+ expect(read('docker-compose.yml')).toContain('- PLUGINS_DIR=${PLUGINS_DIR:-');
+ const note = between(read('docs/11-operational-runbooks.md'), '> The scripts resolve every other path', '\n>\n');
+ expect(note).toMatch(/A `\.\/data\/\.\.\.` path in `\.\/\.env` needs the same\s+>\s+override/);
+ expect(note).toContain('`PLUGINS_DIR=./data/plugins`');
+ });
+
// docs/20 section 20.4: the project runs no real-time chat server, and the `openwa` name is shared.
it('links no chat server the project does not run', () => {
const docs = readdirSync(join(root, 'docs'))