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

setup/pi-monitoring/deploy_stack.sh

@@ -0,0 +1,94 @@
+#!/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"
+AUTO_YES=false
+
+usage() {
+  cat <<USAGE
+Usage: $(basename "$0") [options]
+
+Deploy Portainer + Grafana + Prometheus + Uptime Kuma monitoring stack.
+
+Options:
+  --env-file=PATH   Env file path (default: setup/pi-monitoring/stack.env)
+  --yes, -y         Skip confirmation prompt
+  --help, -h        Show help
+USAGE
+}
+
+for arg in "$@"; do
+  case "$arg" in
+    --env-file=*) ENV_FILE="${arg#*=}" ;;
+    --yes|-y) AUTO_YES=true ;;
+    --help|-h) usage; exit 0 ;;
+    *) log_error "Unknown argument: $arg"; usage; exit 1 ;;
+  esac
+done
+
+require_cmd docker sudo
+load_stack_env "$ENV_FILE"
+
+if ! docker compose version >/dev/null 2>&1; then
+  log_error "docker compose plugin not found"
+  exit 1
+fi
+
+if ! confirm_action "Deploy monitoring stack using $ENV_FILE?" "$AUTO_YES"; then
+  log_info "Cancelled"
+  exit 0
+fi
+
+ensure_ops_dirs "$OPS_ROOT"
+prepare_permissions "$OPS_ROOT"
+
+if [[ ! -f "$OPS_ROOT/prometheus/targets/external.yml" ]]; then
+  cp "$SCRIPT_DIR/prometheus/targets/external.yml.example" "$OPS_ROOT/prometheus/targets/external.yml"
+  log_info "Created $OPS_ROOT/prometheus/targets/external.yml from example"
+fi
+
+compose_file_path="$(compose_file)"
+
+log_info "Pulling container images..."
+docker compose \
+  --project-name "$COMPOSE_PROJECT_NAME" \
+  --env-file "$ENV_FILE" \
+  -f "$compose_file_path" \
+  pull
+
+log_info "Starting stack..."
+docker compose \
+  --project-name "$COMPOSE_PROJECT_NAME" \
+  --env-file "$ENV_FILE" \
+  -f "$compose_file_path" \
+  up -d
+
+services=(portainer grafana prometheus uptime-kuma node-exporter cadvisor)
+for svc in "${services[@]}"; do
+  cid="$(docker compose \
+    --project-name "$COMPOSE_PROJECT_NAME" \
+    --env-file "$ENV_FILE" \
+    -f "$compose_file_path" \
+    ps -q "$svc")"
+
+  if [[ -z "$cid" ]]; then
+    log_error "Service did not start: $svc"
+    exit 1
+  fi
+
+  if ! wait_for_container_running "$cid" 60; then
+    log_error "Service failed to reach running state: $svc"
+    docker logs "$cid" --tail 80 || true
+    exit 1
+  fi
+done
+
+log_success "Monitoring stack is up"
+log_info "Portainer: https://<pi-ip>:${PORTAINER_HTTPS_PORT}"
+log_info "Grafana:   http://<pi-ip>:${GRAFANA_PORT}"
+log_info "Prometheus:http://<pi-ip>:${PROMETHEUS_PORT}"
+log_info "Uptime Kuma:http://<pi-ip>:${UPTIME_KUMA_PORT}"