LogoRiven Wiki

Getting Started

All in one media management solution

Riven
GitHub Repo starsIssuesLicenseContributorsDiscord

This documentation covers the new Beta version. If you still need the legacy (v0) documentation, see the v0.23.6 README.

Riven is a powerful media management and streaming solution designed to integrate with various media servers and third-party services. It automates the process of finding, downloading, and organizing media content, making it instantly available for streaming through your preferred media server.


Getting Started

Homepage

Riven is under active development, we are constantly working on new features and fixing bugs.

You may see different terms used in Discord and other documentation:

  • Legacy version: Also referred to as v0, legacy, or old
  • Beta version: Also referred to as v1, new, or dev

Riven streamlines your media consumption experience by:

  1. Automatically discovering new content based on your preferences and watchlists.
  2. Efficiently searching for and downloading high-quality media files via debrid services.
  3. Organizing your media library using RivenVFS, a high-performance virtual filesystem.
  4. Streaming content on-demand with intelligent caching and prefetching.
  5. Seamlessly integrating with your chosen media server for immediate streaming access.
  6. Providing a user-friendly web interface for easy management and configuration.

Whether you're a casual viewer or a media enthusiast, Riven offers a powerful, automated solution to keep your media library up-to-date and easily accessible.


Prerequisites

Operating System

Riven only supports Linux-based operating systems. For Windows, Windows Subsystem for Linux (WSL) is required.

If you are using WSL, it's recommended to install docker on WSL and not on Windows to avoid issues.

Required Software

Supported Services

Media Servers

Debrid Services

Content Services

Scrapers


Installation

Step 1: Set Up Directories

Before installing Riven, you must configure your filesystem and mount paths. This includes setting up mount propagation on the host for the VFS to work correctly.

See the Filesystem (VFS) page for detailed instructions on:

  • Configuring mount propagation on the host
  • Setting up volume mounts in docker-compose.yml
  • Understanding the library path and mount path configuration

Step 2: Docker Compose Configuration

Did you set up the VFS mount path?

Make sure you've completed the Setup Directories step first!

Mount propagation must be configured on the host before running Docker Compose.

Riven Services

The docker-compose.yml file is used to run Riven in a containerized environment. It consists of three services:

  1. riven: The main application (backend).
  2. riven-frontend: The web interface (frontend).
  3. riven-db: The database.

Docker Hub Tags

Both spoked/riven (backend) and spoked/riven-frontend (frontend) repositories use the same tagging conventions:

TagVersionDescription
latestv0 (Legacy)The legacy version of Riven
devv1 (Beta)Latest development builds - recommended for beta users
mainv1 (Beta)Same as dev - latest development builds
Other tagsVariousBranch names or temporarily assigned tags

Which tag should I use?

If you're a new user or want the latest features and bug fixes, use the :dev or :main tag. The :latest tag points to the legacy v0 version.

docker-compose.yml
volumes:
    riven-frontend-data:
    riven-pg-data:

services:
    riven-frontend:
        image: spoked/riven-frontend:dev
        container_name: riven-frontend
        restart: unless-stopped
        # If you want to expose the frontend to the host, uncomment the following line and remove the expose line
        # ports:
        #     - "3000:3000"
        expose:
            - 3000
        environment:
            - TZ=Asia/Kolkata
            - DATABASE_URL=/riven/data/riven.db
            - BACKEND_URL=http://riven:8080
            - BACKEND_API_KEY=backend_api_key
            - AUTH_SECRET="auth_secret" # Generate a random secret key (e.g., using `openssl rand -base64 32`)
            - ORIGIN=http://localhost:3000 # Change this to the URL you will use to access frontend
        depends_on:
            riven:
                condition: service_healthy
        volumes:
            - riven-frontend-data:/riven/data # This is frontend data storage

    riven:
        image: spoked/riven:dev
        container_name: riven
        restart: unless-stopped
        shm_size: 1024m # this is used for the VFS caching
        # If you want to expose the backend to the host, uncomment the following line and remove the expose line
        # ports:
        #     - "8080:8080"
        expose:
            - 8080
        tty: true
        cap_add:
            - SYS_ADMIN
        security_opt:
            - apparmor:unconfined
        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:5432/riven
            - RIVEN_FILESYSTEM_MOUNT_PATH=/mount
            - RIVEN_UPDATERS_LIBRARY_PATH=/path/to/library/mount # like /mnt/riven
        healthcheck:
            test: curl -s http://localhost:8080 >/dev/null || exit 1
            interval: 30s
            timeout: 10s
            retries: 10
        volumes:
            - ./data:/riven/data # This is backend data storage
            - /path/to/library/mount:/mount:rshared,z # like /mnt/riven:/mount:rshared,z
        depends_on:
            riven-db:
                condition: service_healthy

    riven-db:
        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:
            - riven-pg-data:/var/lib/postgresql/data/pgdata
        healthcheck:
            test: ["CMD-SHELL", "pg_isready -U postgres"]
            interval: 10s
            timeout: 5s
            retries: 5

Now this won't work as is, you need to modify the docker-compose.yml file to match your setup.

  1. Change TZ to your timezone in both riven & riven-frontend.

  2. riven-frontend service:

    • Change ORIGIN to the URL you will be accessing the web interface from. For example, if you are planning to run Riven on https://riven.example.com, change it to https://riven.example.com.
    • Change BACKEND_URL to the URL where the frontend can access the backend.
    • Change BACKEND_API_KEY to the Riven backend API key. This can be found in the backend settings.json file which is generated on first run, or you can set it using RIVEN_API_KEY environment variable in riven service.
    • Generate a random secret key (e.g., using openssl rand -base64 32) and set it to AUTH_SECRET environment variable in riven-frontend service.
  3. riven service:

    • Set PUID & PGID to your user ID & group ID. This is usually 1000 for both, but you can find it using id -u & id -g commands.
    • RIVEN_FILESYSTEM_MOUNT_PATH is the path where the virtual filesystem will be mounted. RIVEN_UPDATERS_LIBRARY_PATH is the path where the media servers will and see your library. Make sure you have setup the host mount path with proper propagation as described in the Filesystem (VFS) documentation. These both environment variables are same path if you are running then locally (not using docker).

Running Riven

Depending on how you installed Riven, execute the following command:

docker-compose up -d && docker-compose logs -f

Python Version

Riven requires Python 3.12 or higher and uv to be installed.

make install
make run

You can access the Riven web interface by navigating to the specified ORIGIN URL you entered in the docker-compose.yml file or your reverse proxy URL.

  • Example: http://localhost:3000

Configuration

Once Riven is running, you can configure it editing the settings.json file in the data directory attached to the riven container or through the web interface.

At this point you can take a look at the services page to learn more about the various services and how to configure them.


On this page