Security and stability improvements

- Updated kill switch test in SETUP.md to use docker stop instead of killall
- Added 50GB disk space requirement and ProtonVPN link to prerequisites
- Replaced weak password generation with openssl rand -hex 12
- Extended API key timeout from 30s to 60s
- Added VPN key validation loop in bootstrap.sh
- Added docker compose error checking with helpful failure message
- Removed duplicate log-prune launchd install
- Improved log trimming with mktemp and trap for safety
- Added .env.nord placeholder validation in vpn-mode.sh
- Added timeout parameters to franchise-sort.py urlopen calls
- Added qBittorrent password validation in download-watchdog.py
- Added health checks to all services (qbittorrent, sonarr, radarr, prowlarr, bazarr, seerr, tdarr)
- Added Tdarr resource limits (4 CPUs, 8GB RAM)
- Added explanatory comments for cap_add and docker.sock mounts
- Added SEERR_BIND_IP security warning in .env.example
- Added download watchdog environment variables documentation to README

Author: liamvibecodes

.env.example

@@ -17,7 +17,7 @@ TIMEZONE=America/New_York
 
 # --- WEB ACCESS ---
 # Seerr bind IP: keep 127.0.0.1 for local-only (recommended default).
-# Set to 0.0.0.0 only if you intentionally expose Seerr on your LAN.
+# WARNING: Setting to 0.0.0.0 exposes Seerr to your entire network. Use 127.0.0.1 for local-only access.
 SEERR_BIND_IP=127.0.0.1
 
 # --- VPN (ProtonVPN WireGuard) ---

README.md

@@ -83,6 +83,19 @@ Then open Tidarr at `http://localhost:8484` to authenticate with your Tidal acco
 Franchise sorting is kept manual by default because it requires your Plex token:
 `PLEX_TOKEN=... python3 scripts/franchise-sort.py`
 
+### Download Watchdog Configuration
+
+The download watchdog reads qBittorrent credentials and behavior settings from environment variables or automatically detects them from your config files. Optional environment variables:
+
+- `QBIT_USERNAME` (default: `admin`)
+- `QBIT_PASSWORD` (auto-detected from qBittorrent config if not set)
+- `WATCHDOG_STALL_SECONDS` (default: `1800` — how long a torrent must be stalled before auto-swap)
+- `WATCHDOG_SLOW_SECONDS` (default: `1200` — how long a torrent must be slow before auto-swap)
+- `WATCHDOG_MIN_SPEED_BPS` (default: `307200` — 300 KB/s minimum speed threshold)
+- `WATCHDOG_MAX_SWAP_PROGRESS` (default: `0.25` — never swap torrents past 25% complete)
+
+Set these in `.env` or your shell environment if you need to customize watchdog behavior.
+
 ## One-Command Install
 
 Requires OrbStack (or Docker Desktop) and Plex already installed. Handles everything else.

SETUP.md

@@ -29,6 +29,7 @@ Already running the basic stack and want an in-place migration? Use [UPGRADE.md]
 ## Prerequisites
 
 - A Mac (any recent macOS)
