Streamline automation paths and align setup behavior

Author: liamvibecodes

.github/workflows/validate.yml

@@ -20,7 +20,22 @@ jobs:
 
       - name: Validate python scripts
         run: |
-          python3 -m py_compile scripts/download-watchdog.py
+          while IFS= read -r -d '' f; do
+            python3 -m py_compile "$f"
+          done < <(find scripts -type f -name '*.py' -print0)
+
+      - name: Validate media path usage
+        run: |
+          # Automation scripts must resolve MEDIA_DIR from env/.env, not hardcode $HOME/Media.
+          ! rg -n '\$HOME/Media' \
+            scripts/auto-heal.sh \
+            scripts/backup.sh \
+            scripts/download-watchdog.py \
+            scripts/install-launchd-jobs.sh \
+            scripts/install-vpn-failover.sh \
+            scripts/log-prune.sh \
+            scripts/setup-music.sh \
+            scripts/vpn-failover-watch.sh
 
       - name: Validate compose config
         run: |

README.md

@@ -32,7 +32,7 @@
 There are dozens of *arr stack Docker Compose repos on GitHub. Almost all of them dump a compose file and leave you to figure out the rest. This one is different:
 
 - **One command to install.** Clone, configure, and start everything with a single `curl | bash`. No 45-minute manual setup.
-- **Auto-configures itself.** The configure script wires up all 13 services via their APIs. No clicking through web UIs.
+- **Auto-configures itself.** The configure script wires up the core request/download stack via API (qBittorrent, Prowlarr, Radarr, Sonarr, Seerr). No clicking through those web UIs.
 - **Built for macOS.** Native paths, launchd instead of systemd, OrbStack or Docker Desktop instead of bare Docker. Not a Linux guide with "should work on Mac" in the footnotes.
 - **Self-healing.** Hourly health checks, download watchdog, VPN failover between providers. Runs unattended.
 - **Quality automation.** TRaSH Guides profiles filter out bad releases. Kometa keeps Plex metadata clean. Tdarr saves disk space with automatic transcoding.
@@ -75,9 +75,12 @@ Then open Tidarr at `http://localhost:8484` to authenticate with your Tidal acco
 | Download watchdog | Every 15 min | Detects stalled/slow torrents, auto-fixes or swaps them |
 | Kometa | Every 4 hours | Updates Plex collections and metadata overlays |
 | Log prune | Daily | Removes log files older than 30 days |
-| Franchise sort | After Kometa | Sorts franchise collection movies by release date in Plex |
+| Franchise sort | Optional/manual | Sorts franchise collection movies by release date in Plex |
 | VPN failover | Every 2 min (optional) | Auto-switches between ProtonVPN and NordVPN on sustained failure |
-| Watchtower | Weekly (optional) | Auto-pulls latest container images and recreates updated services |
+| Watchtower | Daily at 04:00 (optional) | Auto-pulls latest container images and recreates updated services |
+
+Franchise sorting is kept manual by default because it requires your Plex token:
+`PLEX_TOKEN=... python3 scripts/franchise-sort.py`
 
 ## One-Command Install
 
@@ -115,7 +118,7 @@ bash scripts/configure.sh
 bash scripts/install-launchd-jobs.sh
 ```
 
-The `watchtower` line above enables automatic container image updates (checks weekly). It's optional but recommended so your services stay patched without manual pulls.
+The `watchtower` line above enables automatic container image updates (scheduled daily at 04:00 in compose). It's optional but recommended so your services stay patched without manual pulls.
 
 ## Full Setup Guide
 
@@ -221,7 +224,7 @@ docker compose --profile music up -d
 
 ### Tidarr Download Config
 
-The setup script creates a default `tiddl` config at `~/Media/config/tidarr/.tiddl/config.toml`. Key settings:
+The setup script creates a default `tiddl` config at `<MEDIA_DIR>/config/tidarr/.tiddl/config.toml` (default `<MEDIA_DIR>` is `~/Media`). Key settings:
 
 - **Quality:** `max` (24-bit Hi-Res FLAC when available, falls back to 16-bit/44.1kHz)
 - **Download path:** Your Plex music folder (files go directly to the library)
@@ -282,7 +285,7 @@ bash scripts/archive-media.sh --execute --archive /Volumes/External/Media-Archiv
 bash scripts/archive-media.sh --execute --archive /Volumes/External/Media-Archive --only-watched
 ```
 
