Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
#!/usr/bin/env bash
#
# OpenWA restore.
#
# Restores the always-SQLite auth/audit database, a SQLite data store, engine authentication, local
# media, installed plugins, and bootstrap configuration from an archive produced by scripts/backup.sh.
# PostgreSQL dumps are staged for the explicit psql import printed at the end of the restore.
#
# Usage:
# ./scripts/restore.sh <backup-archive.tar.gz> [--strict] [--force]
# Options:
# --strict refuse to restore an archive whose CONSISTENCY-WARNING marker reports
# plain-copied (possibly torn) database snapshots; without it the restore
# continues after a loud warning. An ENGINE-STATE-NOTE (engine auth state that
# may have been copied while the app ran) is printed either way and never refused.
# --force overwrite databases that already hold a working install's data; without it
# the restore refuses to touch a live target before changing anything
# Environment:
# MAIN_DATABASE_NAME restore target for the auth/audit DB (default: <data dir>/main.sqlite)
# DATABASE_NAME restore target for the SQLite data store (default: <data dir>/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 app's ./data default (see lib-env.sh).
# OPENWA_DATA_DIR the app's ./data directory to restore into, such as a volume's mountpoint on
# the host (default: ./data); the ./data defaults, and a ./data/... path read
# from ./.env or .env.generated, are 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
# 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. One that
# comes from the archive's .env.generated has to stay in the data dir, unless it
# is the default: the restore stops at one that leads elsewhere, naming the key,
# before it copies anything. Set the key in the environment or ./.env to restore
# outside the data dir.
# 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
# shipped container
#
# Stop the OpenWA app before restoring. A snapshot of the current data dir, and of every target
# outside it, is taken before anything is written so a bad restore can be undone.
#
set -euo pipefail
# Restored databases, credentials, and snapshots must not inherit a permissive operator umask.
umask 077
STRICT=0
FORCE=0
ARCHIVE=""
for arg in "$@"; do
case "$arg" in
--strict)
STRICT=1
;;
--force)
FORCE=1
;;
-h | --help)
echo "Usage: $0 <backup-archive.tar.gz> [--strict] [--force]"
exit 0
;;
-*)
echo "Unknown option: $arg" >&2
echo "Usage: $0 <backup-archive.tar.gz> [--strict] [--force]" >&2
exit 1
;;
*)
if [ -n "$ARCHIVE" ]; then
echo "Unexpected extra argument: $arg" >&2
echo "Usage: $0 <backup-archive.tar.gz> [--strict] [--force]" >&2
exit 1
fi
ARCHIVE="$arg"
;;
esac
done
DATA_DIR="${OPENWA_DATA_DIR:-./data}"
# shellcheck source=scripts/lib-env.sh
. "$(dirname "$0")/lib-env.sh"
RESTORE_TIMESTAMP="$(date +%Y%m%d-%H%M%S)"
RESOLVED_CWD="$(pwd -P)"
# Resolve a path the way the kernel does: left to right, following every symlink and applying each '..' to
# the physical directory reached so far. Folding '..' lexically first would read <link to />/.. as the link's
# parent directory when the kernel resolves it to /, and a guard on that value would pass what it must refuse.
# Each step is the kernel's own realpath (fs.realpathSync.native). The JavaScript one folds a '..' inside a
# link's target lexically, so a link to <link to />/.. would read as the directory holding it, and it keeps
# the case and Unicode form as typed on a filesystem that ignores both. The part past the first component
# that does not exist cannot hold a link, so '..' there is plain text. This matters for destructive targets
# such as /mount-link/sessions: path.resolve alone would not reveal that mount-link points at the
# workspace, home directory, or another broad protected target.
resolve_path() {
node -e '
const fs = require("fs");
const path = require("path");
const raw = process.argv[1];
const absolute = raw.startsWith("/") ? raw : process.cwd() + "/" + raw;
let physical = "/";
const missing = [];
for (const segment of absolute.split("/")) {
if (segment === "" || segment === ".") continue;
if (missing.length > 0) {
if (segment === "..") missing.pop();
else missing.push(segment);
} else if (segment === "..") {
physical = path.dirname(physical);
} else {
const next = path.join(physical, segment);
if (fs.existsSync(next)) physical = fs.realpathSync.native(next);
else missing.push(segment);
}
}
console.log(path.join(physical, ...missing));
' "$1"
}
RESOLVED_DATA_DIR="$(resolve_path "$DATA_DIR")"
RESOLVED_USER_HOME="$(resolve_path "${HOME:-/nonexistent-openwa-home}")"
log() { echo "[restore] $*"; }
case "$DATA_DIR" in
'' | / | . | ./ | .. | ../)
log "ERROR: refusing unsafe OPENWA_DATA_DIR target: ${DATA_DIR:-<empty>}"
exit 1
;;
esac
# The trailing / comes off the prefix wherever a resolved directory is matched as one: the root resolves to
# "/", "$dir"/* is then //*, which no path matches, and every spelling of / that the list above misses
# (//, /., /./, /.. or a link to /) would be taken for a directory the workspace is not under. Trimmed, the
# pattern is /*, so the root is refused here as a parent of the workspace. The / is kept inside the quotes:
# bash 5 does not match "${dir%/}"/* against anything when the trim leaves nothing, and bash 3 does.
case "$RESOLVED_CWD/" in
"${RESOLVED_DATA_DIR%/}/"*)
log "ERROR: OPENWA_DATA_DIR must not be the workspace or one of its parent directories: $DATA_DIR"
exit 1
;;
esac
# The root directory under a name no path comparison recognises is refused by identity: a bind mount of /, or
# a link whose name is not valid UTF-8, which node reads back with replacement characters so that the
# resolution above misses it. test -ef compares device and inode, as the kernel does.
if [ "$DATA_DIR" -ef / ]; then
log "ERROR: refusing unsafe OPENWA_DATA_DIR target: $DATA_DIR"
exit 1
fi
# The home directory, or a parent of it, holds every other home under it as the workspace's parent holds the
# workspace, so the data dir is refused when it is either.
case "$RESOLVED_USER_HOME/" in
"${RESOLVED_DATA_DIR%/}/"*)
log "ERROR: OPENWA_DATA_DIR must not be the user home directory or one of its parent directories: $DATA_DIR"
exit 1
;;
esac
# refuse_unwritable <path> <label>: stop in the snapshot phase, before the first database is replaced.
refuse_unwritable() {
log "ERROR: cannot write the $2 target: $1"
log " nothing has been restored yet; fix its permissions or point the setting at a writable path, then re-run"
exit 1
}
# refuse_root_target <path> <label>: a database or key file that resolves to / (//, /., a link to /) is
# snapshotted with cp -pRH, which copies the whole filesystem into a directory inside it, and a root user can
# write there. Checked first in the snapshot phase, ahead of the writability test a non-root user stops at.
refuse_root_target() {
if [ "$(resolve_path "$1")" = / ] || [ "$1" -ef / ]; then
log "ERROR: refusing to replace broad $2 target: $1"
exit 1
fi
}
# refuse_directory_target <path> <label>: a database or key file is a file. Given a directory (the workspace's
# parent, say, from a typo in a path) the restore copied it whole into the safety snapshot, wrote the file
# inside it, and then took the search bit off it with the chmod 0600 that follows a database or key file.
refuse_directory_target() {
if [ -d "$1" ]; then
log "ERROR: refusing to replace $2 target that is a directory: $1"
exit 1
fi
}
replace_tree() {
source_dir="$1"
target_dir="$2"
label="$3"
case "$target_dir" in
'' | / | . | ./ | .. | ../)
log "ERROR: refusing to replace unsafe $label target: ${target_dir:-<empty>}"
exit 1
;;
esac
resolved_target="$(resolve_path "$target_dir")"
if [ "$resolved_target" = "/" ] || [ "$target_dir" -ef / ] || [ "$resolved_target" = "$RESOLVED_CWD" ] || [ "$resolved_target" = "$RESOLVED_DATA_DIR" ] || [ "$resolved_target" = "$RESOLVED_USER_HOME" ]; then
log "ERROR: refusing to replace broad $label target: $target_dir"
exit 1
fi
case "$RESOLVED_CWD/" in
"${resolved_target%/}/"*)
log "ERROR: refusing to replace $label target that contains the workspace: $target_dir"
exit 1
;;
esac
case "$RESOLVED_DATA_DIR/" in
"${resolved_target%/}/"*)
log "ERROR: refusing to replace $label target that contains the data directory: $target_dir"
exit 1
;;
esac
case "$RESOLVED_USER_HOME/" in
"${resolved_target%/}/"*)
log "ERROR: refusing to replace $label target that contains the user home directory: $target_dir"
exit 1
;;
esac
if [ "$PHASE" = snapshot ]; then
# An existing directory is emptied before it is refilled, which needs every directory in it.
openwa_writable "$target_dir" || refuse_unwritable "$target_dir" "$label"
if [ -d "$target_dir" ]; then
blocked="$(find "$target_dir/" -type d \
-exec sh -c 'for d do [ -w "$d" ] || { echo "$d"; exit 1; }; done' sh {} + 2>/dev/null)" || true
[ -z "$blocked" ] || refuse_unwritable "${blocked%%$'\n'*}" "$label"
fi
snapshot_external "$target_dir"
return
fi
log "Restoring $label"
if [ -d "$target_dir" ]; then
# Empty the directory and refill it rather than remove it: it may be a mount point (a volume under
# the container's read-only root), which can be neither removed nor re-created. A symlink to a
# directory is refilled through the link, so an operator's layout on another disk survives. The
# trailing slash makes find descend into the link's target instead of stopping at the link.
find "$target_dir/" -mindepth 1 -maxdepth 1 -exec rm -rf -- {} +
cp -pR "$source_dir/." "$target_dir/"
else
rm -rf -- "$target_dir"
mkdir -p "$(dirname "$target_dir")"
cp -pR "$source_dir" "$target_dir"
fi
}
# The data-dir safety snapshot below cannot cover a target that lives OUTSIDE it (a custom
# MAIN_DATABASE_NAME / DATABASE_NAME, SESSION_DATA_PATH, BAILEYS_AUTH_DIR, STORAGE_LOCAL_PATH,
# PLUGINS_DIR or BOOTSTRAP_KEY_FILE). Preserve such a target separately, so a restore pointed at the
# wrong archive remains recoverable. OPENWA_RESTORE_SNAPSHOT_DIR takes these snapshots too when it is
# set: a target on its own mount under a read-only root has no writable place next to it.
snapshot_external() {
target="$1"
external_snapshot=""
case "$(resolve_path "$target")" in
"${RESOLVED_DATA_DIR%/}/"*) return 0 ;;
esac
[ -e "$target" ] || return 0
snapshot_dir="${OPENWA_RESTORE_SNAPSHOT_DIR:-$(dirname "$target")}"
external_snapshot="${snapshot_dir%/}/$(basename "$target").pre-restore-$RESTORE_TIMESTAMP"
# Targets from different parents can share a name in one snapshot dir (a PLUGINS_DIR and a
# PLUGIN_STATE_DIR both end in plugins); never copy one into the other's snapshot.
n=1
while [ -e "$external_snapshot" ]; do
n=$((n + 1))
external_snapshot="${snapshot_dir%/}/$(basename "$target").pre-restore-$RESTORE_TIMESTAMP-$n"
done
log "Snapshotting current $target -> $external_snapshot"
mkdir -p "$snapshot_dir"
# -H copies what a symlinked target points at. The restore writes through such a link, so a copy of
# the link itself would end up showing the archive instead of the state it replaced.
cp -pRH "$target" "$external_snapshot"
}
# restore_db <staged file> <target> <label>
# SQLite keeps un-checkpointed transactions in <db>-wal (and a crashed transaction in <db>-journal),
# named after the symlink-resolved file, and replays them over whatever main file it finds next to
# them. Those sidecars belong to the database being replaced: they go into its snapshot and are
# removed before the copy, or the restored file reads back the old install's rows.
restore_db() {
resolved_db="$(resolve_path "$2")"
if [ "$PHASE" = snapshot ]; then
refuse_root_target "$2" "$3"
refuse_directory_target "$2" "$3"
openwa_writable "$2" || refuse_unwritable "$2" "$3"
for db in "$2" "$resolved_db"; do
for sfx in -wal -shm -journal; do
if [ -e "$db$sfx" ] && [ ! -w "$(dirname "$db")" ]; then
refuse_unwritable "$(dirname "$db")" "$3"
fi
done
done
snapshot_external "$2"
# Empty when the target lives in the data dir, whose own snapshot already holds the sidecars.
if [ -n "$external_snapshot" ]; then
for sfx in -wal -shm -journal; do
for db in "$2" "$resolved_db"; do
if [ -f "$db$sfx" ]; then
cp -p "$db$sfx" "$external_snapshot$sfx"
fi
done
done
fi
return
fi
log "Restoring $3 -> $2"
mkdir -p "$(dirname "$2")"
rm -f -- "$2-wal" "$2-shm" "$2-journal" "$resolved_db-wal" "$resolved_db-shm" "$resolved_db-journal"
cp "$1" "$2"
# Owner-only, matching what the app re-tightens on every boot (sqlite-file-permissions.ts);
# cp preserves the staged mode, and a foreign-umask extraction may leave it broader.
chmod 0600 "$2" 2>/dev/null || true
}
# A restore target that already holds a working install's tables is LIVE: overwriting it destroys
# real data, and the pre-restore snapshot is a convenience, not a recovery guarantee. Probe with
# the same sqlite3 CLI backup.sh snapshots with, opened read-only so the guard itself cannot touch
# the target it is guarding; a missing file — or one with no tables yet, as a
# fresh install leaves behind — is safe to restore over. Without the CLI there is no way to prove
# the file empty, so any non-empty target counts as live rather than guessed safe.
# sqlite3 applies the operator's rc file even to a one-shot query, and .headers on or another output
# mode turns the count into text, so the probe loads no rc file. Anything but a bare count still
# means the probe did not answer, which counts as live like a probe that failed outright.
db_appears_live() {
target="$1"
[ -f "$target" ] || return 1
if command -v sqlite3 >/dev/null 2>&1; then
tables="$(sqlite3 -batch -noheader -list -init /dev/null -readonly "$target" \
"SELECT count(*) FROM sqlite_master;" 2>/dev/null)" || return 0
case "$tables" in
'' | *[!0-9]*)
return 0
;;
esac
[ "$tables" -gt 0 ]
else
[ -s "$target" ]
fi
}
if [ -z "$ARCHIVE" ] || [ ! -f "$ARCHIVE" ]; then
echo "Usage: $0 <backup-archive.tar.gz> [--strict] [--force]" >&2
exit 1
fi
STAGE="$(mktemp -d)"
trap 'rm -rf "$STAGE"' EXIT
log "Extracting $ARCHIVE"
# Refuse archive path names that could escape STAGE. This restore command accepts archives produced by
# backup.sh and installs their keys, plugins and configuration as they are; it is not a general
# untrusted-tar verifier. Where it writes does not rest on the archive, though: a member name that could
# escape STAGE is refused here, and a path from its .env.generated that leads out of the data dir below.
while IFS= read -r entry; do
case "$entry" in
/* | ../* | */../* | */..)
log "ERROR: unsafe path in backup archive: $entry"
exit 1
;;
esac
done < <(tar -tzf "$ARCHIVE")
tar -xzf "$ARCHIVE" -C "$STAGE"
# Targets resolve exactly like the app: an explicit environment value, then ./.env, then the
# dashboard's .env.generated, else the app's ./data defaults under OPENWA_DATA_DIR. They may
# legitimately live outside it, where the environment or ./.env says so (see archive_target). The
# archive's .env.generated replaces the target's further down, so when it carries one, that copy is
# the third layer: the restored app reads its paths, and state placed where the replaced file
# pointed would never be opened. Resolved before anything is validated or written.
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_DIR%/}/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_DIR%/}/openwa.sqlite" path)"
fi
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" 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" 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" 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
# before refilling it from that link. Refuse it before any existing state is touched.
for member in sessions baileys media plugin-packages plugin-state; do
if [ -L "$STAGE/$member" ]; then
log "ERROR: archive member $member/ is a symlink, not a directory: the backup holds no data for it"
log " re-take the backup with this version of backup.sh, or extract the archive and restore by hand"
exit 1
fi
done
# The environment and ./.env are the operator's own; the archive's .env.generated is not, yet the paths it names
# are where the restore empties directories and writes files. Such a path has to lie inside the data dir as the
# kernel resolves it, unless it is where the app goes without it (a default, which the operator's own links may
# lead elsewhere). Inside the data dir, two ways out remain closed: a link that does not resolve, which a copy
# follows wherever it points, and a target inside or around a directory refilled from the archive, whose links
# are in place before the other target is written. Setting the key in the environment or ./.env lifts this.
from_archive() {
[ "$OPENWA_GENERATED_ENV" = "$STAGE/.env.generated" ] && [ -z "$(printenv "$1" 2>/dev/null || true)" ] &&
! openwa_env_file_value ./.env "$1" >/dev/null 2>&1 &&
openwa_env_file_value "$OPENWA_GENERATED_ENV" "$1" >/dev/null 2>&1
}
refuse_archive_path() {
log "ERROR: $1 from the archive's .env.generated $3: $2"
log " nothing has been restored yet; to restore there, set $1 in the environment or ./.env and re-run"
exit 1
}
TARGET_KEYS=()
TARGET_PATHS=()
TARGET_KINDS=()
TARGET_CHOSEN=()
# archive_target <key> <path> <file|dir> <default>...: note a target the restore replaces, refusing it when the
# archive's .env.generated chose it and it leads out of the data dir.
archive_target() {
local key="$1" path="$2" kind="$3" resolved chosen=0 p
shift 3
resolved="$(resolve_path "$path")"
if from_archive "$key"; then
chosen=1
for p in "$@"; do
[ "$resolved" != "$(resolve_path "$p")" ] || chosen=0
done
fi
if [ "$chosen" -eq 1 ]; then
case "$resolved" in
"${RESOLVED_DATA_DIR%/}/"?*) ;;
*) refuse_archive_path "$key" "$path" "is not inside the data directory" ;;
esac
p="$path"
while [ ! -e "$p" ]; do
[ ! -L "$p" ] || refuse_archive_path "$key" "$path" "goes through a link that does not resolve ($p)"
p="$(dirname "$p")"
done
fi
TARGET_KEYS+=("$key")
TARGET_PATHS+=("$resolved")
TARGET_KINDS+=("$kind")
TARGET_CHOSEN+=("$chosen")
}
if [ -f "$STAGE/main.sqlite" ]; then
archive_target MAIN_DATABASE_NAME "$MAIN_DB" file "${DATA_DIR%/}/main.sqlite"
fi
if [ -f "$STAGE/openwa.sqlite" ]; then
archive_target DATABASE_NAME "$DATA_DB" file "${DATA_DIR%/}/openwa.sqlite"
fi
if [ -d "$STAGE/sessions" ]; then
archive_target SESSION_DATA_PATH "$SESSIONS_DIR" dir "$DATA_DIR/sessions"
fi
if [ -d "$STAGE/baileys" ]; then
archive_target BAILEYS_AUTH_DIR "$BAILEYS_DIR" dir "$DATA_DIR/baileys"
fi
# A leftover ./uploads stays where the app itself keeps media (openwa_media_dir), so it counts as a default.
if [ -d "$STAGE/media" ]; then
archive_target STORAGE_LOCAL_PATH "$MEDIA_DIR" dir "$DATA_DIR/media" ./uploads
fi
if [ -d "$STAGE/plugin-packages" ]; then
archive_target PLUGINS_DIR "$PLUGIN_PACKAGES_DIR" dir "$DATA_DIR/plugins"
fi
if [ -d "$STAGE/plugin-state" ]; then
archive_target PLUGIN_STATE_DIR "$PLUGIN_STATE_DIR" dir "$DATA_DIR/plugins"
fi
if [ -f "$STAGE/.api-key" ]; then
archive_target BOOTSTRAP_KEY_FILE "$ADMIN_KEY_FILE" file "$DATA_DIR/.api-key"
fi
# Written into the data dir after the trees, at fixed names, so no key moves them. A refilled tree can still
# stand on one of them, and a copy onto a directory goes into it, through any link the archive put there.
for fixed in .env.generated database.sql; do
if [ -f "$STAGE/$fixed" ]; then
TARGET_KEYS+=("$fixed")
TARGET_PATHS+=("$(resolve_path "$DATA_DIR/$fixed")")
TARGET_KINDS+=(file)
TARGET_CHOSEN+=(0)
fi
done
i=0
while [ "$i" -lt "${#TARGET_KEYS[@]}" ]; do
j=0
while [ "$j" -lt "${#TARGET_KEYS[@]}" ]; do
if [ "${TARGET_KINDS[j]}" = dir ] && [ "${TARGET_CHOSEN[i]}${TARGET_CHOSEN[j]}" != 00 ]; then
where=""
case "${TARGET_PATHS[i]}" in
"${TARGET_PATHS[j]%/}/"?*) where=inside ;;
"${TARGET_PATHS[j]}") [ "${TARGET_KINDS[i]}" != file ] || where=on ;;
esac
if [ -n "$where" ]; then
key="${TARGET_KEYS[i]}"
[ "${TARGET_CHOSEN[i]}" -eq 1 ] || key="${TARGET_KEYS[j]}"
refuse_archive_path "$key" "${TARGET_PATHS[i]}" \
"puts the ${TARGET_KEYS[i]} target $where the ${TARGET_KEYS[j]} directory, which is refilled from the archive"
fi
fi
j=$((j + 1))
done
i=$((i + 1))
done
# A backup taken without sqlite3 .backup carries this marker: the database snapshots were
# plain-copied from a possibly-live app and may be torn. Warn loudly and continue — unless
# --strict makes it fatal. Refuse BEFORE touching any existing state.
if [ -f "$STAGE/CONSISTENCY-WARNING" ]; then
log "WARN: archive carries CONSISTENCY-WARNING — database snapshot(s) may be torn:"
sed 's/^/[restore] /' "$STAGE/CONSISTENCY-WARNING"
if [ "$STRICT" -eq 1 ]; then
log "ERROR: --strict given — refusing to restore a possibly-torn database snapshot"
exit 1
fi
log "WARN: continuing anyway; verify data integrity after the restore (re-run with --strict to make this fatal)"
fi
# Engine auth state copied while an engine may have been writing it. Informational only: every
# online backup of a running install carries it, and the worst case is a re-pair, not lost data.
if [ -f "$STAGE/ENGINE-STATE-NOTE" ]; then
log "WARN: archive carries ENGINE-STATE-NOTE; engine auth state may have been copied while the app was running:"
sed 's/^/[restore] /' "$STAGE/ENGINE-STATE-NOTE"
fi
# Refuse to overwrite a live database without --force, BEFORE any existing state is touched (the
# same rule the --strict refusal above follows). Only the databases this archive actually carries
# are checked — a target the archive omits is left alone either way.
if [ "$FORCE" -ne 1 ]; then
LIVE_TARGETS=""
if [ -f "$STAGE/main.sqlite" ] && db_appears_live "$MAIN_DB"; then
LIVE_TARGETS="$LIVE_TARGETS $MAIN_DB"
fi
if [ -f "$STAGE/openwa.sqlite" ] && db_appears_live "$DATA_DB"; then
LIVE_TARGETS="$LIVE_TARGETS $DATA_DB"
fi
if [ -n "$LIVE_TARGETS" ]; then
echo "[restore] ERROR: database target(s) appear live:$LIVE_TARGETS" >&2
echo "[restore] they already hold a working install's data — stop the app, then re-run with --force to overwrite them" >&2
exit 1
fi
fi
# Safety snapshot of whatever is there now, next to the data dir unless OPENWA_RESTORE_SNAPSHOT_DIR
# names another directory. The shipped compose file and Helm chart mount the data dir as a volume
# under a read-only root, where that sibling cannot be written.
if [ -d "$DATA_DIR" ] && [ -n "$(ls -A "$DATA_DIR" 2>/dev/null || true)" ]; then
SAFETY_DIR="${OPENWA_RESTORE_SNAPSHOT_DIR:-$(dirname "$DATA_DIR")}"
SAFETY="${SAFETY_DIR%/}/$(basename "$DATA_DIR").pre-restore-$RESTORE_TIMESTAMP"
log "Snapshotting current data dir -> $SAFETY"
mkdir -p "$SAFETY_DIR"
# -H for a symlinked data dir, as in snapshot_external.
cp -pRH "$DATA_DIR" "$SAFETY"
fi
mkdir -p "$DATA_DIR"
if [ ! -f "$STAGE/main.sqlite" ]; then
log "WARN: main.sqlite not in archive — API keys / audit log will NOT be restored"
fi
MERGED_PLUGINS_DIR=""
if [ -d "$STAGE/plugin-packages" ] && [ -d "$STAGE/plugin-state" ] &&
[ "$(resolve_path "$PLUGIN_PACKAGES_DIR")" = "$(resolve_path "$PLUGIN_STATE_DIR")" ]; then
# Docker deployments deliberately colocate package and state files. Build the complete target in
# staging and replace it once, so neither half can erase the other during restore.
MERGED_PLUGINS_DIR="$STAGE/plugin-merged"
mkdir -p "$MERGED_PLUGINS_DIR"
cp -pR "$STAGE/plugin-packages/." "$MERGED_PLUGINS_DIR"
cp -pR "$STAGE/plugin-state/." "$MERGED_PLUGINS_DIR"
fi
# Runs twice: PHASE=snapshot checks every target and snapshots the ones outside the data dir, then
# PHASE=apply writes them. A target that is refused, or cannot be snapshotted or written, stops the
# restore before the first database is written, instead of halfway through with a mixed install left
# behind.
restore_targets() {
if [ -f "$STAGE/main.sqlite" ]; then
restore_db "$STAGE/main.sqlite" "$MAIN_DB" "auth/audit DB"
fi
if [ -f "$STAGE/openwa.sqlite" ]; then
restore_db "$STAGE/openwa.sqlite" "$DATA_DB" "data store"
fi
if [ -d "$STAGE/sessions" ]; then
replace_tree "$STAGE/sessions" "$SESSIONS_DIR" "whatsapp-web.js sessions"
fi
if [ -d "$STAGE/baileys" ]; then
replace_tree "$STAGE/baileys" "$BAILEYS_DIR" "Baileys authentication state"
fi
if [ -d "$STAGE/media" ]; then
replace_tree "$STAGE/media" "$MEDIA_DIR" "local media"
fi
if [ -n "$MERGED_PLUGINS_DIR" ]; then
replace_tree "$MERGED_PLUGINS_DIR" "$PLUGIN_PACKAGES_DIR" "installed plugins and plugin state"
else
if [ -d "$STAGE/plugin-packages" ]; then
replace_tree "$STAGE/plugin-packages" "$PLUGIN_PACKAGES_DIR" "installed plugin packages"
fi
if [ -d "$STAGE/plugin-state" ]; then
replace_tree "$STAGE/plugin-state" "$PLUGIN_STATE_DIR" "plugin registry and persisted state"
fi
fi
if [ -f "$STAGE/.api-key" ]; then
restore_admin_key
fi
}
# The plaintext admin key goes where the app reads it. Checked and, outside the data dir, snapshotted
# with the other targets: it may be the only plaintext copy of a key the replaced main.sqlite accepts.
restore_admin_key() {
if [ "$PHASE" = snapshot ]; then
refuse_root_target "$ADMIN_KEY_FILE" "admin key (BOOTSTRAP_KEY_FILE)"
refuse_directory_target "$ADMIN_KEY_FILE" "admin key (BOOTSTRAP_KEY_FILE)"
openwa_writable "$ADMIN_KEY_FILE" || refuse_unwritable "$ADMIN_KEY_FILE" "admin key (BOOTSTRAP_KEY_FILE)"
snapshot_external "$ADMIN_KEY_FILE"
return
fi
log "Restoring plaintext admin key -> $ADMIN_KEY_FILE"
mkdir -p "$(dirname "$ADMIN_KEY_FILE")"
cp "$STAGE/.api-key" "$ADMIN_KEY_FILE"
chmod 0600 "$ADMIN_KEY_FILE"
}
PHASE=snapshot
restore_targets
# Written into the data dir after the targets, so checked with them; the data-dir snapshot holds both.
if [ -f "$STAGE/.env.generated" ]; then
openwa_writable "$DATA_DIR/.env.generated" ||
refuse_unwritable "$DATA_DIR/.env.generated" "dashboard-generated configuration"
fi
if [ -f "$STAGE/database.sql" ]; then
openwa_writable "$DATA_DIR/database.sql" || refuse_unwritable "$DATA_DIR/database.sql" "PostgreSQL dump"
fi
PHASE=apply
restore_targets
if [ -f "$STAGE/.env.generated" ]; then
log "Restoring dashboard-generated configuration"
cp "$STAGE/.env.generated" "$DATA_DIR/.env.generated"
chmod 0600 "$DATA_DIR/.env.generated"
fi
if [ -f "$STAGE/database.sql" ]; then
cp "$STAGE/database.sql" "$DATA_DIR/database.sql"
log "Postgres dump present: load it into an EMPTY database, as docs/11-operational-runbooks.md"
log "(Restore from Backup, step 3) shows for the built-in openwa-postgres container. For an external"
log "server, with DATABASE_URL set to your own URL for that database:"
# psql defaults to sslmode=prefer, which falls back to plaintext and takes any certificate, so the
# printed command asks for the TLS mode the app uses. The restore is already done: a TLS line the
# scripts cannot parse leaves the check on rather than stopping it.
PSQL_SSL=""
PSQL_UNREAD=""
if [ -z "${PGSSLMODE:-}" ]; then
PSQL_TLS="$(openwa_resolve DATABASE_SSL false 2>/dev/null)" || { PSQL_TLS=true && PSQL_UNREAD=DATABASE_SSL; }
if [ "$PSQL_TLS" = true ]; then
PSQL_SSL="PGSSLMODE=verify-full "
PSQL_REJECT="$(openwa_resolve DATABASE_SSL_REJECT_UNAUTHORIZED true 2>/dev/null)" ||
PSQL_UNREAD="${PSQL_UNREAD:+$PSQL_UNREAD and }DATABASE_SSL_REJECT_UNAUTHORIZED"
if [ "$PSQL_REJECT" = false ]; then
PSQL_SSL="PGSSLMODE=require "
fi
fi
fi
log " sed '/^SET transaction_timeout = 0;\$/d' $DATA_DIR/database.sql | ${PSQL_SSL}psql -v ON_ERROR_STOP=1 \"\$DATABASE_URL\""
if [ -n "$PSQL_UNREAD" ]; then
log "($PSQL_UNREAD could not be read from the configuration, so the command takes the stricter setting)"
fi
if [ "$PSQL_SSL" = "PGSSLMODE=verify-full " ] && [ -z "${PGSSLROOTCERT:-}" ]; then
log "(verify-full needs the server's CA: set PGSSLROOTCERT to its CA file, such as the NODE_EXTRA_CA_CERTS"
log "file for a private CA; libpq otherwise reads ~/.postgresql/root.crt, and sslrootcert=system needs libpq 16+"
log "and a system CA store, which the image lacks)"
fi
log "(sed drops a setting this image's pg_dump 17 writes and PostgreSQL 16 rejects)"
fi
log "Restore complete. Start the app and confirm an existing API key still authenticates."