Add preflight doctor and resilient bootstrap workflow

Author: liamvibecodes

README.md

@@ -87,6 +87,12 @@ Requires OrbStack (or Docker Desktop) and Plex already installed. Handles everyt
 curl -fsSL https://raw.githubusercontent.com/liamvibecodes/mac-media-stack-advanced/main/bootstrap.sh | bash
 ```
 
+Optional flags when running from a local clone:
+
+```bash
+bash bootstrap.sh --media-dir /Volumes/T9/Media --install-dir ~/mac-media-stack-advanced --non-interactive
+```
+
 <details>
 <summary>See it in action</summary>
 <br>
@@ -100,8 +106,9 @@ If you prefer to run each step yourself:
 ```bash
 git clone https://github.com/liamvibecodes/mac-media-stack-advanced.git
 cd mac-media-stack-advanced
-bash scripts/setup.sh
+bash scripts/setup.sh            # or: bash scripts/setup.sh --media-dir /Volumes/T9/Media
 # edit .env with VPN keys
+bash scripts/doctor.sh           # preflight validation before first boot
 docker compose up -d
 docker compose --profile autoupdate up -d watchtower  # optional auto-updates
 bash scripts/configure.sh
@@ -141,11 +148,18 @@ Optional music:
 
 All download traffic routes through ProtonVPN (with optional NordVPN failover). Gluetun's built-in kill switch blocks traffic if the VPN drops, so your real IP is never exposed through the tunnel. Everything else uses your normal connection. All services auto-start on boot and self-heal if they go down.
 
+To manually switch providers after creating `.env.nord` from `.env.nord.example`:
+
+```bash
+bash scripts/vpn-mode.sh nord
+```
+
 ## Scripts
 
 | Script | Purpose |
 |--------|---------|
 | `scripts/setup.sh` | Creates folders, generates .env, copies config templates |
+| `scripts/doctor.sh` | Runs preflight checks (runtime, env, compose, ports) |
 | `scripts/configure.sh` | Auto-configures all service connections via API |
 | `scripts/health-check.sh` | Full stack health diagnostic |
 | `scripts/install-launchd-jobs.sh` | Installs all automation as background jobs |

SETUP.md

@@ -16,6 +16,12 @@ curl -fsSL https://raw.githubusercontent.com/liamvibecodes/mac-media-stack-advan
 
 It will prompt you for VPN keys, configure all services, and install automation jobs. You'll still need to do Step 7 (configure Recyclarr, Kometa, Tdarr, and Unpackerr with API keys) manually afterward.
 
+To run from a local clone with custom paths:
+
+```bash
+bash bootstrap.sh --media-dir /Volumes/T9/Media --install-dir ~/mac-media-stack-advanced
+```
+
 ---
 
 ## Prerequisites
@@ -68,6 +74,8 @@ cd ~
 git clone https://github.com/liamvibecodes/mac-media-stack-advanced.git
 cd mac-media-stack-advanced
 bash scripts/setup.sh
+# or:
+# bash scripts/setup.sh --media-dir /Volumes/T9/Media
 ```
 
 ---
@@ -84,6 +92,14 @@ Fill in `WIREGUARD_PRIVATE_KEY` and `WIREGUARD_ADDRESSES` from your ProtonVPN ac
 
 ## Step 4: Start the Stack
 
+Run preflight checks before first startup:
+
+```bash
+bash scripts/doctor.sh
+```
+
+Then start the stack:
+
 ```bash
 docker compose up -d
 bash scripts/health-check.sh
@@ -138,6 +154,7 @@ bash scripts/configure.sh
 ```
 
 This configures qBittorrent, Prowlarr (indexers), Radarr, Sonarr, and Seerr. It will print your API keys at the end. **Save them.**
+It also writes credentials/API keys to `~/Media/state/first-run-credentials.txt` (mode `600`).
 
 ---
 
@@ -226,6 +243,12 @@ bash scripts/install-vpn-failover.sh
 ```
 
 This checks every 2 minutes and auto-switches between Proton and Nord after 3 consecutive failures.
