Getting Started
All in one media management solution
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.
⚙️ 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.
🔧 Powerful Configuration
Customize Riven to fit your media management needs. Configure debrid services, media servers, scrapers and more with our user-friendly interface.
💬 Active Community
Join our vibrant community for support, updates, and contributions. Collaborate with other users and developers to make Riven even better.
Getting Started

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:
- Automatically discovering new content based on your preferences and watchlists.
- Efficiently searching for and downloading high-quality media files via debrid services.
- Organizing your media library using RivenVFS, a high-performance virtual filesystem.
- Streaming content on-demand with intelligent caching and prefetching.
- Seamlessly integrating with your chosen media server for immediate streaming access.
- 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
- Docker: Required to run Riven. Learn more
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:
riven: The main application (backend).riven-frontend: The web interface (frontend).riven-db: The database.
Docker Hub Tags
Both spoked/riven (backend) and spoked/riven-frontend (frontend) repositories use the same tagging conventions:
| Tag | Version | Description |
|---|---|---|
latest | v0 (Legacy) | The legacy version of Riven |
dev | v1 (Beta) | Latest development builds - recommended for beta users |
main | v1 (Beta) | Same as dev - latest development builds |
| Other tags | Various | Branch 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.
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: 5Now this won't work as is, you need to modify the docker-compose.yml file to match your setup.
-
Change
TZto your timezone in both riven & riven-frontend. -
riven-frontendservice:- Change
ORIGINto the URL you will be accessing the web interface from. For example, if you are planning to run Riven onhttps://riven.example.com, change it tohttps://riven.example.com. - Change
BACKEND_URLto the URL where the frontend can access the backend. - Change
BACKEND_API_KEYto the Riven backend API key. This can be found in the backendsettings.jsonfile which is generated on first run, or you can set it usingRIVEN_API_KEYenvironment variable inrivenservice. - Generate a random secret key (e.g., using
openssl rand -base64 32) and set it toAUTH_SECRETenvironment variable inriven-frontendservice.
- Change
-
rivenservice:- Set
PUID&PGIDto your user ID & group ID. This is usually 1000 for both, but you can find it usingid -u&id -gcommands. RIVEN_FILESYSTEM_MOUNT_PATHis the path where the virtual filesystem will be mounted.RIVEN_UPDATERS_LIBRARY_PATHis 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).
- Set
Running Riven
Depending on how you installed Riven, execute the following command:
docker-compose up -d && docker-compose logs -fPython Version
Riven requires Python 3.12 or higher and uv to be installed.
make install
make runYou 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.
