Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/rivenmedia/riven/llms.txt

Use this file to discover all available pages before exploring further.

Riven uses RivenVFS — a FUSE-based virtual filesystem — to expose your debrid media as a regular directory tree. Plex reads from this mount just like any other media folder, while Riven’s updater service keeps Plex’s library in sync whenever items are added or completed. Getting this working reliably requires exact library names, correct Docker volume propagation flags, and a shared bind mount on the host.

​
Prerequisites

  • Riven and its PostgreSQL database are running (see the installation guide).
  • You have chosen a host path for the RivenVFS mount (referred to below as /path/to/riven/mount).
  • Plex Media Server is running in Docker (or directly on the host).

​
Required Plex Library Sections

Riven’s updater locates your Plex libraries by their exact section names. You must create all four sections before enabling the updater:
Media typeRequired section name
Moviesmovies
Moviesanime_movies
Showsshows
Showsanime_shows
These names are currently mandatory and case-sensitive. Support for custom library names is planned for a future release.

​
Docker Volume Setup

​
1. Prepare the host bind mount

The host directory must be a shared bind mount so that FUSE mounts created inside the Riven container propagate out to other containers. Run the following commands once per boot (or automate them — see below): 
sudo mkdir -p /path/to/riven/mount
sudo mount --bind /path/to/riven/mount /path/to/riven/mount
sudo mount --make-rshared /path/to/riven/mount
Verify propagation: 
findmnt -T /path/to/riven/mount -o TARGET,PROPAGATION
# Expected output: PROPAGATION = shared or rshared

​
Make it permanent

Create /etc/systemd/system/riven-bind-shared.service:
[Unit]
Description=Make Riven data bind mount shared
After=local-fs.target
Before=docker.service

[Service]
Type=oneshot
ExecStart=/usr/bin/mount --bind /path/to/riven/mount /path/to/riven/mount
ExecStart=/usr/bin/mount --make-rshared /path/to/riven/mount
RemainAfterExit=yes

[Install]
WantedBy=multi-user.target
Then enable it:
sudo systemctl enable --now riven-bind-shared.service

​
2. Configure Docker volumes

In your docker-compose.yml, the Riven container uses rshared,z (it creates the FUSE mount and must propagate it outward), while consumer containers like Plex use rslave,z (they receive mount events but do not propagate them further): 
services:
  riven:
    image: spoked/riven:latest
    cap_add:
      - SYS_ADMIN
    security_opt:
      - apparmor:unconfined
    devices:
      - /dev/fuse
    volumes:
      - /path/to/riven/data:/riven/data
      - /path/to/riven/mount:/mount:rshared,z   # rshared — Riven creates the FUSE mount

  plex:
    image: plexinc/pms-docker
    volumes:
      - /path/to/plex/config:/config
      - /path/to/riven/mount:/mount:rslave,z    # rslave — Plex receives the mount
Do not use rshared on the Plex volume. rslave is correct for consumer containers: they receive mount propagation events without re-broadcasting them.

​
Create the Plex Libraries

1

Open Plex Web and navigate to Libraries

Go to Settings → Libraries in Plex Web (or click the + icon next to Libraries in the left sidebar).
2

Add the Movies library

  1. Click Add Library and select Movies.
  2. Set the library name to exactly movies (all lowercase).
  3. Click Add folder and enter the path /mount/movies.
  4. Click Add Library.
3

Add the Anime Movies library

Repeat the process: type Movies, name it anime_movies, and point it to /mount/anime_movies.
4

Add the Shows library

Click Add Library, select TV Shows, name it shows, and point it to /mount/shows.
5

Add the Anime Shows library

Repeat for TV Shows: name it anime_shows, path /mount/anime_shows.
6

Enable automatic library scans

In each library’s settings, enable Automatically detect new content so Plex picks up new files without waiting for a full scan.

​
Configure the Plex Updater in Riven

Riven needs your Plex server URL and authentication token to trigger library scans after items are added.

​
Updater settings

SettingDescriptionDefault
updaters.plex.enabledEnable the Plex updaterfalse
updaters.plex.urlURL to your Plex serverhttp://localhost:32400
updaters.plex.tokenYour Plex authentication token (X-Plex-Token)""
updaters.updater_intervalSeconds between library update cycles120
Apply these settings via the API: 
curl -X POST http://localhost:8080/api/v1/settings/set/updaters.plex.enabled,updaters.plex.url,updaters.plex.token \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "updaters.plex.enabled": true,
    "updaters.plex.url": "http://plex:32400",
    "updaters.plex.token": "YOUR_PLEX_TOKEN"
  }'
Or set all settings at once using POST /api/v1/settings/set/all with the full settings object.

​
Get your Plex token

1

Sign in to Plex Web

Go to app.plex.tv and sign in with your Plex account.
2

Open any media item's XML

Navigate to a movie or show in your library, click the ⋮ menu, choose Get Info, then click View XML. The URL that opens will contain X-Plex-Token=XXXXXXXXXXXXXXXX.
3

Copy the token

Copy the value after X-Plex-Token= — this is the token to paste into updaters.plex.token.
The official Plex support article Finding an authentication token covers additional methods including the Plex desktop app and account settings page.

​
Troubleshooting: Plex Shows Empty /mount After Restart

If Plex’s library folders appear empty after restarting Riven or RivenVFS, the problem is almost always mount propagation. Work through these steps without restarting Plex.
1

Verify the host path is shared

Check that your host mount directory has shared or rshared propagation:
findmnt -T /path/to/riven/mount -o TARGET,PROPAGATION
# PROPAGATION must be: shared or rshared
If it shows private, re-run the bind mount commands from the Docker volume setup section above.
2

Verify propagation inside the Plex container

Check that the Plex container is receiving mount events and that the FUSE mount is visible:
docker exec -it plex sh -c \
  'findmnt -T /mount -o TARGET,PROPAGATION,OPTIONS,FSTYPE'
PROPAGATION should be rslave or rshared, and FSTYPE should show fuse when RivenVFS is active. If FSTYPE shows ext4 or similar, the FUSE mount has not propagated — confirm the Plex volume uses :rslave,z.
3

Re-trigger the VFS mount

Restart the Riven container to remount RivenVFS. With correct propagation on both sides (host rshared, Plex container rslave), Plex should see the content return automatically without needing a Plex restart.
docker restart riven
4

Clear a stale FUSE mount (after crashes)

If Riven crashed previously without cleanly unmounting, a stale FUSE entry can block remounts:
sudo fusermount -uz /path/to/riven/mount \
  || sudo umount -l /path/to/riven/mount
# Then restart Riven
docker restart riven
In Riven settings, filesystem.mount_path must be set to the container path (typically /mount), not the host path. Both Riven and Plex refer to the same in-container path for their libraries (e.g., /mount/movies).

Build docs developers (and LLMs) love

Get started for freeTalk to us