PlexCache-D - Beta testing of v3.0 (archived)

[StudioNirin]

PlexCache-D Docker Setup for Unraid (Beta Testing)

Before You Start

IMPORTANT: If you're currently running the CLI version of PlexCache via User Scripts or cron, disable those scheduled runs first to avoid conflicts. Running both the Docker scheduler and CLI scripts simultaneously can cause race conditions and duplicate file operations.

---

Quick Install with Template

The easiest way to install is using the pre-configured Docker template:

1. Download plexcache-d.xml
2. Place it in /boot/config/plugins/dockerMan/templates-user/ on your Unraid server
3. Go to Docker → Add Container → Select "plexcache-d" from the template dropdown
4. Adjust paths for your setup and click Apply

Or continue below for manual configuration.

---

Docker Container Settings

Basic Settings

Setting	Value
Name	plexcache-d
Repository	ghcr.io/studionirin/plexcache-d:latest
Network Type	Bridge
Privileged	Off
WebUI	http://[IP]:[PORT:5757]

Required Mappings

Name	Host Value	Container Value	Type	Description
Config	/mnt/user/appdata/plexcache-d	/config	Path	Config & data persistence
Cache	/mnt/cache_downloads/	/mnt/cache	Path	Your cache drive
Array	/mnt/user0	/mnt/user0	Path	Array direct access
User	/mnt/user	/mnt/user	Path	User share access
PUID	99	PUID	Variable	User ID (99=nobody on Unraid)
PGID	100	PGID	Variable	Group ID (100=users on Unraid)
TZ	Europe/London	TZ	Variable	Your timezone
Port	5757	5757	Port	Web UI

Optional Mappings (Native Unraid Notifications)

Name	Host Value	Container Value	Type	Description
Unraid Notify Script	/usr/local/emhttp	/usr/local/emhttp	Path (ro)	Unraid's notify script
Notifications	/tmp/notifications	/tmp/notifications	Path	Unraid's notification queue

Note: Without these optional mounts, notifications fall back to webhook-only mode.

Path Notes

Adjust the host paths to match your setup:

• Config: Create this folder for persistent config storage (e.g., /mnt/user/appdata/plexcache-d)
• Cache: Your cache-enabled share where media files are cached (e.g., /mnt/cache_downloads/ or /mnt/cache/)
• Array: Direct array access (bypasses cache), needed for .plexcached backup files
• User: User share access for Plex path resolution

---

First Run

1. Start the container
2. Access the Web UI at http://your-server-ip:5757
3. The Setup Wizard will automatically launch to configure:
   • Plex connection (URL + token via OAuth "Get Token" button)
   • Library selection and path mappings
   • User selection for OnDeck/Watchlist monitoring
   • Cache behavior settings

---

Path Mappings Configuration

During setup, you'll configure path mappings. These tell PlexCache how to translate Plex's media paths to the container's paths.

Example Configuration:

Plex Path	Cache Path	Array Path	Host Cache Path
/data/media/movies	/mnt/cache/media/movies	/mnt/user0/media/movies	/mnt/cache_downloads/media/movies
/data/media/tv	/mnt/cache/media/tv	/mnt/user0/media/tv	/mnt/cache_downloads/media/tv

• Plex Path: The path Plex reports for your media (check Plex library settings)
• Cache Path: Where the file lives on your cache drive (inside the container)
• Array Path: Where the .plexcached backup lives on the array (inside the container)
• Host Cache Path: The actual host path for the mover exclude file (see below)

Docker Path Translation (Important!)

If your cache mount differs between host and container (e.g., host /mnt/cache_downloads → container /mnt/cache), you must configure Host Cache Path in Settings → Paths for each mapping.

This ensures the mover exclude file contains paths that the Unraid mover recognizes. Without this, the mover may incorrectly move your cached files back to the array.

---

Unraid Mover Integration (CA Mover Tuning)

If using the CA Mover Tuning plugin to prevent the mover from touching cached files:

1. Go to Settings → Scheduler → CA Mover Tuning

2. Set the File Exclusion Path to:

   [Your Config Path]/unraid_mover_exclusions.txt
   

   Example: /mnt/user/appdata/plexcache-d/unraid_mover_exclusions.txt

PlexCache automatically maintains this file with all currently cached media paths.

---

After Setup

Dashboard

• Shows cache status, OnDeck/Watchlist counts, and system health
• "Run Now" button for manual cache operations (with dry-run option)
• Recent activity feed showing cached/restored files

Settings → Schedule

• Configure automatic runs (replaces your old cron/User Script)
• Interval-based or cron expression scheduling
• Dry-run and verbose options

Settings → Cache

• Cache Limit: Maximum drive usage for caching (e.g., 500GB or 75%)
• Eviction Mode: Smart (priority-based), FIFO (oldest first), or None
• Eviction Threshold: When to start evicting (% of cache limit)
• Minimum Priority: Only evict files below this score (OnDeck ~90, Watchlist ~70)

Settings → Notifications

• Configure webhook URL (Discord, Slack, or generic)
• Select notification types: Summary, Activity, Errors, Warnings
• Enable native Unraid notifications (requires optional mounts above)

Maintenance

• View cache health status
• Fix unprotected files or orphaned backups
• Clean up stale tracking entries

---

Migrating from CLI Version

If you're migrating from the CLI version:

1. Copy your CLI files to /mnt/user/appdata/plexcache-d/import/:

   • plexcache_settings.json
   • unraid_mover_exclusions.txt (or plexcache_mover_files_to_exclude.txt)
   • data/ folder (timestamps, trackers, etc.)

2. Start the container and access the Setup Wizard

3. The wizard will detect your import files and offer to migrate them automatically

4. After import, verify your Plex connection (URL may differ in Docker)

---

