Riven is a powerful media management solution that works together with debrid services to help you find, organize, stream, and enjoy your media effortlessly.

How do I get started with Riven?

To get started with Riven, visit our documentation at https://riven.tv/docs to learn about installation and setup.

Where can I find support for Riven?

For support, please refer to our documentation, send us a message in our discord server at https://discord.riven.tv, or reach out via contact@riven.tv

Getting Started with Riven

Welcome to Riven! This guide will help you get up and running quickly with your all-in-one media management solution.

Quick Configuration

Want to skip manual editing? Use our Docker Compose Generator to create a customized configuration with your preferred media server in seconds!

Prerequisites

Before you begin, ensure you have:

Required Services

Debrid Service: Real-Debrid or TorBox account (required for downloading)
Media Server: Plex, Jellyfin, or Emby installed and configured
Docker: Docker and Docker Compose installed on your system

System Requirements

Operating System Support

Linux: Fully supported (Ubuntu, Debian, Fedora, Arch, etc.)
Windows: Only via WSL2 (Windows Subsystem for Linux)
macOS: Not officially supported due to FUSE limitations

Hardware:

CPU: 2+ cores recommended
RAM: 4GB minimum, 8GB+ recommended
Disk: Fast SSD preferred for database and cache
Network: Stable internet connection

Quick Installation

Step 1: Prepare Your System

Create a directory for Riven and the required mount point:

# Create and configure the mount point
RIVEN_MOUNT_PATH=/mnt/riven
sudo mkdir -p $RIVEN_MOUNT_PATH
sudo mount --bind $RIVEN_MOUNT_PATH $RIVEN_MOUNT_PATH
sudo mount --make-rshared $RIVEN_MOUNT_PATH

# Verify mount propagation (should show "shared" or "rshared")
findmnt -T $RIVEN_MOUNT_PATH -o TARGET,PROPAGATION

Important: Mount Propagation

Proper mount propagation is critical for Riven to work correctly! The mount path must be set to rshared to allow the VFS mount inside the container to be visible to your media server.

For detailed information, see the Filesystem (VFS) documentation.

Step 2: Create docker-compose.yml

Create a docker-compose.yml file with the following content:

Prefer a Custom Configuration?

Use our Docker Compose Generator to customize values like timezone, ports, and media server selection. You can download or copy the generated configuration directly!

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=Europe/UTC
      - ORIGIN=http://localhost:3000 # Set to the frontend url. It's the url you will use to access the frontend. This is used by both auth & svelte csrf protection.
      - BACKEND_URL=http://riven:8080
      - BACKEND_API_KEY=my32charapikey1234567890abcdefgh
    depends_on:
      riven:
        condition: service_healthy
    volumes:
      - ./riven-frontend/data:/riven/data

  riven:
    image: spoked/riven:latest
    container_name: riven
    restart: unless-stopped
    ports:
      - "8080:8080"
    tty: true
    cap_add:
      - SYS_ADMIN
    security_opt:
      - apparmor:unconfined
    devices:
      - /dev/fuse
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Europe/UTC
      - RIVEN_FORCE_ENV=true
      - RIVEN_DATABASE_HOST=postgresql+psycopg2://postgres:postgres@riven-db/riven
      - RIVEN_FILESYSTEM_MOUNT_PATH=/mount
    healthcheck:
      test: curl -s http://localhost:8080 >/dev/null || exit 1
      interval: 30s
      timeout: 10s
      retries: 10
    volumes:
      - ./riven/data:/riven/data
      - /mnt/riven:/mount:rshared,z # Use your actual host mount path here
    depends_on:
      riven-db:
        condition: service_healthy

  riven-db:
    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

Step 3: Customize Configuration

Edit the docker-compose.yml file to match your setup:

Timezone: Change TZ to your timezone (e.g., Europe/London, Asia/Tokyo)
User IDs: Set PUID and PGID to match your user (run id command to find yours)
Mount Path: Change /mnt/riven to your actual host mount path (keep :rshared,z flags!)
Origin URL (optional): If using a custom domain, update ORIGIN to your URL

If you're running Riven behind a reverse proxy (nginx, Caddy, Traefik), you can remove the ORIGIN environment variable from the frontend service. See the Deployment Guide for reverse proxy examples.

Step 4: Start Riven

Launch the services:

docker-compose up -d

Monitor the logs to ensure everything starts correctly:

docker-compose logs -f

Wait until you see messages indicating that all services are healthy and running.

Step 5: Access the Web Interface

Open your browser and navigate to:

http://localhost:3000

Or use the custom URL you configured in the ORIGIN variable.

Need Help?

If you encounter issues not covered in this guide:

Check the Troubleshooting Guide
Review the logs: docker-compose logs -f riven
Join the Discord community for support
Search or create an issue on GitHub

Happy streaming with Riven!

Getting Started

On this page