-**Protecting favorites:** `scripts/setup.sh` creates `~/Media/config/archive-exceptions.txt` for you. Add one title per line and anything listed won't be archived regardless of age or size. See `configs/archive-exceptions.txt.example` for the format.
+**Protecting favorites:** `scripts/setup.sh` creates `<MEDIA_DIR>/config/archive-exceptions.txt` for you (default `<MEDIA_DIR>` is `~/Media`). Add one title per line and anything listed won't be archived regardless of age or size. See `configs/archive-exceptions.txt.example` for the format.
 
 The script verifies file counts after copying and only deletes the source if the counts match. If verification fails, your original files are untouched.
 

SETUP.md

@@ -65,6 +65,8 @@ Or download from https://orbstack.dev. Open it once after installing.
 
 Both options use the same `docker` and `docker compose` commands. Everything in this guide works identically with either one.
 
+If you use a custom media location (`MEDIA_DIR` in `.env`), replace any `~/Media` path below with that value.
+
 ---
 
 ## Step 2: Download and Setup
@@ -154,7 +156,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`).
+It also writes credentials/API keys to `<MEDIA_DIR>/state/first-run-credentials.txt` (mode `600`, default path `~/Media/state/first-run-credentials.txt`).
 
 ---
 
@@ -171,7 +173,7 @@ It also writes credentials/API keys to `~/Media/state/first-run-credentials.txt`
 
 ### Recyclarr (TRaSH quality profiles)
 
-The setup script copied a template to `~/Media/config/recyclarr/recyclarr.yml`. Open it and replace the API key placeholders with the keys printed by configure.sh:
+The setup script copied a template to `<MEDIA_DIR>/config/recyclarr/recyclarr.yml` (default: `~/Media/config/recyclarr/recyclarr.yml`). Open it and replace the API key placeholders with the keys printed by configure.sh:
 
 ```bash
 open -a TextEdit ~/Media/config/recyclarr/recyclarr.yml
@@ -228,8 +230,9 @@ This installs:
 - Nightly backup (configs + databases, 14-day retention)
 - Download watchdog (stalled torrent auto-fix every 15 min)
 - Kometa scheduler (metadata refresh every 4 hours)
+- Log prune (daily log cleanup with 30-day retention)
 
-Automation logs go to `~/Media/logs/` and launchd stdout/stderr logs go to `~/Media/logs/launchd/`.
+Automation logs go to `<MEDIA_DIR>/logs/` and launchd stdout/stderr logs go to `<MEDIA_DIR>/logs/launchd/` (default `~/Media/...`).
 
 ### Optional: VPN Failover
 
@@ -277,6 +280,7 @@ bash scripts/health-check.sh
 tail -50 ~/Media/logs/auto-heal.log
 tail -50 ~/Media/logs/download-watchdog.log
 tail -50 ~/Media/logs/vpn-failover.log
