Riven

https://riven.tv/docs
Admin
Riven is an all-in-one media management solution that automates finding, downloading, and organizing...
Tokens:10,237
Snippets:143
Trust Score:4.6
Update:3 months ago
Show doc for...
Tokens:
Raw
### Enable a Plugin

Source: https://riven.tv/docs/plugins

To enable a plugin, add its name to the RIVEN_SETTING__enabledPlugins configuration array. This example enables the 'seerr' plugin.

```bash
RIVEN_SETTING__enabledPlugins=["seerr"]
```

--------------------------------

### Start Riven with Docker Compose

Source: https://riven.tv/docs/getting-started

Command to start all services defined in the docker-compose.yml file in detached mode.

```bash
docker compose up -d
```

--------------------------------

### Setup Mount Propagation Commands

Source: https://riven.tv/docs/deployment

Commands to create the Riven data directory, reload the systemd daemon, and enable/start the mount propagation service.

```bash
sudo mkdir -p /mnt/riven
sudo systemctl daemon-reload
sudo systemctl enable --now riven-mount.service
```

--------------------------------

### Jellyfin Media Server Integration with Riven

Source: https://riven.tv/docs/deployment

Example configuration to integrate Jellyfin with Riven TS within the same Docker Compose setup. It highlights the use of `rslave` propagation for the shared VFS mount, contrasting with Riven's `rshared`.

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

--------------------------------

### Ensure PostgreSQL Health Before Riven Startup

Source: https://riven.tv/docs/troubleshooting

Configure Riven's dependency on the PostgreSQL service to ensure it's healthy before Riven starts.

```yaml
depends_on:
  postgres:
    condition: service_healthy
```

--------------------------------

### Write Plugin Tests

Source: https://riven.tv/docs/plugin-sdk

Write unit tests for your plugin's data sources using the provided testing utilities. This example demonstrates testing the `validate` method of the `MyServiceAPI`.

```typescript
import { it } from "@repo/util-plugin-testing/plugin-test-context";

import { HttpResponse } from "msw";
import { expect } from "vitest";

import { pluginConfig } from "../../my-service-plugin.config.ts";
import { MyServiceAPI } from "../my-service.datasource.ts";

it("returns true if the request succeeds", async ({ 
  server,
  dataSourceConfig,
}) => {
  server.use(getHealthCheckHandler());

  const api = new MyServiceAPI({
    ...dataSourceConfig,
    pluginSymbol: pluginConfig.name,
    settings: { apiKey: "test-key" },
  });

  expect(await api.validate()).toBe(true);
});
```

--------------------------------

### Environment Variables for Riven Configuration

Source: https://riven.tv/docs/getting-started

Configures Riven settings, database connection, Redis URL, VFS mount path, logging level, and API keys for plugins like TMDB, StremThru, and MDBList. Customize these values according to your setup.

```env
# Enabled plugins
RIVEN_SETTING__enabledPlugins=["..."]

# Database
RIVEN_SETTING__databaseUrl="postgres+psycopg2://riven:riven@postgres:5432/riven"

# Redis
RIVEN_SETTING__redisUrl="redis://redis:6379"

# VFS mount path (must match the volume mount)
RIVEN_SETTING__vfsMountPath="/mnt/riven"

# Logging
RIVEN_SETTING__logLevel="info"

# TMDB (required for metadata)
RIVEN_PLUGIN_SETTING__REPO_PLUGIN_TMDB__apiKey="your-tmdb-api-key"

# Debrid provider (via StremThru)
RIVEN_PLUGIN_SETTING__REPO_PLUGIN_STREMTHRU__realdebridApiKey="your-rd-key"
RIVEN_PLUGIN_SETTING__REPO_PLUGIN_STREMTHRU__torboxApiKey="your-tb-key"

# Content source (pick at least one)
RIVEN_PLUGIN_SETTING__REPO_PLUGIN_MDBLIST__apiKey="your-mdblist-key"
RIVEN_PLUGIN_SETTING__REPO_PLUGIN_MDBLIST__lists=["user/list-name"]
```

--------------------------------

