Getting Started#

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!

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.

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#

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.

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

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 2: Media Server#

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

Step 3: Content Services#

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

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.

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.

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#