Improve installer flexibility and preflight reliability

Author: liamvibecodes

README.md

@@ -64,6 +64,12 @@ Requires OrbStack (or Docker Desktop) and Plex already installed. Handles everyt
 curl -fsSL https://raw.githubusercontent.com/liamvibecodes/mac-media-stack/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 --non-interactive
+```
+
 <details>
 <summary>See it in action</summary>
 <br>
@@ -79,6 +85,7 @@ git clone https://github.com/liamvibecodes/mac-media-stack.git
 cd mac-media-stack
 bash scripts/setup.sh        # creates folders, generates .env
 # edit .env and add your VPN keys
+bash scripts/doctor.sh       # preflight validation before first boot
 docker compose up -d          # start everything
 docker compose --profile autoupdate up -d watchtower  # optional auto-updates
 bash scripts/configure.sh     # auto-configure all services
@@ -96,6 +103,7 @@ By default, Seerr is bound to `127.0.0.1` for safer local-only access. Set `SEER
 | Script | Purpose |
 |--------|---------|
 | `scripts/setup.sh` | Creates folder structure and .env file |
+| `scripts/doctor.sh` | Runs preflight checks (runtime, env, compose, ports) |
 | `scripts/configure.sh` | Auto-configures all service connections |
 | `scripts/health-check.sh` | Checks if everything is running correctly |
 | `scripts/auto-heal.sh` | Hourly self-healer (restarts VPN/containers if down) |

SETUP.md

@@ -21,6 +21,12 @@ curl -fsSL https://raw.githubusercontent.com/liamvibecodes/mac-media-stack/main/
 
 It will prompt you for VPN keys and walk you through the Seerr login. If you'd rather do each step yourself, continue with the manual guide below.
 
+You can also run it locally with custom paths:
+
+```bash
+bash bootstrap.sh --media-dir /Volumes/T9/Media --install-dir ~/mac-media-stack
+```
+
 ---
 
 ## What You Need
@@ -133,13 +139,19 @@ WIREGUARD_ADDRESSES=10.2.0.2/32
 
 ## Step 6: Start the Stack
 
+Run preflight checks before first startup:
+
 ```bash
-docker compose up -d
+bash scripts/doctor.sh
 ```
 
-This will download everything it needs (about 2-3 GB, may take a few minutes on the first run). You'll see each service being created.
+Then start services:
+
+```bash
+docker compose up -d
+```
 
-When it's done, wait about 30 seconds for everything to start up, then run the health check:
+This will download everything it needs (about 2-3 GB, may take a few minutes on the first run). You'll see each service being created. After it starts, run the health check:
 
 ```bash
 bash scripts/health-check.sh
@@ -179,7 +191,7 @@ The script will:
 - Connect everything together (Prowlarr, Radarr, Sonarr, Seerr)
 - Ask you to sign in to Seerr with Plex (one browser click)
 
-At the end it will print your qBittorrent password. Save it somewhere just in case, but you shouldn't need it for normal use.
+At the end it will print your qBittorrent password and save credentials/API keys to `~/Media/state/first-run-credentials.txt` (mode `600`).
 
 ---
 ## Step 9: Install Auto-Healer (Optional but Recommended)

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"
+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)
+  --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"
@@ -51,6 +109,26 @@ detect_running_runtime() {
     fi
 }
 
+wait_for_service() {
+    local name="$1"
+    local url="$2"
+    local max_attempts="${3:-45}"
+    local attempt=0
+
+    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 +163,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"
 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,46 +187,69 @@ 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 ""
-    echo "You need your ProtonVPN WireGuard credentials."
-    echo "If someone gave you a private key and address, enter them now."
-    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 before starting."
-        echo "  Run: open -a TextEdit $INSTALL_DIR/.env"
+        echo -e "${CYAN}VPN Configuration${NC}"
+        echo ""
+        echo "You need your ProtonVPN WireGuard credentials."
+        echo "If someone gave you a private key and address, enter them now."
+        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 before starting."
+            echo "  Run: 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...${NC}"
 echo "  (First run downloads ~2-3 GB, this may take a few minutes)"
 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
 
 # Configure
 echo ""
-bash scripts/configure.sh
+if [[ "$NON_INTERACTIVE" == true ]]; then
+    bash scripts/configure.sh --non-interactive
+else
+    bash scripts/configure.sh
+fi
 
 # Auto-heal
 echo ""
@@ -161,7 +264,9 @@ echo ""
 echo "  Seerr (browse/request):  http://localhost:5055"
 echo "  Plex (watch):            http://localhost:32400/web"
 echo ""
+echo "  Media location:          $MEDIA_DIR"
+echo ""
 echo "  Next: Set up Plex libraries (Settings > Libraries > Add)"
-echo "    - Movies: ~/Media/Movies"
-echo "    - TV Shows: ~/Media/TV Shows"
+echo "    - Movies: $MEDIA_DIR/Movies"
+echo "    - TV Shows: $MEDIA_DIR/TV Shows"
 echo ""

scripts/auto-heal.sh

@@ -26,27 +26,25 @@ fi
 HEALED=0
 
 # Check VPN tunnel
-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" ]]; then
-    log "WARN: VPN not responding. Restarting gluetun..."
+if [[ -z "$vpn_ip" || -z "$vpn_iface" || "$vpn_health" == "unhealthy" ]]; then
+    log "WARN: VPN status unhealthy (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})"
         ((HEALED++))
     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
-elif [[ "$vpn_ip" == "$local_ip" ]]; then
-    log "WARN: VPN IP matches real IP. Tunnel not working. Restarting gluetun..."
-    docker restart gluetun >> "$LOG" 2>&1
-    sleep 15
-    ((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 core containers are running