### Create GraphQL Resolvers

Source: https://riven.tv/docs/plugin-sdk

Define GraphQL resolvers to interact with your plugin's data sources and expose functionality via queries. This example shows a resolver for validating the data source.

```typescript
import { PluginDataSource } from "@repo/util-plugin-sdk";

import { Query, Resolver } from "type-graphql";

import { MyServiceAPI } from "../datasource/my-service.datasource.ts";
import { pluginConfig } from "../my-service-plugin.config.ts";

@Resolver()
export class MyServiceResolver {
  @Query((_returns) => Boolean)
  async myServiceIsValid(
    @PluginDataSource(pluginConfig.name, MyServiceAPI) api: MyServiceAPI,
  ): Promise<boolean> {
    return await api.validate();
  }
}
```

--------------------------------

### Seerr Plugin Configuration

Source: https://riven.tv/docs/plugins

Configure the Seerr plugin by providing its URL and API key.

```bash
# Seerr
RIVEN_PLUGIN_SETTING__REPO_PLUGIN_SEERR__url="http://seerr:5055"
RIVEN_PLUGIN_SETTING__REPO_PLUGIN_SEERR__apiKey="your-seerr-key"
```

--------------------------------

### Verify VFS Mount for Media Server

Source: https://riven.tv/docs/troubleshooting

Ensure the Riven VFS is mounted correctly on the host by checking if files are visible in `/mnt/riven`.

```bash
ls /mnt/riven
```

--------------------------------

### Plugin Project Structure

Source: https://riven.tv/docs/plugin-sdk

Illustrates the typical directory layout for a Riven TV plugin, including configuration, data sources, schemas, and documentation.

```tree
packages/plugin-my-service/
├── lib/
│   ├── index.ts                    # Plugin export
│   ├── my-service-plugin.config.ts # Plugin identifier
│   ├── datasource/
│   │   ├── my-service.datasource.ts
│   │   └── __tests__/
│   │       └── validate.spec.ts
│   └── schema/
│       ├── my-service.resolver.ts
│       ├── my-service-settings.resolver.ts
│       ├── types/
│       │   └── my-service-settings.type.ts
│       └── arguments/
│           └── list-id.arguments.ts
├── docs/
│   └── settings.mdx                 # Auto-generated settings doc
├── package.json
└── tsconfig.json
```

--------------------------------

### Plugin Configuration Pattern

Source: https://riven.tv/docs/plugins

All plugin settings are configured using environment variables following the pattern RIVEN_PLUGIN_SETTING__REPO_PLUGIN_<NAME>__<settingName>="value". The plugin name is uppercase with underscores.

```bash
RIVEN_PLUGIN_SETTING__REPO_PLUGIN_<NAME>__<settingName>="value"
```

--------------------------------

### Monitor Riven Logs

Source: https://riven.tv/docs/getting-started

Follow the logs of the Riven container to verify successful startup and identify any potential issues.

```bash
docker compose logs -f riven
```

--------------------------------

### MDBList Plugin Configuration

Source: https://riven.tv/docs/plugins

Configure the MDBList plugin with your API key and specify the lists to use.

```bash
# MDBList with lists
RIVEN_PLUGIN_SETTING__REPO_PLUGIN_MDBLIST__apiKey="your-key"
RIVEN_PLUGIN_SETTING__REPO_PLUGIN_MDBLIST__lists=["username/list-name"]
```

--------------------------------

### Configure Media Server Volume Mount for Slave Propagation

Source: https://riven.tv/docs/troubleshooting

Use 'rslave' propagation for media server volume mounts that access Riven's VFS to ensure timely updates.

```yaml
volumes:
  - /mnt/riven:/mnt/riven:rslave,z
```

--------------------------------

### Scaffold a New Plugin

Source: https://riven.tv/docs/plugin-sdk

Use the Turbo Generator to create a new plugin project. This command scaffolds the plugin and adds it as a dependency to the main application.

```bash
turbo gen plugin --args my-service
```

--------------------------------

### Configure Riven Database Connection URL

Source: https://riven.tv/docs/troubleshooting

