feat: add NAS storage support via rclone SFTP

Extends existing cloud storage infrastructure to support NAS devices
(TrueNAS, Synology, Unraid) over SFTP. Same rclone + mergerfs compose,
different backend and LAN-optimized defaults.

- Add --storage-type nas to setup wizard with SSH key gen, Synology
  chroot detection, and connectivity testing
- Add --nas-storage flag to bootstrap.sh
- Make dir-cache-time configurable via RCLONE_DIR_CACHE_TIME env var
- Add NAS health checks to doctor.sh (key perms, SFTP connectivity)
- Dynamic upload intervals in launchd (2h NAS, 6h cloud)
- Add SFTP examples to rclone.conf.example
- Add NAS compose render test to CI
- Update README and SETUP with NAS docs

Author: liamvibecodes

.env.example

@@ -59,3 +59,19 @@ JELLYSTAT_DB_PASSWORD=
 # RCLONE_VFS_CACHE_MAX_AGE=72h
 # RCLONE_VFS_READ_CHUNK_SIZE=128M
 # CLOUD_UPLOAD_MIN_AGE_HOURS=24
+# RCLONE_DIR_CACHE_TIME=5m
+
+# --- NAS STORAGE (rclone SFTP + mergerfs) ---
+# Same infrastructure as cloud storage, optimized for LAN.
+# Uses rclone SFTP to mount NAS inside Docker (where FUSE works on macOS).
+# Run: bash scripts/setup-cloud-storage.sh --storage-type nas
+#
+# STORAGE_TYPE=nas
+# CLOUD_STORAGE_ENABLED=true
+# RCLONE_REMOTE=mynas
+# RCLONE_REMOTE_PATH=/mnt/pool/dataset/media
+# RCLONE_VFS_CACHE_MAX_SIZE=10G
+# RCLONE_VFS_CACHE_MAX_AGE=1h
+# RCLONE_VFS_READ_CHUNK_SIZE=32M
+# RCLONE_DIR_CACHE_TIME=30s
+# CLOUD_UPLOAD_MIN_AGE_HOURS=2

.github/workflows/validate.yml

@@ -57,4 +57,11 @@ jobs:
           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
+
+          # NAS storage compose (same overlay, different env vars)
+          sed -i 's/^RCLONE_VFS_CACHE_MAX_SIZE=50G/RCLONE_VFS_CACHE_MAX_SIZE=10G/' .env
+          echo 'STORAGE_TYPE=nas' >> .env
+          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
           rm .env

README.md

