Skip to content

Riven

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.

  • ⚙ Easy Installation

    Get Riven up and running quickly with our comprehensive installation guide. Whether you're using Docker or running natively, we've got you covered.

    ⚙ Installation Guide

  • 🔧 Powerful Configuration

    Customize Riven to fit your media management needs. Configure debrid services, media servers, and more with our user-friendly interface.

    🔧 Configuration Options

  • ☁ ElfHosted ❤️

    ElfHosted is a PaaS that takes care of all the technical details like hosting, security, and updates for your self-hosted apps.

    • 🎉 Sponsored: Your subscription goes directly to Riven developers!

    ☁ Check out ElfHosted

  • Active Community

    Join our vibrant community for support, updates, and contributions. Collaborate with other users and developers to make Riven even better.

    Join the Discord

Getting Started#

step-5

Beta

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

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.
  3. Organizing your media library using a smart symlink system.
  4. Seamlessly integrating with your chosen media server for immediate streaming access.
  5. 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.

ElfHosted#

ElfHosted is a geeky open-source PaaS which provides all the "plumbing" (hosting, security, updates, etc) for your self-hosted apps.

Curious how it works? Here's an explainer video! 🔥

ElfHosted ❤️ Riven 100%

Riven is an "Elf-icial" app in the ElfHosted app catalogue - A whopping 100% of your subscription goes directly to Riven developers, who can usually be found in the #elf-riven channel in the ElfHosted Discord Server.

ElfHosted "Infinite Streaming" bundles

Riven comes pre-packaged with Zurg and your choice of Plex, Jellyfin, or Emby, and is available in the following convenient bundles:

  • Starter Kit (quick and easy setup)
  • Hobbit Bundle (12.5% dedicated node, GPU transcoding, 250Mbps shared, extra bundled apps, 22% off non-bundled)
  • Ranger Bundle (25% dedicated node, GPU transcoding, 500Mbps shared, extra bundled apps, 44% off non-bundled)
  • Halfling Bundle (50% dedicated node, GPU transcoding, 1Gbps shared, extra bundled apps, 66% off non-bundled)
  • Nazgul Bundle (100% dedicated node, GPU transcoding, 1Gbps dedicated, extra bundled apps, 88% off non-bundled)

Setup#

Before we begin, we need to set up the required folders and files for Riven.

Grab the docker-compose.yml file from the installation guide and then docker-compose up -d to start the services.

Note

  • Linux: Riven only supports Linux-based operating systems.
  • Windows: Riven only supports Windows Subsystem for Linux (WSL) in Windows.
  • Rclone: Required to mount debrid service. Additionally, Zurg is preferred for Real-Debrid users. Learn more
  • Media Server: Plex, Jellyfin, and Emby are supported.
  • Docker: Required to run Riven in a containerized environment. Learn more

Debrid Support

Currently only Real-Debrid, All-Debrid and Torbox are supported. More services will be added in the future!

Setup Directories#

For detailed information on the various services and configurations available in Riven, please refer to the symlink page. This page will help you understand how to configure and manage your media library using symlinks. It will help you understand why we map the Riven volumes to /mnt and how you can modify this in the docker-compose.yml file for the best outcome.

Installation#

Setup Rclone & Symlink Paths First! 🔥

This is incredibly important and must be setup first! When configuring the rclone mount path and library path, you need to make sure that the paths are correct for your system. More information can be found at the symlink page.

If your debrid files are found in your rclone path, and you can successfully ls -lh /mnt/zurg your rclone path, you can skip this step.

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-compose.yml
services:
    riven-frontend:
        image: spoked/riven-frontend:latest
        container_name: riven-frontend
        restart: unless-stopped
        ports:
            - "3000:3000"
        tty: true
        environment:
            - PUID=1000
            - PGID=1000
            - TZ=America/New_York
            - ORIGIN=http://localhost:3000
            - BACKEND_URL=http://riven:8080
            - DIALECT=postgres
            - DATABASE_URL=postgres://postgres:postgres@riven-db/riven
        depends_on:
            riven:
                condition: service_healthy

    riven:
        image: spoked/riven:latest
        container_name: riven
        restart: unless-stopped
        ports:
            - "8080:8080"
        tty: true
        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:
            - ./data:/riven/data
            - /mnt:/mnt
        depends_on:
            riven_postgres:
                condition: service_healthy

    riven_postgres:
        image: postgres:16.3-alpine3.20
        container_name: riven-db
        environment:
            PGDATA: /var/lib/postgresql/data/pgdata
            POSTGRES_USER: postgres
            POSTGRES_PASSWORD: postgres
            POSTGRES_DB: riven
        volumes:
            - ./riven-db:/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.
  2. 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. This is not required if you are running riven behind a reverse proxy like nginx, caddy, cosmos etc.
  3. Change BACKEND_URL to the URL where the frontend can access the backend. This is not required here as we are running both frontend and backend in the same network (stack).
  4. Change RIVEN_DATABASE_HOST to the URL where the backend can access the database. This is not required here as we are running both backend and database in the same network (stack).
  5. Change DIALECT and DATABASE_URL to use the same database as the backend. This is not required here as we are running both backend and database in the same network (stack).
  6. Change volumes to match your setup. Riven requires access to the library folder and rclone mount path.

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.11 or higher and poetry to be installed.

poetry install --without dev
poetry run python /src/main.py

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 by accessing the web interface. You will be prompted with onboarding steps to set up your debrid service, media server, content services and scraper services.

There are 4 steps in the onboarding process.

Step 1: General Settings#

In this step you configure the downloaders (debrid services), rclone mount path, library path, subtitles, etc. See the image below for an example.

step-1

Step 2: Media Server#

In this step you configure the media server and updater settings. See the image below for an example.

step-2

Step 3: Content Services#

In this step you configure the content services like Trakt, Overseerr, etc. See the image below for an example.

step-3

Step 4: Scraper Services#

In this step you configure the scraper services like Torrentio, Zilean, Prowlarr, Jackett, etc. See the image below for an example.

step-4

Done!

Once you have completed the onboarding process, you will be greeted with a beautiful dashboard where you can manage your media library, request items, settings and many more in the future.

step-5

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

Frequently Asked Questions#

Cross-site POST form submissions are forbidden

The most common reason for this is that you may not have set up ORIGIN correctly in the docker-compose.yml file. If you are running Riven behind a reverse proxy, you can remove the ORIGIN environment variable from the riven-frontend service.

I am seeing an error when trying to save changes

If you are seeing an error when trying to save changes, it is most likely due to incorrect configuration or backend failure. Please check the logs of the Riven service to see the error message. If you are unable to resolve the issue, feel free to ask for help in the Riven Discord server.

I am stuck in an onboarding loop

If you are stuck in the onboarding loop, it is most likely due to incorrect symlink settings. Check your library path and rclone mount path. If they are correct, check the logs of the Riven service. If you are unable to resolve the issue, feel free to ask for help in the Riven Discord server.