feat: add Pi monitoring stack with deployment scripts and architecture documentation

setup/pi-monitoring/backup_stack.sh

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=./lib.sh
+source "$SCRIPT_DIR/lib.sh"
+
+ENV_FILE="$SCRIPT_DIR/stack.env"
+RETENTION_DAYS=14
+AUTO_YES=false
+
+usage() {
+  cat <<USAGE
+Usage: $(basename "$0") [options]
+
+Create a compressed backup archive for the Pi monitoring stack state.
+
+Options:
+  --env-file=PATH     Env file path (default: setup/pi-monitoring/stack.env)
+  --retention-days=N  Delete backups older than N days (default: 14)
+  --yes, -y           Skip confirmation prompt
+  --help, -h          Show help
+USAGE
+}
+
+for arg in "$@"; do
+  case "$arg" in
+    --env-file=*) ENV_FILE="${arg#*=}" ;;
+    --retention-days=*) RETENTION_DAYS="${arg#*=}" ;;
+    --yes|-y) AUTO_YES=true ;;
+    --help|-h) usage; exit 0 ;;
+    *) log_error "Unknown argument: $arg"; usage; exit 1 ;;
+  esac
+done
+
+require_cmd tar find date
+load_stack_env "$ENV_FILE"
+
+backup_dir="$OPS_ROOT/backups"
+mkdir -p "$backup_dir"
+
+timestamp="$(date -u +%Y%m%dT%H%M%SZ)"
+archive_path="$backup_dir/pi-monitoring-${timestamp}.tar.gz"
+
+if ! confirm_action "Create backup archive at $archive_path?" "$AUTO_YES"; then
+  log_info "Cancelled"
+  exit 0
+fi
+
+paths=(
+  "$OPS_ROOT/portainer/data"
+  "$OPS_ROOT/grafana/data"
+  "$OPS_ROOT/prometheus/data"
+  "$OPS_ROOT/prometheus/targets"
+  "$OPS_ROOT/uptime-kuma/data"
+  "$SCRIPT_DIR/docker-compose.yml"
+  "$SCRIPT_DIR/prometheus/prometheus.yml"
+  "$ENV_FILE"
+)
+
+include=()
+for p in "${paths[@]}"; do
+  if [[ -e "$p" ]]; then
+    include+=("${p#/}")
+  else
+    log_warn "Skipping missing path: $p"
+  fi
+done
+
+if [[ ${#include[@]} -eq 0 ]]; then
+  log_error "No backup sources found"
+  exit 1
+fi
+
+log_info "Creating backup archive..."
+(
+  cd /
+  tar -czf "$archive_path" "${include[@]}"
+)
+
+log_success "Backup created: $archive_path"
+
+if [[ "$RETENTION_DAYS" =~ ^[0-9]+$ ]]; then
+  log_info "Pruning backups older than ${RETENTION_DAYS} days..."
+  find "$backup_dir" -type f -name 'pi-monitoring-*.tar.gz' -mtime "+${RETENTION_DAYS}" -delete
+else
+  log_warn "Invalid retention value '${RETENTION_DAYS}'; skipping pruning"
+fi