feat: add cloud storage mode with jellyfin guardrails

Author: liamvibecodes

.env.example

@@ -47,3 +47,15 @@ JELLYSTAT_DB_PASSWORD=
 # --- OPTIONAL: MUSIC (Lidarr + Tidarr) ---
 # Uncomment if using music services (bash scripts/setup-music.sh)
 # UN_LIDARR_0_API_KEY=your_lidarr_api_key_here
+
+# --- CLOUD STORAGE (rclone + mergerfs) ---
+# Uncomment if using cloud storage (bash scripts/setup-cloud-storage.sh)
+# Note: cloud-backed playback on macOS requires MEDIA_SERVER=jellyfin and TDARR_MODE=docker.
+# CLOUD_STORAGE_ENABLED=true
+# RCLONE_REMOTE=myremote
+# RCLONE_REMOTE_PATH=
+# RCLONE_VFS_CACHE_MODE=full
+# RCLONE_VFS_CACHE_MAX_SIZE=50G
+# RCLONE_VFS_CACHE_MAX_AGE=72h
+# RCLONE_VFS_READ_CHUNK_SIZE=128M
+# CLOUD_UPLOAD_MIN_AGE_HOURS=24

.github/workflows/validate.yml

@@ -35,6 +35,8 @@ jobs:
             scripts/install-vpn-failover.sh \
             scripts/log-prune.sh \
             scripts/setup-music.sh \
+            scripts/setup-cloud-storage.sh \
+            scripts/cloud-upload.sh \
             scripts/vpn-failover-watch.sh
 
       - name: Validate compose config
@@ -43,4 +45,16 @@ jobs:
           docker compose --profile autoupdate --profile music config >/dev/null
           docker compose --profile jellyfin config >/dev/null
           docker compose --profile autoupdate --profile music --profile jellyfin config >/dev/null
+
+          # Cloud storage compose override
+          sed -i 's/^# CLOUD_STORAGE_ENABLED=true/CLOUD_STORAGE_ENABLED=true/' .env
+          sed -i 's/^# RCLONE_REMOTE=myremote/RCLONE_REMOTE=testremote/' .env
+          sed -i 's/^# RCLONE_REMOTE_PATH=/RCLONE_REMOTE_PATH=/' .env
+          sed -i 's/^# RCLONE_VFS_CACHE_MODE=full/RCLONE_VFS_CACHE_MODE=full/' .env
+          sed -i 's/^# RCLONE_VFS_CACHE_MAX_SIZE=50G/RCLONE_VFS_CACHE_MAX_SIZE=50G/' .env
+          sed -i 's/^# RCLONE_VFS_CACHE_MAX_AGE=72h/RCLONE_VFS_CACHE_MAX_AGE=72h/' .env
+          sed -i 's/^# RCLONE_VFS_READ_CHUNK_SIZE=128M/RCLONE_VFS_READ_CHUNK_SIZE=128M/' .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

@@ -21,6 +21,7 @@
   <img src="https://img.shields.io/badge/Tidarr-1DB954?style=flat-square&logoColor=white" />
   <img src="https://img.shields.io/badge/Recyclarr-FF6B35?style=flat-square&logoColor=white" />
   <img src="https://img.shields.io/badge/Kometa-FF4081?style=flat-square&logoColor=white" />
+  <img src="https://img.shields.io/badge/rclone-2596be?style=flat-square&logo=rclone&logoColor=white" />
   <img src="https://img.shields.io/badge/macOS-000000?style=flat-square&logo=apple&logoColor=white" />
   <br><br>
   <img src="https://img.shields.io/github/stars/liamvibecodes/mac-media-stack-advanced?style=flat-square&color=yellow" />
@@ -55,6 +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) |
 
 ## Choosing Your Media Server
 
@@ -94,6 +96,62 @@ After the stack is running:
 
 Jellystat will start tracking watch history, user activity, and library statistics automatically.
 
+## Optional: Cloud 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.
+
+Supports Google Drive, S3, Backblaze B2, Dropbox, and [40+ other providers](https://rclone.org/overview/).
+
+### Compatibility Requirements (macOS)
+
+- Set `MEDIA_SERVER=jellyfin` for cloud-backed playback.
+- Set `TDARR_MODE=docker` if you use Tdarr with cloud storage.
+- Native macOS apps (like Plex app and native Tdarr) cannot read Docker FUSE merged mounts directly.
+
+### Quick Start
+
+```bash
+bash scripts/setup-cloud-storage.sh
+docker compose -f docker-compose.yml -f docker-compose.cloud-storage.yml --profile cloud-storage --profile jellyfin --profile tdarr-docker up -d
+```
+
+If you also use optional profiles, append them to the same command (example: `--profile jellyfin`, `--profile music`, `--profile tdarr-docker`).
+
+Or include it in bootstrap:
+
+```bash
+bash bootstrap.sh --cloud-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
+```
+
+### Library paths when cloud storage is enabled
+
+- **Jellyfin (Docker):** keep `/data/movies` and `/data/tvshows` (override maps those to merged paths).
+- **Tdarr Docker mode:** keep `/movies` and `/tv` (override maps those to merged paths).
+
+### Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CLOUD_STORAGE_ENABLED` | `false` | Set to `true` to enable |
+| `RCLONE_REMOTE` | (required) | Remote name from rclone.conf |
+| `RCLONE_REMOTE_PATH` | (empty) | Subfolder on remote |
+| `RCLONE_VFS_CACHE_MODE` | `full` | VFS cache mode (full recommended) |
+| `RCLONE_VFS_CACHE_MAX_SIZE` | `50G` | Max local cache size |
+| `RCLONE_VFS_CACHE_MAX_AGE` | `72h` | Max cache age |
+| `RCLONE_VFS_READ_CHUNK_SIZE` | `128M` | Read chunk size |
+| `CLOUD_UPLOAD_MIN_AGE_HOURS` | `24` | Only upload files older than this |
+
+**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)
 
 | Service | What It Does |