+tail -50 ~/Media/logs/log-prune.log
 ```
 
 **Manual VPN switch:**

bootstrap.sh

@@ -10,6 +10,7 @@ YELLOW='\033[1;33m'
 CYAN='\033[0;36m'
 NC='\033[0m'
 
+BOOTSTRAP_DIR="$(cd "$(dirname "$0")" && pwd)"
 MEDIA_DIR="$HOME/Media"
 INSTALL_DIR="$HOME/mac-media-stack-advanced"
 NON_INTERACTIVE=false
@@ -75,60 +76,65 @@ echo "======================================="
 echo ""
 
 # Detect container runtime
-detect_installed_runtime() {
-    local has_orbstack=0
-    local has_docker_desktop=0
-
-    if [[ -d "/Applications/OrbStack.app" ]] || command -v orbstack &>/dev/null; then
-        has_orbstack=1
-    fi
-    if [[ -d "/Applications/Docker.app" ]]; then
-        has_docker_desktop=1
-    fi
-
-    if [[ $has_orbstack -eq 1 && $has_docker_desktop -eq 1 ]]; then
-        echo "OrbStack or Docker Desktop"
-    elif [[ $has_orbstack -eq 1 ]]; then
-        echo "OrbStack"
-    elif [[ $has_docker_desktop -eq 1 ]]; then
-        echo "Docker Desktop"
-    else
-        echo "none"
-    fi
-}
+if [[ -f "$BOOTSTRAP_DIR/scripts/lib/runtime.sh" ]]; then
+    # shellcheck source=scripts/lib/runtime.sh
+    source "$BOOTSTRAP_DIR/scripts/lib/runtime.sh"
+else
+    detect_installed_runtime() {
+        local has_orbstack=0
+        local has_docker_desktop=0
 
-detect_running_runtime() {
-    local os_name
-    os_name=$(docker info --format '{{.OperatingSystem}}' 2>/dev/null || true)
-    if [[ "$os_name" == *"OrbStack"* ]]; then
-        echo "OrbStack"
-    elif [[ "$os_name" == *"Docker Desktop"* ]]; then
-        echo "Docker Desktop"
-    else
-        echo "Docker"
-    fi
-}
+        if [[ -d "/Applications/OrbStack.app" ]] || command -v orbstack &>/dev/null; then
+            has_orbstack=1
+        fi
+        if [[ -d "/Applications/Docker.app" ]]; then
+            has_docker_desktop=1
+        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
+        if [[ $has_orbstack -eq 1 && $has_docker_desktop -eq 1 ]]; then
+            echo "OrbStack or Docker Desktop"
+        elif [[ $has_orbstack -eq 1 ]]; then
+            echo "OrbStack"
+        elif [[ $has_docker_desktop -eq 1 ]]; then
+            echo "Docker Desktop"
+        else
+            echo "none"
         fi
-        sleep 2
-        attempt=$((attempt + 1))
-    done
+    }
+
+    detect_running_runtime() {
+        local os_name
+        os_name=$(docker info --format '{{.OperatingSystem}}' 2>/dev/null || true)
+        if [[ "$os_name" == *"OrbStack"* ]]; then
+            echo "OrbStack"
+        elif [[ "$os_name" == *"Docker Desktop"* ]]; then
+            echo "Docker Desktop"
+        else
+            echo "Docker"
+        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
-}
+        echo -e "  ${YELLOW}WARN${NC}  $name is not reachable yet (continuing anyway)"
+        return 1
+    }
+fi
 
 INSTALLED_RUNTIME=$(detect_installed_runtime)
 

scripts/archive-media.sh

@@ -4,11 +4,15 @@
 
 set -euo pipefail
 
+PROJECT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+# shellcheck source=scripts/lib/media-path.sh
+source "$PROJECT_DIR/scripts/lib/media-path.sh"
+
 EXECUTE=0
 DAYS=180
 MIN_SIZE_GB=8
 TYPE="both"
-SOURCE_ROOT="$HOME/Media"
+SOURCE_ROOT="$(resolve_media_dir "$PROJECT_DIR")"
 ARCHIVE_ROOT=""
 LOG_FILE=""
 ONLY_WATCHED=0

scripts/auto-heal.sh

@@ -2,7 +2,12 @@
 # Media Stack Auto-Healer
 # Runs hourly via launchd. Checks VPN and container health, restarts what's broken.
 
-BASE_DIR="$HOME/Media"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+# shellcheck source=scripts/lib/media-path.sh
+source "$SCRIPT_DIR/lib/media-path.sh"
+
+BASE_DIR="$(resolve_media_dir "$PROJECT_DIR")"
 LOG_DIR="$BASE_DIR/logs"
 mkdir -p "$LOG_DIR"
 LOG="$LOG_DIR/auto-heal.log"

scripts/backup.sh

@@ -4,16 +4,20 @@
 
 set -euo pipefail
 
-BASE_DIR="$HOME/Media"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+# shellcheck source=scripts/lib/media-path.sh
+source "$SCRIPT_DIR/lib/media-path.sh"
+
+BASE_DIR="$(resolve_media_dir "$PROJECT_DIR")"
 BACKUP_ROOT="$BASE_DIR/backups"
 TS="$(date +%Y%m%d-%H%M%S)"
 OUT="$BACKUP_ROOT/$TS"
 
 mkdir -p "$OUT"/{configs,dbs,state}
 
 # Backup compose and env
-SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
-cp "$SCRIPT_DIR/docker-compose.yml" "$OUT/" 2>/dev/null || true
+cp "$PROJECT_DIR/docker-compose.yml" "$OUT/" 2>/dev/null || true
 
 # Backup config files
 find "$BASE_DIR/config" -maxdepth 2 -type f \( -name 'config.xml' -o -name 'config.yml' -o -name 'settings.json' -o -name '*.conf' \) -print0 | while IFS= read -r -d '' f; do
@@ -30,7 +34,7 @@ find "$BASE_DIR/config" -maxdepth 2 -type f -name '*.db' -print0 | while IFS= re
 done
 
 # Snapshot container status
-if ! docker compose -f "$SCRIPT_DIR/docker-compose.yml" ps > "$OUT/state/compose-ps.txt" 2>/dev/null; then
+if ! docker compose -f "$PROJECT_DIR/docker-compose.yml" ps > "$OUT/state/compose-ps.txt" 2>/dev/null; then
     echo "$(date '+%F %T') WARN: could not capture docker compose status snapshot" >> "$BASE_DIR/logs/backup.log"
 fi
 

scripts/configure.sh

@@ -325,7 +325,7 @@ echo "  Prowlarr API Key: $PROWLARR_KEY"
 echo "  Saved credentials: $CREDS_FILE"
 echo ""
 echo -e "  ${YELLOW}Save these!${NC} You'll need the API keys for:"
-echo "    - configs/recyclarr.yml (copy to ~/Media/config/recyclarr/)"
+echo "    - configs/recyclarr.yml (copy to $MEDIA_DIR/config/recyclarr/)"
 echo "    - .env (UN_SONARR_0_API_KEY and UN_RADARR_0_API_KEY for Unpackerr)"
 echo ""
 echo "  Seerr:       http://localhost:5055"

scripts/download-watchdog.py

@@ -18,7 +18,23 @@
 import http.cookiejar
 from pathlib import Path
 
-BASE_DIR = Path(os.path.expanduser("~/Media"))
+def load_media_dir() -> Path:
+    env_media = os.getenv("MEDIA_DIR")
+    if env_media:
+        return Path(os.path.expanduser(env_media))
+
+    env_path = Path(__file__).resolve().parents[1] / ".env"
+    if env_path.exists():
+        for line in env_path.read_text(errors="ignore").splitlines():
+            if line.startswith("MEDIA_DIR="):
+                value = line.split("=", 1)[1].strip().strip('"').strip("'")
+                if value:
+                    return Path(os.path.expanduser(value))
+
+    return Path.home() / "Media"
+
+
+BASE_DIR = load_media_dir()
 STATE_FILE = BASE_DIR / "state" / "download-watchdog-state.json"
 LOG_FILE = BASE_DIR / "logs" / "download-watchdog.log"
 RADARR_CFG = BASE_DIR / "config" / "radarr" / "config.xml"

scripts/franchise-sort.py

@@ -23,11 +23,28 @@
 import logging
 import os
 import sys
+from pathlib import Path
+
+def load_default_media_log_dir() -> str:
+    env_media = os.getenv("MEDIA_DIR")
+    if env_media:
+        return os.path.expanduser(os.path.join(env_media, "logs"))
+
+    env_path = Path(__file__).resolve().parents[1] / ".env"
+    if env_path.exists():
+        for line in env_path.read_text(errors="ignore").splitlines():
+            if line.startswith("MEDIA_DIR="):
+                value = line.split("=", 1)[1].strip().strip('"').strip("'")
+                if value:
+                    return os.path.expanduser(os.path.join(value, "logs"))
+
+    return os.path.expanduser("~/Media/logs")
+
 
 PLEX_URL = os.environ.get("PLEX_URL", "http://localhost:32400")
 PLEX_TOKEN = os.environ.get("PLEX_TOKEN", "")
 SECTION_ID = os.environ.get("PLEX_SECTION_ID", "1")
-LOG_DIR = os.environ.get("MEDIA_LOG_DIR", os.path.expanduser("~/Media/logs"))
+LOG_DIR = os.environ.get("MEDIA_LOG_DIR", load_default_media_log_dir())
 DRY_RUN = False