Set the RIVEN_SETTING__databaseUrl environment variable to match your PostgreSQL credentials for Riven to connect.

```env
RIVEN_SETTING__databaseUrl="postgres+psycopg2://user:password@postgres:5432/riven"
```

--------------------------------

### Run Plugin Tests

Source: https://riven.tv/docs/plugin-sdk

Execute plugin tests using the Turbo build system. This command filters tests to run only for the specified plugin.

```bash
pnpm turbo test --filter=@repo/plugin-my-service
```

--------------------------------

### StremThru Plugin Configuration (TorBox)

Source: https://riven.tv/docs/plugins

Configure the StremThru plugin for TorBox integration by providing your TorBox API key.

```bash
# StremThru with TorBox
RIVEN_PLUGIN_SETTING__REPO_PLUGIN_STREMTHRU__torboxApiKey="your-tb-key"
```

--------------------------------

### Run Kubb Code Generation with Turbo

Source: https://riven.tv/docs/plugin-sdk

Execute the Kubb code generation process using Turbo. This command filters the generation to a specific service, ensuring only relevant code is produced.

```bash
pnpm turbo codegen --filter=@repo/plugin-my-service
```

--------------------------------

### Verify Mount Propagation

Source: https://riven.tv/docs/deployment

Command to verify that the mount propagation for the Riven data directory is set to 'shared'. This is a crucial step after setting up the systemd service.

```bash
findmnt -o TARGET,PROPAGATION /mnt/riven
```

--------------------------------

### TMDB Plugin Configuration

Source: https://riven.tv/docs/plugins

Configure the TMDB plugin by providing your TMDB API key.

```bash
# TMDB
RIVEN_PLUGIN_SETTING__REPO_PLUGIN_TMDB__apiKey="your-tmdb-key"
```

--------------------------------

### Create Settings Resolver

Source: https://riven.tv/docs/plugin-sdk

Create a settings resolver to expose plugin configuration details via GraphQL. This allows external systems to query plugin-specific settings.

```typescript
import { Settings } from "@repo/util-plugin-sdk";

import { FieldResolver, Resolver } from "type-graphql";

@Resolver((_of) => Settings)
export class MyServiceSettingsResolver {
  @FieldResolver((_returns) => MyServiceSettings)
  myService(): MyServiceSettings {
    return { apiKey: "my-service-api-key" };
  }
}
```

--------------------------------

### Configure Plugin API Key Environment Variable

Source: https://riven.tv/docs/troubleshooting

Set the RIVEN_PLUGIN_SETTING__REPO_PLUGIN_TMDB__apiKey environment variable in your .env file to authenticate plugins.

```env
# Correct format
RIVEN_PLUGIN_SETTING__REPO_PLUGIN_TMDB__apiKey="your-key"

# Common mistakes:
# Missing quotes around values with special characters
# Extra spaces around the = sign
# Wrong plugin name (case-sensitive)
```

--------------------------------

### Check Riven Mount Service Status

Source: https://riven.tv/docs/troubleshooting

Verify if the riven-mount.service is active and running on the host system.

```bash
sudo systemctl status riven-mount.service
```

--------------------------------

### Check Riven Container Logs for Restarts

Source: https://riven.tv/docs/troubleshooting

View the last 50 lines of Riven's logs to diagnose reasons for frequent container restarts.

```bash
docker compose logs --tail=50 riven
```

--------------------------------

### Configure Riven Redis URL

Source: https://riven.tv/docs/troubleshooting

Set the RIVEN_SETTING__redisUrl environment variable to the correct Redis connection string.

```env
RIVEN_SETTING__redisUrl="redis://redis:6379"
```

--------------------------------

### Custom Ranking Configuration Preset

Source: https://riven.tv/docs/ranking-configuration/presets/custom

This JSON structure defines a custom preset for ranking configuration. Use the 'settings' object for specific ranking adjustments and the 'rankingModel' object to define the custom ranking logic.

```json
{
  "preset": "custom",
  "settings": {
    // Add your custom ranking configuration settings here
  },
  "rankingModel": {
    // Define your custom ranking model here
    //
  }
}
```

