Riven is a media automation system that uses a virtual file system and debrid services to find, organize, and stream your media. It integrates with Plex, Jellyfin, and many other services.

Riven-TS is the official TypeScript rewrite of Riven, featuring a modern plugin architecture, GraphQL API, and extensible design. It is the actively developed version going forward.

How do I get started with Riven?

Deploy Riven with Docker using our compose generator or follow the documentation at https://riven.tv/docs.

Deployment | Riven

This page covers what changes once Riven is more than a test install. For the initial setup, see Getting Started.

Requirements

Linux host with FUSE support
Docker Engine 24+ with Compose V2
PostgreSQL 17 and Redis 8

Media Server Integration

Add your media server to the same compose file. Riven's container uses rshared propagation to publish its FUSE mount; consumers use rslave to receive it:

Jellyfin example

jellyfin:
  image: jellyfin/jellyfin:latest
  ports:
    - 8096:8096
  volumes:
    - jellyfin_config:/config
    - /mnt/riven:/mount:rslave,z
  depends_on:
    riven:
      condition: service_started

The media server must start after Riven has mounted the VFS. If it scans an empty mount it will mark the library as unavailable.

Reverse Proxy

Riven serves GraphQL on port 3000. Make sure RIVEN_SETTING__gqlHost="0.0.0.0" is set, or the proxy will get connection refused.

Traefik

labels:
  - traefik.enable=true
  - traefik.http.routers.riven.rule=Host(`riven.example.com`)
  - traefik.http.routers.riven.entrypoints=websecure
  - traefik.http.routers.riven.tls=true
  - traefik.http.routers.riven.tls.certresolver=leresolver
  - traefik.http.services.riven.loadbalancer.server.port=3000

Nginx

server {
    server_name riven.example.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

The GraphQL API currently has no authentication. Do not expose it to the internet without putting auth in front of it.

Pinning a Version

:main tracks the latest build of the default branch and can change under you. For production, pin a release instead:

image: ghcr.io/rivenmedia/riven-ts:1.2.3

Available tags are on the package page. There is no latest tag.

Updating

docker compose pull
docker compose up -d

Database migrations run automatically on startup.

Backups

PostgreSQL holds your library — media items, requests, streams, and the VFS file entries. Back it up:

docker compose exec postgres pg_dump -U riven riven | gzip > riven-backup.sql.gz

Keep your .env and the generated ranking config (./data) too. Logs are disposable, and Redis only holds in-flight queue state.

Deployment