@@ -56,7 +56,7 @@ New to self-hosted media? Start with the [basic version](https://github.com/liam
 | **Intro Skipper** | Jellyfin plugin: auto-detects intros and adds a "Skip Intro" button on TV shows |
 | **TMDb Box Sets** | Jellyfin plugin: auto-creates franchise collections from TMDb data (Jellyfin's Kometa) |
 | **Jellystat** | Jellyfin analytics dashboard (like Tautulli for Plex: watch history, user stats, library insights) |
-| **Cloud Storage** | rclone + mergerfs: transparent cloud/local merged library (Google Drive, S3, B2, Dropbox) |
+| **Cloud / NAS Storage** | rclone + mergerfs: transparent remote/local merged library (Google Drive, S3, B2, Dropbox, NAS via SFTP) |
 
 ## Choosing Your Media Server
 
@@ -96,11 +96,11 @@ After the stack is running:
 
 Jellystat will start tracking watch history, user activity, and library statistics automatically.
 
-## Optional: Cloud Storage (rclone + mergerfs)
+## Optional: Cloud / NAS Storage (rclone + mergerfs)
 
-Transparent cloud/local merged library. rclone FUSE-mounts your cloud storage inside Docker (where FUSE works natively), mergerfs overlays it with local storage, and all existing services see a single unified path. Local-first writes keep downloads fast; a periodic upload script moves stable media to the cloud.
+Transparent cloud/local or NAS/local merged library. rclone FUSE-mounts your remote storage inside Docker (where FUSE works natively on macOS), mergerfs overlays it with local storage, and all existing services see a single unified path. Local-first writes keep downloads fast; a periodic upload script moves stable media to the remote.
 
-Supports Google Drive, S3, Backblaze B2, Dropbox, and [40+ other providers](https://rclone.org/overview/).
+Supports Google Drive, S3, Backblaze B2, Dropbox, NAS via SFTP (TrueNAS, Synology, Unraid), and [40+ other providers](https://rclone.org/overview/).
 
 ### Compatibility Requirements (macOS)
 
@@ -123,13 +123,26 @@ Or include it in bootstrap:
 bash bootstrap.sh --cloud-storage
 ```
 
+### NAS Quick Start
+
+```bash
+bash scripts/setup-cloud-storage.sh --storage-type nas
+docker compose -f docker-compose.yml -f docker-compose.cloud-storage.yml --profile cloud-storage --profile jellyfin --profile tdarr-docker up -d
+```
+
+Or include it in bootstrap:
+
+```bash
+bash bootstrap.sh --nas-storage
+```
+
 ### How It Works
 
 ```
 rclone-mount  -->  FUSE mounts cloud provider to /cloud
 mergerfs      -->  overlays /local + /cloud into /merged
 Radarr/Sonarr -->  read/write /merged (local-first writes)
-cloud-upload  -->  every 6h, moves files >24h old to cloud
+cloud-upload  -->  periodically moves stable files to remote (6h/24h for cloud, 2h for NAS)
 ```
 
 ### Library paths when cloud storage is enabled
@@ -150,6 +163,24 @@ cloud-upload  -->  every 6h, moves files >24h old to cloud
 | `RCLONE_VFS_READ_CHUNK_SIZE` | `128M` | Read chunk size |
 | `CLOUD_UPLOAD_MIN_AGE_HOURS` | `24` | Only upload files older than this |
 
+### NAS Configuration (LAN-Optimized Defaults)
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `STORAGE_TYPE` | (empty) | Set to `nas` for NAS mode |
+| `RCLONE_DIR_CACHE_TIME` | `30s` | Directory listing cache (shorter for LAN) |
+| `RCLONE_VFS_CACHE_MAX_SIZE` | `10G` | Smaller cache needed on fast LAN |
+| `RCLONE_VFS_CACHE_MAX_AGE` | `1h` | Shorter cache age on LAN |
+| `RCLONE_VFS_READ_CHUNK_SIZE` | `32M` | Read chunk size |
+| `CLOUD_UPLOAD_MIN_AGE_HOURS` | `2` | Upload files older than 2h (vs 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.
+- **Unraid:** Path is `/mnt/user/media`
+
+**Performance:** rclone SFTP delivers ~100MB/s on Gigabit LAN, adequate for multiple concurrent 4K streams.
+
 **Cloud mode note:** Use `TDARR_MODE=docker` when cloud storage is enabled. Native Tdarr cannot access merged Docker FUSE mounts on macOS.
 
 ## Optional: Music (Lidarr + Tidarr)
@@ -185,7 +216,7 @@ Then open Tidarr at `http://localhost:8484` to authenticate with your Tidal acco
 | Log prune | Daily | Removes log files older than 30 days |
 | Franchise sort | Optional/manual | Sorts franchise collection movies by release date in Plex (Plex only) |
 | VPN failover | Every 2 min (optional) | Auto-switches between ProtonVPN and NordVPN on sustained failure |
-| Cloud upload | Every 6 hours (optional) | Moves local media older than 24h to cloud storage |
+| Cloud upload | Every 2-6 hours (optional) | Moves stable local media to remote storage (NAS: 2h, cloud: 6h) |
 | 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:
@@ -241,6 +272,12 @@ To use Jellyfin instead of Plex:
 bash bootstrap.sh --jellyfin
 ```
 
+NAS storage via SFTP (TrueNAS, Synology, Unraid):
+
+```bash
+bash bootstrap.sh --nas-storage
+```
+
 ## Update Existing Clone
 
 Already cloned an older version and want the latest release tag without reinstalling?

SETUP.md

@@ -335,9 +335,9 @@ Everything else is fully automated.
 
 ---
 
-## Optional: Cloud Storage (rclone + mergerfs)
+## Optional: Cloud / NAS Storage (rclone + mergerfs)
 
-If your local disk is too small for your full library, cloud storage lets you extend it transparently. rclone mounts your cloud provider (Google Drive, S3, B2, Dropbox, etc.) inside Docker, and mergerfs overlays it with your local storage so all services see one unified library.
+If your local disk is too small for your full library, or you have a NAS with plenty of space, remote storage lets you extend your library transparently. rclone mounts your cloud provider or NAS (via SFTP) inside Docker, and mergerfs overlays it with your local storage so all services see one unified library.
 
 ### Compatibility (macOS)
 
@@ -365,6 +365,33 @@ docker compose -f docker-compose.yml -f docker-compose.cloud-storage.yml --profi
 
 Or pass `--cloud-storage` to `bootstrap.sh` for a full install.
 
+### NAS Setup (TrueNAS, Synology, Unraid)
+
+```bash
+bash scripts/setup-cloud-storage.sh --storage-type nas
+```
+
+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
+5. Test connectivity before writing the config
+6. Write NAS-optimized VFS cache settings to `.env`
+
+**SSH key setup:** If you generate a new key, the wizard prints the public key. Add it to your NAS:
+- **TrueNAS:** Accounts > Users > [user] > SSH Public Key
+- **Synology:** DSM > Control Panel > User > [user] > Edit > SSH Key
+- **Unraid:** Tools > User SSH Keys, or append to `~/.ssh/authorized_keys`
+
+**Start with NAS storage:**
+
+```bash
+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`
+
 ### 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`.
@@ -392,6 +419,22 @@ docker exec rclone-mount rclone ls myremote: --max-depth 1
 docker restart rclone-mount && sleep 15 && docker restart mergerfs
 ```
 
+### NAS-specific troubleshooting
+
+```bash
+# Verify SSH key permissions
+ls -la ~/Media/config/rclone/nas_key.pem
+# Should show -rw------- (600)
+
+# Test NAS connectivity directly
+docker run --rm -v ~/Media/config/rclone:/config/rclone rclone/rclone lsd mynas: --contimeout 10s
+
+# Check SFTP connection speed
+docker run --rm -v ~/Media/config/rclone:/config/rclone rclone/rclone test bandwidth mynas: --duration 10s
+
+# Synology: if paths don't resolve, check sftp_path_override in rclone.conf
+```
+
 ---
 
 ## Troubleshooting

bootstrap.sh

@@ -17,6 +17,7 @@ NON_INTERACTIVE=false
 MEDIA_SERVER=plex
 TDARR_MODE=native
 CLOUD_STORAGE=false
+NAS_STORAGE=false
 
 usage() {
     cat <<EOF
@@ -29,6 +30,7 @@ Options:
   --tdarr-mode MODE     Tdarr mode: native (default) or docker
   --tdarr-docker        Shortcut for --tdarr-mode docker
   --cloud-storage       Enable cloud storage (rclone + mergerfs)
+  --nas-storage         Enable NAS storage via SFTP (rclone + mergerfs)
   --non-interactive     Skip interactive prompts (manual Seerr wiring required)
   --help                Show this help message
 
@@ -37,6 +39,7 @@ Examples:
   bash bootstrap.sh --media-dir /Volumes/T9/Media
   bash bootstrap.sh --tdarr-docker
   bash bootstrap.sh --jellyfin --cloud-storage --tdarr-docker
+  bash bootstrap.sh --jellyfin --nas-storage --tdarr-docker
   bash bootstrap.sh --media-dir /Volumes/T9/Media --non-interactive
 EOF
 }
@@ -79,6 +82,11 @@ while [[ $# -gt 0 ]]; do
             CLOUD_STORAGE=true
             shift
             ;;
+        --nas-storage)
+            NAS_STORAGE=true
+            CLOUD_STORAGE=true
+            shift
+            ;;
         --non-interactive)
             NON_INTERACTIVE=true
             shift
@@ -334,11 +342,14 @@ fi
 if [[ "$CLOUD_STORAGE" == true ]]; then
     echo ""
     echo -e "${CYAN}Setting up cloud storage...${NC}"
+    SETUP_ARGS=("--media-dir" "$MEDIA_DIR")
+    if [[ "$NAS_STORAGE" == true ]]; then
+        SETUP_ARGS+=("--storage-type" "nas")
+    fi
     if [[ "$NON_INTERACTIVE" == true ]]; then
-        bash scripts/setup-cloud-storage.sh --media-dir "$MEDIA_DIR" --non-interactive
-    else
-        bash scripts/setup-cloud-storage.sh --media-dir "$MEDIA_DIR"
+        SETUP_ARGS+=("--non-interactive")
     fi
+    bash scripts/setup-cloud-storage.sh "${SETUP_ARGS[@]}"
 fi
 
 echo ""
@@ -506,8 +517,13 @@ else
 fi
 echo ""
 if [[ "$CLOUD_ACTIVE" == true ]]; then
-    echo "  Cloud storage: enabled (rclone + mergerfs)"
-    echo "  Uploads run every 6 hours via launchd"
+    if [[ "$NAS_STORAGE" == true ]]; then
+        echo "  NAS storage: enabled (rclone SFTP + mergerfs)"
+        echo "  Uploads run every 2 hours via launchd"
+    else
+        echo "  Cloud storage: enabled (rclone + mergerfs)"
+        echo "  Uploads run every 6 hours via launchd"
+    fi
     echo ""
 fi
 

configs/rclone.conf.example

@@ -40,3 +40,40 @@
 # [local-test]
 # type = local
 # nounc = true
+
+# ── NAS via SFTP (recommended for TrueNAS, Synology, Unraid) ────────
+# https://rclone.org/sftp/
+# SFTP gives ~100MB/s on Gigabit LAN (vs ~20MB/s for rclone SMB).
+# SSH key auth recommended for unattended operation.
+#
+# The setup wizard can generate keys for you:
+#   bash scripts/setup-cloud-storage.sh --storage-type nas
+
+# TrueNAS (key auth)
+# [mynas]
+# type = sftp
+# host = 192.168.1.100
+# user = media
+# key_file = /config/rclone/nas_key.pem
+
+# Synology (key auth + path override for SFTP chroot)
+# [synology]
+# type = sftp
+# host = 192.168.1.101
+# user = media
+# key_file = /config/rclone/nas_key.pem
+# sftp_path_override = /volume1/media
+
+# Unraid (key auth)
+# [unraid]
+# type = sftp
+# host = 192.168.1.102
+# user = root
+# key_file = /config/rclone/nas_key.pem
+
+# Generic NAS (password auth — run: rclone obscure YOUR_PASSWORD)
+# [nas-password]
+# type = sftp
+# host = 192.168.1.100
+# user = media
+# pass = OBSCURED_PASSWORD_HERE

docker-compose.cloud-storage.yml

@@ -24,7 +24,7 @@ services:
       --vfs-cache-max-size ${RCLONE_VFS_CACHE_MAX_SIZE:-50G}
       --vfs-cache-max-age ${RCLONE_VFS_CACHE_MAX_AGE:-72h}
       --vfs-read-chunk-size ${RCLONE_VFS_READ_CHUNK_SIZE:-128M}
-      --dir-cache-time 5m
+      --dir-cache-time ${RCLONE_DIR_CACHE_TIME:-5m}
       --poll-interval 15s
       --log-level INFO
     volumes:

scripts/cloud-upload.sh

@@ -13,6 +13,8 @@ BASE_DIR="$(resolve_media_dir "$PROJECT_DIR")"
 # shellcheck disable=SC1091
 source "$PROJECT_DIR/.env" 2>/dev/null || true
 
+STORAGE_TYPE="${STORAGE_TYPE:-cloud}"
+
 # Exit silently if cloud storage not enabled
 if [[ "${CLOUD_STORAGE_ENABLED:-}" != "true" ]]; then
     exit 0
@@ -56,7 +58,7 @@ if [[ ! -f "$RCLONE_CONF" ]]; then
     exit 1
 fi
 
-log "--- Cloud upload started ---"
+log "--- Cloud upload started (${STORAGE_TYPE}) ---"
 
 # Move Movies
 if [[ -d "$BASE_DIR/Movies" ]]; then
@@ -90,4 +92,4 @@ if [[ -d "$BASE_DIR/TV Shows" ]]; then
     log "TV Shows upload complete (exit: $?)"
 fi
 
-log "--- Cloud upload finished ---"
+log "--- Cloud upload finished (${STORAGE_TYPE}) ---"

scripts/doctor.sh

@@ -236,6 +236,41 @@ if [[ "$CLOUD_STORAGE_ENABLED" == "true" ]]; then
     fi
 fi
 
+# NAS-specific checks
+STORAGE_TYPE=""
+if [[ -f "$ENV_FILE" ]]; then
+    STORAGE_TYPE=$(sed -n 's/^STORAGE_TYPE=//p' "$ENV_FILE" | head -1)
+fi
+
+if [[ "$STORAGE_TYPE" == "nas" ]]; then
+    nas_key="$MEDIA_DIR/config/rclone/nas_key.pem"
+    if [[ -f "$nas_key" ]]; then
+        ok "NAS SSH key exists"
+        key_perms=$(stat -f '%Lp' "$nas_key" 2>/dev/null || stat -c '%a' "$nas_key" 2>/dev/null || echo "unknown")
+        if [[ "$key_perms" == "600" ]]; then
+            ok "NAS SSH key permissions are 600"
+        else
+            fail "NAS SSH key permissions are $key_perms (expected 600)"
+        fi
+    else
+        warn "No NAS SSH key found at $nas_key (password auth may be in use)"
+    fi
+
+    # Test NAS connectivity
+    rclone_conf="$MEDIA_DIR/config/rclone/rclone.conf"
+    env_remote=$(sed -n 's/^RCLONE_REMOTE=//p' "$ENV_FILE" | head -1)
+    if [[ -n "$env_remote" && -f "$rclone_conf" ]]; then
+        if docker run --rm \
+            -v "$MEDIA_DIR/config/rclone:/config/rclone" \
+            rclone/rclone lsd "${env_remote}:" \
+            --contimeout 10s 2>/dev/null; then
+            ok "NAS reachable via rclone SFTP"
+        else
+            fail "Cannot reach NAS via rclone SFTP (check network/credentials)"
+        fi
+    fi
+fi
+
 PORTS="5055 9696 8989 7878 8080 6767 8191 8265 8266"
 if [[ "$MEDIA_SERVER" == "jellyfin" ]]; then
     PORTS="$PORTS 8096"