+- At least 50GB free disk space (media libraries will need more)
 - [OrbStack](https://orbstack.dev) (recommended) or [Docker Desktop](https://www.docker.com/products/docker-desktop/) installed and running
 - Plex installed and signed in
 - ProtonVPN WireGuard credentials
@@ -92,6 +93,8 @@ open -a TextEdit .env
 
 Fill in `WIREGUARD_PRIVATE_KEY` and `WIREGUARD_ADDRESSES` from your ProtonVPN account.
 
+Get your WireGuard private key from https://account.protonvpn.com/downloads#wireguard-configuration
+
 ---
 
 ## Step 4: Start the Stack
@@ -135,14 +138,15 @@ curl -s https://ipinfo.io/ip
 To test the kill switch (traffic should be blocked when the VPN drops):
 
 ```bash
-# Kill the VPN process inside the container
-docker exec gluetun sh -c 'killall -SIGUSR1 openvpn'
+# Stop the VPN container
+docker stop gluetun
 
-# Try reaching the internet from inside the VPN namespace — should fail/timeout
-docker exec gluetun sh -c 'wget -qO- --timeout=5 https://ipinfo.io/ip'
+# Try reaching the internet from qBittorrent — should fail/timeout
+# (qBittorrent is routed through gluetun and should have no network when gluetun is down)
+docker exec qbittorrent wget -qO- --timeout=5 https://ipinfo.io/ip 2>&1 || echo "Kill switch works: qBittorrent has no network"
 
 # Restore the VPN
-docker restart gluetun
+docker start gluetun
 ```
 
 If the second `wget` returns an IP instead of timing out, your kill switch isn't working. Check your Gluetun configuration.

bootstrap.sh

@@ -206,8 +206,17 @@ if grep -q "your_wireguard_private_key_here" .env 2>/dev/null; then
     else
         echo -e "${CYAN}VPN Configuration${NC}"
         echo ""
-        read -s -p "  WireGuard Private Key: " vpn_key
-        echo ""
+
+        # Loop until we get a non-empty private key
+        vpn_key=""
+        while [[ -z "$vpn_key" ]]; do
+            read -s -p "  WireGuard Private Key: " vpn_key
+            echo ""
+            if [[ -z "$vpn_key" ]]; then
+                echo -e "  ${RED}Private key cannot be empty. Please enter a valid key.${NC}"
+            fi
+        done
+
         read -p "  WireGuard Address (e.g. 10.2.0.2/32): " vpn_addr
 
         if [[ -n "$vpn_key" && -n "$vpn_addr" ]]; then
@@ -235,7 +244,15 @@ echo ""
 # Start stack
 echo -e "${CYAN}Starting media stack (first run downloads ~3-5 GB)...${NC}"
 echo ""
-docker compose up -d
+if ! docker compose up -d; then
+    echo ""
+    echo -e "${RED}Failed to start the stack.${NC} Check the error output above."
+    echo "Common issues:"
+    echo "  - Missing or invalid VPN credentials in .env"
+    echo "  - Conflicting port bindings (close other apps using ports 8080, 9696, etc.)"
+    echo "  - Insufficient disk space"
+    exit 1
+fi
 
 echo ""
 echo "Waiting for core services..."

docker-compose.yml

@@ -2,6 +2,7 @@ services:
   gluetun:
     image: qmcgaw/gluetun@sha256:495cdc65ace4c110cf4de3d1f5f90e8a1dd2eb0f8b67151d1ad6101b2a02a476
     container_name: gluetun
+    # Grants network admin capabilities needed for VPN tunnel management
     cap_add:
       - NET_ADMIN
     devices:
@@ -38,6 +39,11 @@ services:
       - ${MEDIA_DIR}/Downloads:/downloads
       - ${MEDIA_DIR}/Movies:/movies
       - ${MEDIA_DIR}/TV Shows:/tv
+    healthcheck:
+      test: ["CMD-SHELL", "curl -f http://localhost:8080 || exit 1"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
     restart: unless-stopped
 
   prowlarr:
@@ -51,6 +57,11 @@ services:
       - ${MEDIA_DIR}/config/prowlarr:/config
     ports:
       - 127.0.0.1:9696:9696
+    healthcheck:
+      test: ["CMD-SHELL", "curl -f http://localhost:9696/ping || exit 1"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
     restart: unless-stopped
 
   sonarr:
@@ -66,6 +77,11 @@ services:
       - ${MEDIA_DIR}/Downloads:/downloads
     ports:
       - 127.0.0.1:8989:8989
+    healthcheck:
+      test: ["CMD-SHELL", "curl -f http://localhost:8989/ping || exit 1"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
     restart: unless-stopped
 
   radarr:
@@ -81,6 +97,11 @@ services:
       - ${MEDIA_DIR}/Downloads:/downloads
     ports:
       - 127.0.0.1:7878:7878
+    healthcheck:
+      test: ["CMD-SHELL", "curl -f http://localhost:7878/ping || exit 1"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
     restart: unless-stopped
 
   bazarr:
@@ -96,6 +117,11 @@ services:
       - ${MEDIA_DIR}/TV Shows:/tv
     ports:
       - 127.0.0.1:6767:6767
+    healthcheck:
+      test: ["CMD-SHELL", "curl -f http://localhost:6767/ping || exit 1"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
     restart: unless-stopped
 
   flaresolverr:
@@ -119,6 +145,11 @@ services:
       - ${MEDIA_DIR}/config/seerr:/app/config
     ports:
       - ${SEERR_BIND_IP:-127.0.0.1}:5055:5055
+    healthcheck:
+      test: ["CMD-SHELL", "curl -f http://localhost:5055/api/v1/status || exit 1"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
     restart: unless-stopped
 
   tdarr:
@@ -143,6 +174,16 @@ services:
     ports:
       - 127.0.0.1:8265:8265
       - 127.0.0.1:8266:8266
+    healthcheck:
+      test: ["CMD-SHELL", "curl -f http://localhost:8265 || exit 1"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+    deploy:
+      resources:
+        limits:
+          cpus: '4'
+          memory: 8G
     restart: unless-stopped
 
   unpackerr:
@@ -231,5 +272,6 @@ services:
       - WATCHTOWER_CLEANUP=true
       - WATCHTOWER_SCHEDULE=0 0 4 * * *
     volumes:
+      # Allows Watchtower to manage Docker containers
       - /var/run/docker.sock:/var/run/docker.sock
     restart: unless-stopped

scripts/auto-heal.sh

@@ -17,7 +17,10 @@ log() { echo "$(timestamp) $1" >> "$LOG"; }
 
 # Trim log
 if [[ -f "$LOG" ]] && [[ $(wc -l < "$LOG") -gt 500 ]]; then
-    tail -500 "$LOG" > "$LOG.tmp" && mv "$LOG.tmp" "$LOG"
+    tmp=$(mktemp)
+    trap "rm -f '$tmp'" EXIT
+    tail -n 1000 "$LOG" > "$tmp" && mv "$tmp" "$LOG"
+    trap - EXIT
 fi
 
 log "--- Health check started ---"

scripts/configure.sh

@@ -48,7 +48,7 @@ if [[ ! -f "$SCRIPT_DIR/.env" ]]; then
 fi
 source "$SCRIPT_DIR/.env"
 
-QB_PASSWORD="media$(date +%s | shasum | head -c 8)"
+QB_PASSWORD="media$(openssl rand -hex 12)"
 CREDS_FILE="$MEDIA_DIR/state/first-run-credentials.txt"
 
 log() { echo -e "  ${GREEN}OK${NC}  $1"; }
@@ -209,7 +209,7 @@ wait_for_service() {
 get_api_key() {
     local service="$1"
     local config_path="$MEDIA_DIR/config/$service/config.xml"
-    local max_attempts=15 attempt=0
+    local max_attempts=30 attempt=0
     while [[ $attempt -lt $max_attempts ]]; do
         if [[ -f "$config_path" ]]; then
             local key=$(grep -o '<ApiKey>[^<]*</ApiKey>' "$config_path" 2>/dev/null | sed 's/<[^>]*>//g')

scripts/download-watchdog.py

@@ -168,6 +168,10 @@ def main():
         log("[ERROR] No API keys found")
         return 1
 
+    if not QBIT_PASSWORD:
+        log("[ERROR] QBIT_PASSWORD is not set. Check your environment or credentials file.")
+        return 1
+
     try:
         qbit = make_qbit_opener()
     except Exception as exc:

scripts/franchise-sort.py

@@ -104,15 +104,15 @@ def require_arg(flag: str) -> str:
 
 def plex_get(path):
     url = f"{PLEX_URL}{path}?X-Plex-Token={PLEX_TOKEN}"
-    resp = urllib.request.urlopen(url)
+    resp = urllib.request.urlopen(url, timeout=30)
     return ET.parse(resp).getroot()
 
 
 def plex_put(path, params):
     params["X-Plex-Token"] = PLEX_TOKEN
     url = f"{PLEX_URL}{path}?{urllib.parse.urlencode(params)}"
     req = urllib.request.Request(url, method="PUT")
-    return urllib.request.urlopen(req)
+    return urllib.request.urlopen(req, timeout=30)
 
 
 def get_collections():

scripts/install-launchd-jobs.sh

@@ -104,8 +104,6 @@ install_plist "download-watchdog" 900 "$SCRIPT_DIR/download-watchdog.py" "false"
 
 # Kometa one-shot (every 4 hours = 14400s)
 install_plist "kometa" 14400 "$SCRIPT_DIR/run-kometa.sh"
-# Log prune (every 24 hours)
-install_plist "log-prune" 86400 "$SCRIPT_DIR/log-prune.sh"
 
 echo ""
 echo -e "${YELLOW}Optional:${NC} VPN failover (requires NordVPN as backup)"