--------------------------------

### Check Riven Logs for Plugin Errors

Source: https://riven.tv/docs/troubleshooting

Filter Riven's logs to identify specific validation errors related to plugin startup.

```bash
docker compose logs riven | grep -i plugin
```

--------------------------------

### Define Plugin Configuration

Source: https://riven.tv/docs/plugin-sdk

Define the plugin's configuration, including its unique name using a Symbol. This Symbol is crucial for identification, queue naming, and dependency injection within the Riven ecosystem.

```typescript
import type { RivenPluginConfig } from "@repo/util-plugin-sdk";

export const pluginConfig = {
  name: Symbol("@repo/plugin-my-service"),
} satisfies RivenPluginConfig;
```

--------------------------------

### Systemd Service for Mount Propagation

Source: https://riven.tv/docs/deployment

This systemd service ensures that the Riven data bind mount is shared correctly, which is critical for the VFS to be visible outside the container. It sets up shared mount propagation for the /mnt/riven directory.

```systemd
[Unit]
Description=Make Riven data bind mount shared
After=local-fs.target
Before=docker.service

[Service]
Type=oneshot
ExecStart=/usr/bin/mount --bind /mnt/riven /mnt/riven
ExecStart=/usr/bin/mount --make-rshared /mnt/riven
RemainAfterExit=yes

[Install]
WantedBy=multi-user.target
```

--------------------------------

### Monorepo Directory Structure

Source: https://riven.tv/docs/architecture

Overview of the Riven TV monorepo, detailing the organization of applications and packages.

```tree
riven-ts/
├── apps/
│   ├── riven/          # Main application
│   └── wiki/           # This documentation site
├── packages/
│   ├── core/           # Shared infrastructure
│   │   ├── util-database/
│   │   ├── util-graphql-*
│   │   ├── util-logger/
│   │   └── ...
│   ├── plugin-*       # Plugins
│   ├── util-plugin-sdk/    # Plugin SDK
│   ├── util-plugin-testing/# Plugin test utilities
│   ├── util-rank-torrent-name/ # Torrent ranking
│   └── feature-settings/   # Settings management

```

--------------------------------

### Configure Container Capabilities for /dev/fuse

Source: https://riven.tv/docs/troubleshooting

Grant the Riven container necessary capabilities (SYS_ADMIN) and security options (apparmor:unconfined) to access /dev/fuse.

```yaml
cap_add:
  - SYS_ADMIN
security_opt:
  - apparmor:unconfined
devices:
  - /dev/fuse
```

--------------------------------

### Export the Plugin

Source: https://riven.tv/docs/plugin-sdk

Export the plugin's main object, including its name, version, data sources, resolvers, and hooks. This is the entry point for the Riven plugin system.

```typescript
import { type RivenPlugin } from "@repo/util-plugin-sdk";

import packageJson from "../package.json";
import { MyServiceAPI } from "./datasource/my-service.datasource.ts";
import { pluginConfig } from "./my-service-plugin.config.ts";
import { MyServiceSettingsResolver } from "./schema/my-service-settings.resolver.ts";
import { MyServiceResolver } from "./schema/my-service.resolver.ts";

export default {
  name: pluginConfig.name,
  version: packageJson.version,
  dataSources: [MyServiceAPI],
  resolvers: [MyServiceResolver, MyServiceSettingsResolver],

  hooks: {
    "riven.content-service.requested": async ({ dataSources }) => {
      const api = dataSources.get(MyServiceAPI);
      if (!api) return { movies: [], shows: [] };

      const items = await api.getItems("default-list");
      return {
        movies: items.filter((i) => i.type === "movie"),
        shows: items.filter((i) => i.type === "show"),
      };
    },
  },

  validator() {
    return Promise.resolve(Boolean(process.env["MY_SERVICE_API_KEY"]));
  },
} satisfies RivenPlugin as RivenPlugin;
```

--------------------------------

### Default Ranking Configuration Usage

Source: https://riven.tv/docs/ranking-configuration/presets/default