@@ -108,6 +166,12 @@ bash scripts/setup-music.sh
 docker compose --profile music up -d
 ```
 
+If cloud storage is enabled, use:
+
+```bash
+docker compose -f docker-compose.yml -f docker-compose.cloud-storage.yml --profile cloud-storage --profile music up -d
+```
+
 Then open Tidarr at `http://localhost:8484` to authenticate with your Tidal account, and Lidarr at `http://localhost:8686` to configure your music library. See the [Music Setup](#music-setup) section below for details.
 
 ## Automation
@@ -121,6 +185,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 |
 | 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:
@@ -290,6 +355,8 @@ bash scripts/vpn-mode.sh nord
 | `scripts/vpn-mode.sh` | Manual VPN provider switcher |
 | `scripts/vpn-failover-watch.sh` | Automatic VPN failover daemon |
 | `scripts/run-kometa.sh` | Trigger Kometa metadata run |
+| `scripts/setup-cloud-storage.sh` | Sets up rclone + mergerfs cloud storage integration |
+| `scripts/cloud-upload.sh` | Periodic upload of local media to cloud storage |
 | `scripts/setup-music.sh` | Creates music directories and Tidarr config (optional) |
 | `scripts/log-prune.sh` | Prunes old log files (30-day default retention) |
 | `scripts/franchise-sort.py` | Auto-sorts franchise collections in Plex by release date (Plex only) |
@@ -340,6 +407,12 @@ docker compose --profile music up -d
 #        Host: gluetun, Port: 8080
 ```
 
+If cloud storage is enabled, use this start command in step 2 instead:
+
+```bash
+docker compose -f docker-compose.yml -f docker-compose.cloud-storage.yml --profile cloud-storage --profile music up -d
+```
+
 ### Tidarr Download Config
 
 The setup script creates a default `tiddl` config at `<MEDIA_DIR>/config/tidarr/.tiddl/config.toml` (default `<MEDIA_DIR>` is `~/Media`). Key settings:
@@ -388,6 +461,12 @@ docker compose --profile music stop lidarr tidarr
 export COMPOSE_PROFILES=music
 ```
 
+If cloud storage is enabled, include both compose files and profiles when starting music services:
+
+```bash
+docker compose -f docker-compose.yml -f docker-compose.cloud-storage.yml --profile cloud-storage --profile music up -d
+```
+
 ## Media Archiving
 
 If you're running out of space on your primary drive, the archive script moves old or watched media to an external drive. Dry-run by default so you can preview what would be moved before committing.

SETUP.md

@@ -268,6 +268,7 @@ Replace `YOUR_PLEX_TOKEN` and `YOUR_TMDB_API_KEY`, then save.
      - Movies source: `/movies`
      - TV source: `/tv`
      - Temp/cache: `/temp`
+   - If `CLOUD_STORAGE_ENABLED=true`, use `TDARR_MODE=docker` so Tdarr can read merged cloud paths.
 3. Assign the preloaded flow: `Quality-First HEVC (Resolution Preserving)`
 4. Keep the defaults in that flow for quality-first behavior:
    - No resolution downscale
@@ -334,6 +335,65 @@ Everything else is fully automated.
 
 ---
 
+## Optional: Cloud 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.
+
+### Compatibility (macOS)
+
+- Cloud-backed playback requires `MEDIA_SERVER=jellyfin`.
+- If using Tdarr with cloud storage, use `TDARR_MODE=docker`.
+- Native macOS apps (Plex app, native Tdarr) cannot directly read Docker FUSE merged mounts.
+
+### Setup
+
+```bash
+bash scripts/setup-cloud-storage.sh
+```
+
+The setup wizard will:
+1. Create the required directories
+2. Help you configure an rclone remote (interactive Docker wizard, copy existing conf, or skip)
+3. Write `CLOUD_STORAGE_ENABLED=true` and `RCLONE_REMOTE` to your `.env`
+4. Create `Movies` and `TV Shows` folders on your remote
+
+### Start with cloud 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 pass `--cloud-storage` to `bootstrap.sh` for a full install.
+
+### 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.
+
+### Library paths when cloud storage is enabled
+
+- **Jellyfin (Docker):** keep default container paths `/data/movies` and `/data/tvshows` (mapped to merged paths by compose override).
+- **Tdarr Docker mode:** keep `/movies` and `/tv` (mapped to merged paths by compose override).
+
+### Troubleshooting cloud storage
+
+```bash
+# Check rclone and mergerfs health
+bash scripts/health-check.sh
+
+# View cloud upload logs
+tail -50 ~/Media/logs/cloud-upload.log
+
+# Test rclone connectivity
+docker exec rclone-mount rclone ls myremote: --max-depth 1
+
+# Restart cloud storage (order matters: rclone first, then mergerfs)
+docker restart rclone-mount && sleep 15 && docker restart mergerfs
+```
+
+---
+
 ## Troubleshooting
 
 **Check overall health:**