+Use `docker-compose.nord-fallback.yml` only for Nord mode; Proton remains the default compose path.
+
+Check current provider anytime:
+```bash
+bash scripts/vpn-mode.sh status
+```
 
 ---
 

bootstrap.sh

@@ -10,6 +10,64 @@ YELLOW='\033[1;33m'
 CYAN='\033[0;36m'
 NC='\033[0m'
 
+MEDIA_DIR="$HOME/Media"
+INSTALL_DIR="$HOME/mac-media-stack-advanced"
+NON_INTERACTIVE=false
+
+usage() {
+    cat <<EOF
+Usage: bash bootstrap.sh [OPTIONS]
+
+Options:
+  --media-dir DIR       Media root path (default: ~/Media)
+  --install-dir DIR     Repo install directory (default: ~/mac-media-stack-advanced)
+  --non-interactive     Skip interactive prompts (manual Seerr wiring required)
+  --help                Show this help message
+
+Examples:
+  bash bootstrap.sh
+  bash bootstrap.sh --media-dir /Volumes/T9/Media
+  bash bootstrap.sh --media-dir /Volumes/T9/Media --non-interactive
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --media-dir)
+            if [[ $# -lt 2 || "$2" == --* ]]; then
+                echo "Missing value for --media-dir"
+                exit 1
+            fi
+            MEDIA_DIR="$2"
+            shift 2
+            ;;
+        --install-dir)
+            if [[ $# -lt 2 || "$2" == --* ]]; then
+                echo "Missing value for --install-dir"
+                exit 1
+            fi
+            INSTALL_DIR="$2"
+            shift 2
+            ;;
+        --non-interactive)
+            NON_INTERACTIVE=true
+            shift
+            ;;
+        --help|-h)
+            usage
+            exit 0
+            ;;
+        *)
+            echo "Unknown option: $1"
+            usage
+            exit 1
+            ;;
+    esac
+done
+
+MEDIA_DIR="${MEDIA_DIR/#\~/$HOME}"
+INSTALL_DIR="${INSTALL_DIR/#\~/$HOME}"
+
 echo ""
 echo "======================================="
 echo "  Mac Media Stack Installer (Advanced)"
@@ -51,6 +109,27 @@ detect_running_runtime() {
     fi
 }
 
+wait_for_service() {
+    local name="$1"
+    local url="$2"
+    local max_attempts="${3:-45}"
+    local attempt=0
+    local status
+
+    while [[ $attempt -lt $max_attempts ]]; do
+        status=$(curl -s -o /dev/null -w "%{http_code}" --max-time 3 "$url" 2>/dev/null || true)
+        if [[ "$status" =~ ^(200|301|302|401|403)$ ]]; then
+            echo -e "  ${GREEN}OK${NC}  $name is reachable"
+            return 0
+        fi
+        sleep 2
+        attempt=$((attempt + 1))
+    done
+
+    echo -e "  ${YELLOW}WARN${NC}  $name is not reachable yet (continuing anyway)"
+    return 1
+}
+
 INSTALLED_RUNTIME=$(detect_installed_runtime)
 
 if ! docker info &>/dev/null; then
@@ -85,10 +164,12 @@ if ! command -v git &>/dev/null; then
     exit 1
 fi
 
+echo ""
+echo "Install dir: $INSTALL_DIR"
+echo "Media dir:   $MEDIA_DIR"
 echo ""
 
 # Clone
-INSTALL_DIR="$HOME/mac-media-stack-advanced"
 if [[ -d "$INSTALL_DIR" ]]; then
     echo -e "${YELLOW}Note:${NC} $INSTALL_DIR already exists. Pulling latest..."
     if ! git -C "$INSTALL_DIR" pull --ff-only; then
@@ -107,41 +188,65 @@ echo ""
 
 # Setup
 echo -e "${CYAN}Running setup...${NC}"