Migrating from Alpha Version

If you're migrating from the Brandon 'Alpha' test version:

1. Open up (edit) your docker container composer

2. Change the repo to - ghcr.io/studionirin/plexcache-d:latest

3. I changed the container name to plexcache-d and also the appdata folder to plexcache-d but you don't need to do either of these things really. If you do change the folder name make sure to also change the reference in the container compose file.

4. Hit apply and everything should just work.

[StudioNirin]

@Brandon-Haney
Figured should make a new discussion page for the new merged version, as it'll probably have it's own weird issues until I get it fully up and running.
First issue atm is that I don't seem to be able to actually pull the image on my local server, though I do -seem- to have it live so I'm not sure if I've typod something somewhere.

Edit - Nevermind, figured it out. needed to use the full path of "ghcr.io/studionirin/plexcache-d:latest" the short path didn't want to work for me. Guessing maybe you also had the container on dockerhub and not just ghcr?

[StudioNirin]

@Brandon-Haney

Ok so I've just this second had a report from a user that a series they were watching is missing episodes (The Shield). They were on S06E09 next, and when they went to watch it tonight they were missing. I just looked on my Sonarr (I had to manually scan in order for it to update what files existed) -

As you can see the upcoming like 10 episodes were gone, but the last eps of S07 were there still (which were probably not cached yet) so I'm assuming this was an issue with Plexcaching.

I went through my log file and it seems to be processing the right episodes, but I can't see why it might have been removing them:

plexcache_log_20260213_222045.log

It does seem to be removing a lot of 'redundant array files' which... is worrying if it's done it to a bunch of things. Running a check now.

[StudioNirin]

I'm pushing a hotfix PR now.

I've merged and updated, I'm just replacing some of the missing files (that didn't have .plexcached versions) and then i'll run a test.

Though a lot of the files that didn't have .plexcached versions were old stuff, that definitely would have been stored on the array. So I'm not sure why they didn't have archived copies. Something to keep an eye out for. Could be that I'm just wrong.

[StudioNirin]

Restore files that have .plexcached backups: find /mnt/user0/media/ -name "*.plexcached" -type f -exec sh -c 'mv "$1" "${1%.plexcached}" && echo "Restored: ${1%.plexcached}"' _ {} ;

Weirdly, while this did restore a bunch of files, it didn't restore all of them...

Edit: turns out it's because it was on the cache drive.... (?)

Which is super weird because there's nothing that should have allowed that to happen...

[StudioNirin]

@Brandon-Haney

find commands.txt

A log of some find commands I did. I have a -bunch- of .plexcached files living on hex-drive cache.

[StudioNirin]

To get back to a clean slate I have reverted all .plexcached files back to normal files, and I've also done a bunch of sonarr/radarr organisation so all my files now have totally consistent naming formats and structures (they were already mostly correct but I did some updates and cleaned up some stuff I'd been meaning to do for ages). So after tonight/tomorrow when all the processing is finished I'll turn plexcache back on and see what happens.

[Brandon-Haney]

-bunch- of .plexcached files living on hex-drive cache.

Yeah mapping error in my code, it was using /mnt/user/ which when set to cache-prefer meant it was moving the .plexcache file to your cache drive. I hopefully got that nipped up but hoping your testing will come back positive.

[crafty35a]

I have lots of plexcached files showing on my cache, and no live copies of the files:

https://github.com/StudioNirin/PlexCache-D/discussions/50#discussioncomment-15801741

[StudioNirin]

@Brandon-Haney

In other news, I've been muddling throught the Wiki pages and trying to organise them a bit and get instructions down for setup and use for both the docker and the script versions. Still loads to get done on it though. The github wiki pages are a bit odd to try and organise. I'll probably end up making a custom sidebar for it so I can have a menu for just the main sections etc.

At the moment the 'plexcache-r' section recommends using the backup v2.1.2 branch of plexcache-r as that is a known-working setup, but eventually I'll also change that into using the script-compatible files from plexcache-d. But I've not tested that setup at all yet so I don't know if there are any changes in the setup process for it. The docker version is my priority at the moment though as I think it's by far the better method.

Over this week I'll create a full page for a WebUI guide as well.

And then at some point this week, after we have confirmed no more major issues (like those wierd file deletions) I'll post up on reddit asking for additional beta testers. I've already has a couple people enquire about it but I've suggested they hold off for a couple days.

[StudioNirin]

@Brandon-Haney

Haven't really been looking at plexcache the last couple days, but took a look at it just now and noticed this:

This is before I've run the scan, in fact I haven't run it in a couple days (I have schedule turned off temporarily cos I'm doing some other stuff on the server). The thing that jumped out though is that I remember the last time I looked at the dashboard, I also had a bunch of 'backup cleanup' redundant files to remove. The thing that raised a red flag though was that I know for sure that Battlestar : Razor was the top file then as well. I'm pretty sure Inglorious Basterds and the Lord of the Rings were also there. For some reason the same bunch of files seems to be.... getting backed up and then being restored to the array?

[StudioNirin]

I just ran plexcache (without doing any of the cleanups) and then refreshed the maintenance page, and this happened -

So Razor left, along with like 200 others, but some stayed. Something definitely weird going on. I did wonder if maybe I had Mover set up incorrectly and the files were being moved back to the array, but I checked and it's pointing to the unraid_mover_exclusions.txt

Though I notice all the "Stale exclude entries" and "Stale Timestamp entries" were all fixed by the new run. I wonder if there was some big rename or something that happened in the last couple days.

[Brandon-Haney]

@StudioNirin The "redundant" state (both Movie.mkv AND Movie.mkv.plexcached on array, no cache copy) can only be created by an external process, PlexCache's own eviction never produces this.

Can you zip up your log folder and attach it for me to dig into?