Document backup pipeline behaviour

lib/common.sh

@@ -1,9 +1,15 @@
 #!/usr/bin/env bash
+# Shared configuration, validation and logging helpers.
+#
+# Every executable script sources this file. Defaults are deliberately safe:
+# transfer methods and MQTT reporting are disabled until enabled in the
+# host-local, Git-ignored .env file.
 set -Eeuo pipefail
 
 SCRIPT_ROOT="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd -P)"
 ENV_FILE="${DOCKERBACKUP_ENV:-$SCRIPT_ROOT/.env}"
 
+# Core archive pipeline defaults.
 SOURCE_BASE_DIR="/dockervolumes"
 BACKUP_ROOT="/dockerbackups"
 CONTAINERS_FILE="$SCRIPT_ROOT/containers.txt"
@@ -16,6 +22,7 @@ WAIT_INTERVAL=3
 START_RETRIES=1
 LOCK_FILE="/run/lock/zorruno-docker-backup.lock"
 ZSTD_EXTRA_OPTS="-T0 -12"
+# Optional MQTT reporting and command-listener defaults.
 MQTT_REPORT_ENABLED=0
 MQTT_HOST=""
 MQTT_PORT=1883
@@ -24,6 +31,7 @@ MQTT_PASSWORD_FILE=""
 MQTT_STATUS_TOPIC="viewroad-status/dockerbackup/$BACKUP_HOSTNAME"
 MQTT_COMMAND_TOPIC="viewroad-commands/dockerbackup/$BACKUP_HOSTNAME/run"
 
+# Transfer-stage defaults. Host-specific destinations belong in .env.
 RCLONE_ENABLED=0
 RCLONE_REMOTE=""
 RCLONE_HOST_SUBDIR=1
@@ -34,6 +42,7 @@ SMB_HOST_SUBDIR=1
 SMB_RSYNC_ARGS="-a"
 
 if [[ -f "$ENV_FILE" ]]; then
+  # Export loaded values so child stage scripts inherit the same configuration.
   set -a
   # shellcheck disable=SC1090
   . "$ENV_FILE"
@@ -50,6 +59,8 @@ log() {
   local line
   line="$(timestamp) [$1] $2"
   printf '%s\n' "$line" >&2
+  # Directly executed stages have no BACKUP_RUN_LOG. Always return success so
+  # an informational log call cannot terminate a script running with set -e.
   if [[ -n "${BACKUP_RUN_LOG:-}" ]]; then
     printf '%s\n' "$line" >>"$BACKUP_RUN_LOG"
   fi
@@ -73,6 +84,8 @@ require_positive_integer() {
 }
 
 resolve_path() {
+  # Host-local filenames are resolved relative to the repository, not the
+  # caller's current directory. Absolute paths pass through unchanged.
   if [[ "$1" = /* ]]; then printf '%s\n' "$1"; else printf '%s/%s\n' "$SCRIPT_ROOT" "$1"; fi
 }
 

lib/mqtt.sh

@@ -1,4 +1,6 @@
 #!/usr/bin/env bash
+# Shared mosquitto_pub/mosquitto_sub argument construction.
+# Passwords are read from a protected file rather than placed in .env or Git.
 
 mqtt_common_args() {
   MQTT_ARGS=(-h "$MQTT_HOST" -p "$MQTT_PORT")
@@ -14,6 +16,8 @@ mqtt_publish() {
   [[ -n "$MQTT_HOST" ]] || die "MQTT_HOST is not configured"
   require_command mosquitto_pub
   mqtt_common_args
+  # Backup state is retained so Home Assistant receives the latest result after
+  # reconnecting. Command messages are handled separately and are never kept.
   (( retain )) && MQTT_ARGS+=(-r)
   mosquitto_pub "${MQTT_ARGS[@]}" -t "$topic" -m "$payload"
 }