Use this JSON object to apply the default ranking model in Riven.

```json
{
  "rankingModel": "default"
}
```

--------------------------------

### Reset Riven Database

Source: https://riven.tv/docs/troubleshooting

Down Riven and its volumes, then bring them back up to reset a corrupted database. This will result in data loss.

```bash
docker compose down -v  # Removes volumes!
docker compose up -d
```

--------------------------------

### Configure Docker Volume Mount for Shared Propagation

Source: https://riven.tv/docs/troubleshooting

Ensure Docker volume mounts for Riven use 'rshared' propagation to synchronize mounts between host and container.

```yaml
volumes:
  - /mnt/riven:/mnt/riven:rshared,z
```

--------------------------------

### Check Redis Service Status and Logs

Source: https://riven.tv/docs/troubleshooting

Verify that the Redis service is running and check its logs for any connection or health issues.

```bash
docker compose ps redis
docker compose logs redis
```

--------------------------------

### StremThru Plugin Configuration (Real-Debrid)

Source: https://riven.tv/docs/plugins

Configure the StremThru plugin for Real-Debrid integration by providing your Real-Debrid API key.

```bash
# StremThru with Real-Debrid
RIVEN_PLUGIN_SETTING__REPO_PLUGIN_STREMTHRU__realdebridApiKey="your-rd-key"
```

--------------------------------

### Default Ranking Preset Values

Source: https://riven.tv/docs/ranking-configuration/presets/default

This object defines the default scoring for various media attributes, including quality, resolution, and audio formats. Adjust these values to fine-tune the ranking algorithm.

```json
{
  rankingModel: {
    // Quality
    av1: 500,
    avc: 500,
    bluray: 100,
    hdtv: -5000,
    hevc: 500,
    remux: 10000,
    web: 100,
    webdl: 200,

    // Rips
    brrip: -10000,
    hdrip: -10000,
    webrip: -1000,

    // HDR
    bit10: 100,
    dolbyVision: 3000,
    hdr: 2000,
    hdr10plus: 2100,
    sdr: 0,

    // Audio
    aac: 100,
    atmos: 1000,
    dolbyDigital: 50,
    dolbyDigitalPlus: 150,
    dtsLossy: 100,
    dtsLossless: 2000,
    flac: 0,
    stereo: 0,
    surround: 0,
    truehd: 2000,

    // Extras
    dubbed: -1000,
    edition: 100,
    hardcoded: 0,
    network: 0,
    proper: 20,
    repack: 20,
    retail: 0,
    subbed: 0,
    scene: 0,
    uncensored: 0,
  },
  settings: {
    resolutions: {
      r2160p: true,
    },
  },
}
```

--------------------------------

### Pull Riven TS Docker Image

Source: https://riven.tv/docs/versions

Use this command to pull the latest Riven TS Docker image. This is the recommended version for new users.

```bash
docker pull ghcr.io/rivenmedia/riven-ts:latest
```

--------------------------------

### Implement a DataSource

Source: https://riven.tv/docs/plugin-sdk

Implement a DataSource by extending BaseDataSource to create HTTP API clients. This class provides built-in features like rate limiting, caching, retry logic, and telemetry.

```typescript
import { BaseDataSource, type RateLimiterOptions } from "@repo/util-plugin-sdk";

export class MyServiceAPI extends BaseDataSource<MyServiceSettings> {
  override baseURL = "https://api.myservice.com/v1/";
  override serviceName = "MyService";

  protected override readonly rateLimiterOptions: RateLimiterOptions = {
    max: 50,
    duration: 1000,
  };

  // Authentication
  static override getApiToken() {
    return process.env["MY_SERVICE_API_KEY"];
  }

  protected override willSendRequest(
    _path: string,
    requestOpts: AugmentedRequest,
  ) {
    if (!this.token) throw new Error("API token is not set");
    requestOpts.headers["x-api-key"] = this.token;
  }

  // Validation (called on startup)
  override async validate() {
    try {
      await this.get("health");
      return true;
    } catch {
      return false;
    }
  }

  // Business methods
  async getItems(listId: string): Promise<ExternalIds[]> {
    const response = await this.get(`lists/${listId}/items`, {
      cacheOptions: { ttl: 1000 * 60 * 5 },
    });
    return response.items.map((item) => ({
      imdbId: item.imdb_id,
      tmdbId: item.tmdb_id,
    }));
  }
}
```

