fix: harden NAS storage setup and compatibility flow

Author: liamvibecodes

.github/workflows/validate.yml

@@ -64,4 +64,5 @@ jobs:
           echo 'RCLONE_DIR_CACHE_TIME=30s' >> .env
           docker compose -f docker-compose.yml -f docker-compose.cloud-storage.yml --profile cloud-storage config >/dev/null
           docker compose -f docker-compose.yml -f docker-compose.cloud-storage.yml --profile cloud-storage --profile jellyfin config >/dev/null
+          docker compose -f docker-compose.yml -f docker-compose.cloud-storage.yml --profile cloud-storage --profile tdarr-docker config >/dev/null
           rm .env

README.md

@@ -120,7 +120,7 @@ If you also use optional profiles, append them to the same command (example: `--
 Or include it in bootstrap:
 
 ```bash
-bash bootstrap.sh --cloud-storage
+bash bootstrap.sh --jellyfin --cloud-storage
 ```
 
 ### NAS Quick Start
@@ -133,7 +133,7 @@ docker compose -f docker-compose.yml -f docker-compose.cloud-storage.yml --profi
 Or include it in bootstrap:
 
 ```bash
-bash bootstrap.sh --nas-storage
+bash bootstrap.sh --jellyfin --nas-storage
 ```
 
 ### How It Works
@@ -176,7 +176,7 @@ cloud-upload  -->  periodically moves stable files to remote (6h/24h for cloud,
 
 **Platform notes:**
 - **TrueNAS:** Media path is typically `/mnt/pool/dataset/media`
-- **Synology:** Path is `/volume1/media`. The setup wizard auto-adds `--sftp-path-override` for SFTP chroot compatibility.
+- **Synology:** Path is `/volume1/media`. The setup wizard auto-adds a `path_override` config (equivalent to `--sftp-path-override`) for SFTP chroot compatibility.
 - **Unraid:** Path is `/mnt/user/media`
 
 **Performance:** rclone SFTP delivers ~100MB/s on Gigabit LAN, adequate for multiple concurrent 4K streams.
@@ -275,7 +275,7 @@ bash bootstrap.sh --jellyfin
 NAS storage via SFTP (TrueNAS, Synology, Unraid):
 
 ```bash
-bash bootstrap.sh --nas-storage
+bash bootstrap.sh --jellyfin --nas-storage
 ```
 
 ## Update Existing Clone

SETUP.md

@@ -363,7 +363,7 @@ The setup wizard will:
 docker compose -f docker-compose.yml -f docker-compose.cloud-storage.yml --profile cloud-storage --profile jellyfin --profile tdarr-docker up -d
 ```
 
-Or pass `--cloud-storage` to `bootstrap.sh` for a full install.
+Or pass `--jellyfin --cloud-storage` to `bootstrap.sh` for a full install.
 
 ### NAS Setup (TrueNAS, Synology, Unraid)
 
@@ -375,7 +375,7 @@ The wizard will:
 1. Ask for your NAS hostname/IP and SSH username
 2. Offer to generate an SSH key pair (recommended), use an existing key, or use password auth
 3. Ask for your media path with platform-specific examples
-4. Auto-detect Synology paths and add `--sftp-path-override` for SFTP chroot compatibility
+4. Auto-detect Synology paths and add `path_override` (same effect as `--sftp-path-override`) for SFTP chroot compatibility
 5. Test connectivity before writing the config
 6. Write NAS-optimized VFS cache settings to `.env`
 
@@ -390,13 +390,13 @@ The wizard will:
 docker compose -f docker-compose.yml -f docker-compose.cloud-storage.yml --profile cloud-storage --profile jellyfin --profile tdarr-docker up -d
 ```
 
-Or use bootstrap: `bash bootstrap.sh --nas-storage`
+Or use bootstrap: `bash bootstrap.sh --jellyfin --nas-storage`
 
 ### How it works
 
-- **Write path:** Downloads land on local disk (fast). Every 6 hours, `cloud-upload.sh` moves files older than 24h to the cloud via `rclone move`.
-- **Read path:** Docker services (Jellyfin, Arr apps, Tdarr Docker) read from the mergerfs overlay, which transparently serves files from local or cloud storage.
-- **VFS cache:** rclone caches recently accessed cloud files locally (default 50GB, 72h max age). Adjust `RCLONE_VFS_CACHE_MAX_SIZE` in `.env` based on your available disk space.
+- **Write path:** Downloads land on local disk (fast). `cloud-upload.sh` periodically moves stable files to remote storage (cloud default: every 6h; NAS default: every 2h).
+- **Read path:** Docker services (Jellyfin, Arr apps, Tdarr Docker) read from the mergerfs overlay, which transparently serves files from local or remote storage.
+- **VFS cache:** rclone caches recently accessed remote files locally. Cloud defaults are larger (50GB/72h), NAS defaults are smaller/faster (10GB/1h).
 
 ### Library paths when cloud storage is enabled
 

bootstrap.sh

@@ -372,13 +372,21 @@ COMPOSE_PROFILES=()
 
 # Detect cloud storage from .env (may have been set by setup-cloud-storage.sh or flag)
 CLOUD_ENABLED_ENV=""
+STORAGE_TYPE_ENV=""
 if [[ -f .env ]]; then
     CLOUD_ENABLED_ENV=$(sed -n 's/^CLOUD_STORAGE_ENABLED=//p' .env | head -1)
+    STORAGE_TYPE_ENV=$(sed -n 's/^STORAGE_TYPE=//p' .env | head -1)
 fi
 CLOUD_ACTIVE=false
 if [[ "$CLOUD_STORAGE" == true || "$CLOUD_ENABLED_ENV" == "true" ]]; then
     CLOUD_ACTIVE=true
 fi
+STORAGE_TYPE_EFFECTIVE="$STORAGE_TYPE_ENV"
+if [[ "$NAS_STORAGE" == true ]]; then
+    STORAGE_TYPE_EFFECTIVE="nas"
+elif [[ -z "$STORAGE_TYPE_EFFECTIVE" && "$CLOUD_ACTIVE" == true ]]; then
+    STORAGE_TYPE_EFFECTIVE="cloud"
+fi
 
 if [[ "$CLOUD_ACTIVE" == true && "$MEDIA_SERVER" == "plex" ]]; then
     echo -e "${RED}Cloud storage requires Jellyfin in this stack.${NC}"
@@ -388,7 +396,11 @@ if [[ "$CLOUD_ACTIVE" == true && "$MEDIA_SERVER" == "plex" ]]; then
     echo "  Native Plex cannot read those merged cloud mount paths on macOS."
     echo ""
     echo "Use one of these options:"
-    echo "  1. Re-run with Jellyfin: bash bootstrap.sh --jellyfin --cloud-storage"
+    if [[ "$STORAGE_TYPE_EFFECTIVE" == "nas" ]]; then
+        echo "  1. Re-run with Jellyfin: bash bootstrap.sh --jellyfin --nas-storage"
+    else
+        echo "  1. Re-run with Jellyfin: bash bootstrap.sh --jellyfin --cloud-storage"
+    fi
     echo "  2. Disable cloud storage and keep Plex: set CLOUD_STORAGE_ENABLED=false in .env"
     exit 1
 fi
@@ -503,7 +515,7 @@ echo "  Remaining manual steps:"
 if [[ "$MEDIA_SERVER" == "jellyfin" ]]; then
     echo "    1. Complete Jellyfin setup wizard at http://localhost:8096"
     if [[ "$CLOUD_ACTIVE" == true ]]; then
-        echo "       Add libraries: Movies = /data/movies, TV Shows = /data/tvshows (merged cloud/local)"
+        echo "       Add libraries: Movies = /data/movies, TV Shows = /data/tvshows (merged remote/local)"
     else
         echo "       Add libraries: Movies = /data/movies, TV Shows = /data/tvshows"
     fi
@@ -517,7 +529,7 @@ else
 fi
 echo ""
 if [[ "$CLOUD_ACTIVE" == true ]]; then
-    if [[ "$NAS_STORAGE" == true ]]; then
+    if [[ "$STORAGE_TYPE_EFFECTIVE" == "nas" ]]; then
         echo "  NAS storage: enabled (rclone SFTP + mergerfs)"
         echo "  Uploads run every 2 hours via launchd"
     else

scripts/doctor.sh

@@ -9,6 +9,7 @@ GREEN='\033[0;32m'
 YELLOW='\033[1;33m'
 CYAN='\033[0;36m'
 NC='\033[0m'
+RCLONE_IMAGE="${RCLONE_IMAGE:-rclone/rclone@sha256:c08f5e100e1c4fa4deb1315b56a47c0cc0e765222b7c0834bc93305f2e4d85c0}"
 
 SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
 ENV_FILE="$SCRIPT_DIR/.env"
@@ -243,6 +244,10 @@ if [[ -f "$ENV_FILE" ]]; then
 fi
 
 if [[ "$STORAGE_TYPE" == "nas" ]]; then
+    if [[ "$CLOUD_STORAGE_ENABLED" != "true" ]]; then
+        warn "STORAGE_TYPE=nas is set but CLOUD_STORAGE_ENABLED is not true"
+    fi
+
     nas_key="$MEDIA_DIR/config/rclone/nas_key.pem"
     if [[ -f "$nas_key" ]]; then
         ok "NAS SSH key exists"
@@ -259,10 +264,15 @@ if [[ "$STORAGE_TYPE" == "nas" ]]; then
     # Test NAS connectivity
     rclone_conf="$MEDIA_DIR/config/rclone/rclone.conf"
     env_remote=$(sed -n 's/^RCLONE_REMOTE=//p' "$ENV_FILE" | head -1)
+    env_remote_path=$(sed -n 's/^RCLONE_REMOTE_PATH=//p' "$ENV_FILE" | head -1)
     if [[ -n "$env_remote" && -f "$rclone_conf" ]]; then
+        nas_target="${env_remote}:"
+        if [[ -n "$env_remote_path" ]]; then
+            nas_target="${env_remote}:${env_remote_path}"
+        fi
         if docker run --rm \
             -v "$MEDIA_DIR/config/rclone:/config/rclone" \
-            rclone/rclone lsd "${env_remote}:" \
+            "$RCLONE_IMAGE" lsd "$nas_target" \
             --contimeout 10s 2>/dev/null; then
             ok "NAS reachable via rclone SFTP"
         else

scripts/install-launchd-jobs.sh

@@ -115,8 +115,6 @@ if [[ "${CLOUD_STORAGE_ENABLED:-}" == "true" ]]; then
     upload_interval=21600
     if [[ "${STORAGE_TYPE:-}" == "nas" ]]; then
         upload_interval=7200
-    elif [[ -n "${CLOUD_UPLOAD_MIN_AGE_HOURS:-}" ]]; then
-        upload_interval=$((CLOUD_UPLOAD_MIN_AGE_HOURS * 3600))
     fi
     install_plist "cloud-upload" "$upload_interval" "$SCRIPT_DIR/cloud-upload.sh" "false"
 fi