-bash scripts/setup.sh
+bash scripts/setup.sh --media-dir "$MEDIA_DIR"
 
 echo ""
 
 # VPN keys
 if grep -q "your_wireguard_private_key_here" .env 2>/dev/null; then
-    echo -e "${CYAN}VPN Configuration${NC}"
-    echo ""
-    read -s -p "  WireGuard Private Key: " vpn_key
-    echo ""
-    read -p "  WireGuard Address (e.g. 10.2.0.2/32): " vpn_addr
-
-    if [[ -n "$vpn_key" && -n "$vpn_addr" ]]; then
-        sed -i '' "s|WIREGUARD_PRIVATE_KEY=.*|WIREGUARD_PRIVATE_KEY=$vpn_key|" .env
-        sed -i '' "s|WIREGUARD_ADDRESSES=.*|WIREGUARD_ADDRESSES=$vpn_addr|" .env
-        echo -e "  ${GREEN}VPN keys saved${NC}"
+    if [[ "$NON_INTERACTIVE" == true ]]; then
+        echo -e "${YELLOW}WARN${NC}  Non-interactive mode: VPN placeholders still present in .env"
+        echo "  Update WIREGUARD_PRIVATE_KEY and WIREGUARD_ADDRESSES before using the stack."
     else
-        echo -e "  ${YELLOW}Skipped.${NC} Edit .env manually: open -a TextEdit $INSTALL_DIR/.env"
+        echo -e "${CYAN}VPN Configuration${NC}"
+        echo ""
+        read -s -p "  WireGuard Private Key: " vpn_key
+        echo ""
+        read -p "  WireGuard Address (e.g. 10.2.0.2/32): " vpn_addr
+
+        if [[ -n "$vpn_key" && -n "$vpn_addr" ]]; then
+            sed -i '' "s|WIREGUARD_PRIVATE_KEY=.*|WIREGUARD_PRIVATE_KEY=$vpn_key|" .env
+            sed -i '' "s|WIREGUARD_ADDRESSES=.*|WIREGUARD_ADDRESSES=$vpn_addr|" .env
+            echo -e "  ${GREEN}VPN keys saved${NC}"
+        else
+            echo -e "  ${YELLOW}Skipped.${NC} Edit .env manually: open -a TextEdit $INSTALL_DIR/.env"
+        fi
     fi
 fi
 
 echo ""
 
+# Preflight
+echo -e "${CYAN}Running preflight checks...${NC}"
+if ! bash scripts/doctor.sh --media-dir "$MEDIA_DIR"; then
+    echo ""
+    echo -e "${RED}Preflight checks failed.${NC} Fix the FAIL items above, then re-run bootstrap."
+    exit 1
+fi
+
+echo ""
+
 # Start stack
 echo -e "${CYAN}Starting media stack (first run downloads ~3-5 GB)...${NC}"
 echo ""
 docker compose up -d
 
 echo ""
-echo "Waiting 30 seconds for services to initialize..."
-sleep 30
+echo "Waiting for core services..."
+wait_for_service "qBittorrent" "http://localhost:8080" || true
+wait_for_service "Prowlarr" "http://localhost:9696" || true
+wait_for_service "Radarr" "http://localhost:7878" || true
+wait_for_service "Sonarr" "http://localhost:8989" || true
+wait_for_service "Seerr" "http://localhost:5055" || true
+wait_for_service "Tdarr" "http://localhost:8265" || true
 
 # Configure
 echo ""
-bash scripts/configure.sh
+if [[ "$NON_INTERACTIVE" == true ]]; then
+    bash scripts/configure.sh --non-interactive
+else
+    bash scripts/configure.sh
+fi
 
 # Install automation
 echo ""
@@ -157,10 +262,12 @@ echo "  Seerr:  http://localhost:5055"
 echo "  Plex:   http://localhost:32400/web"
 echo "  Tdarr:  http://localhost:8265"
 echo ""
+echo "  Media location: $MEDIA_DIR"
+echo ""
 echo "  Remaining manual steps:"