--------------------------------

### Configure Kubb for OpenAPI Code Generation

Source: https://riven.tv/docs/plugin-sdk

Configure Kubb to generate code from an OpenAPI specification. Specify the input OpenAPI spec path, the desired output name, and the base URL for the API.

```typescript
import { buildKubbConfig } from "@repo/core-util-kubb-config";

import { defineConfig } from "@kubb/core";

export default buildKubbConfig({
  input: { path: "https://api.myservice.com/swagger.json" },
  name: "MyService",
  baseURL: "https://api.myservice.com",
});
```

--------------------------------

### Manually Unmount and Restart Riven

Source: https://riven.tv/docs/troubleshooting

If a simple restart doesn't fix 'Transport endpoint is not connected', manually unmount the FUSE filesystem and then restart the Riven container.

```bash
sudo fusermount -uz /mnt/riven
docker compose restart riven
```

--------------------------------

### Restart Riven Container

Source: https://riven.tv/docs/troubleshooting

Restart the Riven container using Docker Compose to resolve 'Transport endpoint is not connected' errors.

```bash
docker compose restart riven
```

--------------------------------

### Docker Compose File for Riven TS

Source: https://riven.tv/docs/deployment

The primary Docker Compose file for deploying Riven TS, including its PostgreSQL and Redis dependencies. It configures volumes, environment variables, and health checks.

```yaml
services:
  riven:
    image: ghcr.io/rivenmedia/riven-ts:latest
    container_name: riven
    restart: unless-stopped
    tty: true
    cap_add:
      - SYS_ADMIN
    security_opt:
      - apparmor:unconfined
    devices:
      - /dev/fuse
    env_file: .env
    volumes:
      - riven_data:/riven/data
      - /mnt/riven:/mnt/riven:rshared,z
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy

  postgres:
    image: postgres:17-alpine
    environment:
      POSTGRES_USER: riven
      POSTGRES_PASSWORD: CHANGEME
      POSTGRES_DB: riven
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U riven"]
      interval: 5s
      timeout: 5s
      retries: 5

  redis:
    image: redis:8-alpine
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 5s
      retries: 5

volumes:
  riven_data:
  postgres_data:
  redis_data:
```

--------------------------------

### RivenPlugin Interface Definition

Source: https://riven.tv/docs/plugin-sdk

Defines the structure that every Riven plugin must adhere to, including its name, version, data sources, resolvers, hooks, context, settings schema, and validator.

```typescript
interface RivenPlugin {
  name: Symbol; // Unique identifier
  version: string; // Semver version
  dataSources?: BaseDataSource[]; // HTTP API clients (optional)
  resolvers: Function[]; // GraphQL resolvers (required, min 1)
  hooks?: EventHandlers; // Event handlers (optional)
  context?: Function; // Custom context (optional)
  settingsSchema: ZodObject; // Settings validation schema
  validator: Function; // Check if plugin can start
}
```

--------------------------------

### Update Riven TS with Docker Compose

Source: https://riven.tv/docs/deployment

Commands to update Riven TS to the latest version using Docker Compose. This involves pulling the new image and restarting the containers.

```bash
docker compose pull
docker compose up -d
```

--------------------------------

### Nginx Reverse Proxy Configuration

Source: https://riven.tv/docs/deployment

Configuration snippet for Nginx to act as a reverse proxy for Riven TS. It forwards requests to the Riven TS service running on localhost:3000 and sets necessary proxy headers.

```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;
    }
}
```

--------------------------------

### Traefik Reverse Proxy Configuration

Source: https://riven.tv/docs/deployment

Configuration snippet for Traefik to act as a reverse proxy for Riven TS. It sets up routing based on a hostname and enables TLS with a certificate resolver.

```yaml
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
```
Tokens:
Raw