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.

This guide walks you through the fastest path to a working Riven installation: a Docker Compose stack running the Riven backend, a PostgreSQL database, and Jellyfin (or Plex) — all talking through a shared FUSE mount. By the end you will have a live web UI at http://localhost:8080 and your first content request in the pipeline.

​
Prerequisites

Before you begin, make sure you have the following:
  • Docker and Docker Compose (v2) installed on a Linux host.
  • An active debrid account — Real-Debrid or AllDebrid. Riven requires a debrid service to cache and stream torrent content.
  • A media server — Plex, Jellyfin, or Emby — either already running or set up alongside Riven in the same Compose stack.
  • The FUSE kernel module loaded on the host (sudo modprobe fuse).
Riven’s RivenVFS uses FUSE to expose a virtual mount point. The host must have /dev/fuse available and the SYS_ADMIN capability must be granted to the Riven container.

​
Steps

1
Choose and prepare a mount directory
2
Pick a path on your host that Riven will use as its FUSE mount point. This guide uses /opt/riven/mount. Create it and make it a shared bind mount — this is required so that mount propagation works correctly between the Riven container and your media server container.
3
sudo mkdir -p /opt/riven/data
sudo mkdir -p /opt/riven/mount
sudo mkdir -p /opt/riven/db

# Turn the mount directory into a bind mount and mark it shared (run once per boot)
sudo mount --bind /opt/riven/mount /opt/riven/mount
sudo mount --make-rshared /opt/riven/mount

# Verify the propagation flag is set
findmnt -T /opt/riven/mount -o TARGET,PROPAGATION
# Expected output: PROPAGATION = shared or rshared
4
The mount --bind and mount --make-rshared commands must be re-run after every host reboot unless you automate them. See the Installation guide for systemd unit and fstab options.
5
Create your docker-compose.yml
6
Create a docker-compose.yml file and paste in the contents below. Replace every /path/to/riven/* path with the directories you created in the previous step (e.g. /opt/riven/data, /opt/riven/mount, /opt/riven/db).
7
services:
    riven:
        image: spoked/riven:latest
        container_name: riven
        restart: unless-stopped
        ports:
            - "8080:8080"
        tty: true
        cap_add:
            - SYS_ADMIN
        security_opt:
            - apparmor:unconfined
        shm_size: 1024m
        devices:
            - /dev/fuse
        environment:
            - PUID=1000
            - PGID=1000
            - TZ=America/New_York
            - RIVEN_FORCE_ENV=true
            - RIVEN_DATABASE_HOST=postgresql+psycopg2://postgres:postgres@riven-db/riven
        healthcheck:
            test: curl -s http://localhost:8080 >/dev/null || exit 1
            interval: 30s
            timeout: 10s
            retries: 10
        volumes:
            - /path/to/riven/data:/riven/data
            - /path/to/riven/mount:/mount:rshared,z
        depends_on:
            riven_postgres:
                condition: service_healthy

    riven_postgres:
        image: postgres:17-alpine
        container_name: riven-db
        environment:
            - PGDATA=/var/lib/postgresql/data/pgdata
            - POSTGRES_USER=postgres
            - POSTGRES_PASSWORD=postgres
            - POSTGRES_DB=riven
        volumes:
            - /path/to/riven/db:/var/lib/postgresql/data/pgdata
        healthcheck:
            test: ["CMD-SHELL", "pg_isready -U postgres"]
            interval: 10s
            timeout: 5s
            retries: 5

    jellyfin:
        image: jellyfin/jellyfin
        container_name: jellyfin
        user: 1000:1000
        restart: unless-stopped
        ports:
            - "8096:8096"
        volumes:
            - /path/to/jellyfin/config:/config
            - /path/to/riven/mount:/mount:rslave,z
8
Notice that the Jellyfin container mounts the same host path (/path/to/riven/mount) with :rslave,z propagation. This ensures Jellyfin automatically sees any FUSE mounts that RivenVFS creates inside the Riven container without requiring a Jellyfin restart.
9
If you use Plex instead of Jellyfin, add your Plex container to the same Compose file and mount the path with :rslave,z as shown. Make sure your Plex libraries point to /mount/movies, /mount/shows, etc. (the container-internal path, not the host path).
10
Start the stack
11
docker compose up -d
12
Docker will pull the images, initialise the PostgreSQL database, and start the Riven backend. Riven waits for PostgreSQL to be healthy before starting, so the first boot may take 30–60 seconds.
13
Confirm the stack is running:
14
docker compose ps
docker compose logs riven --tail 50
15
Riven serves its API on port 8080 (configured via the --port CLI argument, default 8080). You can verify the backend is ready by hitting the health endpoint:
16
curl http://localhost:8080/api/v1/health
# Returns: {"message": "True"} when Riven has fully initialised
17
Open the web UI and add your debrid API key
18
Open http://localhost:8080 in your browser. The Riven web UI loads automatically.
19
Navigate to Settings → Downloaders and enable your debrid provider, then paste in your API key:
20
Real-Debrid
  1. Go to real-debrid.com/apitoken and copy your API token.
  2. In the Riven UI, open Settings → Downloaders → Real-Debrid.
  3. Toggle Enabled on and paste the token into the API Key field.
  4. Save settings.
AllDebrid
  1. Log in to AllDebrid and generate an API key from your account settings.
  2. In the Riven UI, open Settings → Downloaders → AllDebrid.
  3. Toggle Enabled on and paste the key into the API Key field.
  4. Save settings.
21
Enable a content source and watch items process
22
With a debrid provider connected, enable at least one content source so Riven knows what to download.
23
Overseerr
  1. In the Riven UI, open Settings → Content → Overseerr.
  2. Toggle Enabled on.
  3. Enter your Overseerr URL (e.g. http://localhost:5055) and API key.
  4. Save settings.
  5. Open Overseerr and submit a movie or TV show request. Riven will pick it up on the next poll cycle and begin scraping, ranking, and downloading.
Plex Watchlist
  1. In the Riven UI, open Settings → Content → Plex Watchlist.
  2. Toggle Enabled on.
  3. Provide your Plex token.
  4. Save settings.
  5. Add an item to your Plex Watchlist; Riven will detect it automatically.
Trakt
  1. In the Riven UI, open Settings → Content → Trakt.
  2. Toggle Enabled on and follow the OAuth flow to connect your Trakt account.
  3. Save settings. Items from your Trakt watchlist will begin syncing.
24
You can watch items move through the pipeline in the Riven UI dashboard. Each item progresses through scraping → debrid caching → VFS mounting → library update. Once an item reaches the Completed state, it will appear in your Jellyfin or Plex library under /mount.

​
Next steps

Installation reference

Full environment variable reference, persistent mount setup, and production hardening tips.

Configuration overview

Configure scrapers, torrent ranking, library profiles, and VFS naming templates.

Build docs developers (and LLMs) love

Get started for freeTalk to us