-echo "    1. Set up Plex libraries (Movies: ~/Media/Movies, TV: ~/Media/TV Shows)"
-echo "    2. Edit ~/Media/config/recyclarr/recyclarr.yml with your API keys"
-echo "    3. Edit ~/Media/config/kometa/config.yml with Plex token + TMDB key"
+echo "    1. Set up Plex libraries (Movies: $MEDIA_DIR/Movies, TV: $MEDIA_DIR/TV Shows)"
+echo "    2. Edit $MEDIA_DIR/config/recyclarr/recyclarr.yml with your API keys"
+echo "    3. Edit $MEDIA_DIR/config/kometa/config.yml with Plex token + TMDB key"
 echo "    4. Update .env with Unpackerr API keys, then: docker compose restart unpackerr"
 echo "    5. Configure Tdarr at http://localhost:8265"
 echo ""

scripts/auto-heal.sh

@@ -25,22 +25,25 @@ fi
 HEALED=0
 
 # Check VPN
-vpn_ip=$(docker exec gluetun sh -c 'wget -qO- --timeout=5 https://ipinfo.io/ip' 2>/dev/null)
-local_ip=$(curl -s --max-time 5 https://ipinfo.io/ip 2>/dev/null)
+vpn_ip=$(docker exec gluetun sh -lc 'cat /tmp/gluetun/ip 2>/dev/null || true' 2>/dev/null)
+vpn_iface=$(docker exec gluetun sh -lc 'ls /sys/class/net 2>/dev/null | grep -E "^(tun|wg)[0-9]+$" | head -1' 2>/dev/null)
+vpn_health=$(docker inspect -f '{{if .State.Health}}{{.State.Health.Status}}{{else}}unknown{{end}}' gluetun 2>/dev/null || true)
 
-if [[ -z "$vpn_ip" || "$vpn_ip" == "$local_ip" ]]; then
-    log "WARN: VPN issue. Restarting gluetun..."
+if [[ -z "$vpn_ip" || -z "$vpn_iface" || "$vpn_health" == "unhealthy" ]]; then
+    log "WARN: VPN issue (health=${vpn_health:-unknown}, ip=${vpn_ip:-none}, iface=${vpn_iface:-none}). Restarting gluetun..."
     docker restart gluetun >> "$LOG" 2>&1
     sleep 15
-    vpn_ip=$(docker exec gluetun sh -c 'wget -qO- --timeout=5 https://ipinfo.io/ip' 2>/dev/null)
-    if [[ -n "$vpn_ip" && "$vpn_ip" != "$local_ip" ]]; then
-        log "OK: VPN recovered (IP: $vpn_ip)"
+    vpn_ip=$(docker exec gluetun sh -lc 'cat /tmp/gluetun/ip 2>/dev/null || true' 2>/dev/null)
+    vpn_iface=$(docker exec gluetun sh -lc 'ls /sys/class/net 2>/dev/null | grep -E "^(tun|wg)[0-9]+$" | head -1' 2>/dev/null)
+    vpn_health=$(docker inspect -f '{{if .State.Health}}{{.State.Health.Status}}{{else}}unknown{{end}}' gluetun 2>/dev/null || true)
+    if [[ -n "$vpn_ip" && -n "$vpn_iface" && "$vpn_health" != "unhealthy" ]]; then
+        log "OK: VPN recovered (IP: $vpn_ip, iface=$vpn_iface, health=${vpn_health:-unknown})"
     else
-        log "ERROR: VPN still down after restart"
+        log "ERROR: VPN still down after restart (health=${vpn_health:-unknown}, ip=${vpn_ip:-none}, iface=${vpn_iface:-none})"
     fi
     ((HEALED++))
 else
-    log "OK: VPN active (IP: $vpn_ip)"
+    log "OK: VPN active (IP: $vpn_ip, iface=$vpn_iface, health=${vpn_health:-unknown})"
 fi
 
 # Check containers