Services currently supported:

and more to come!

Check out out Project Board to stay informed!

Please add feature requests and issues over on our Issue Tracker or join our Discord to chat with us!

We are constantly adding features and improvements as we go along and squashing bugs as they arise.

• Table of Contents
• ElfHosted
• Native Windows Setup
  • Prerequisites
  • Installation
  • Running the Backend
  • Running the Frontend
  • Plex Libraries
  • Troubleshooting
• RivenVFS and Caching
• Development
  • Clone and Bootstrap
  • Running the Backend Manually
  • Running Tests
  • Additional Tips
• Contributing
  • Submitting Changes
  • Code Formatting
  • Dependency Management
    • Adding or Updating Dependencies
  • Running Tests and Linters
• License

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!

• Windows 11 with the latest updates.
• PowerShell 5.1 or PowerShell 7 (all examples below use PowerShell syntax).
• Python 3.11+ for Windows with Add python.exe to PATH enabled during installation.
• Git for Windows.
• Optional: Node.js 18+ when you plan to work on the standalone frontend.
• Optional: Plex Media Server for Windows if you want to integrate with Plex locally.

1. Decide where you want Riven to keep its data. The examples below assume C:\Riven, but you can substitute any writable location.

2. Create the directories Riven expects by running the following in PowerShell:

   $root = 'C:\Riven'
   New-Item -ItemType Directory -Force -Path $root, (Join-Path $root 'mount'), (Join-Path $root 'data') | Out-Null

3. Clone the repository and switch into it:

   git clone https://github.com/rivenmedia/riven.git
   Set-Location riven

4. Allow scripts for the current session (if you have not already) and launch the backend bootstrapper:

   Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
   .\scripts\Start-Backend.ps1 -IncludeDevDependencies

   The script provisions a .venv directory, installs Poetry, restores dependencies (including the optional developer extras when -IncludeDevDependencies is supplied), and starts the FastAPI backend on port 8080. Press Ctrl+C to stop it when you are finished.

5. In the Riven web UI, set the Filesystem mount path to the directory you created earlier (for example C:\Riven\mount). Any folders you create under that mount path (movies, shows, and so on) will be exposed to Plex and other media servers.

Whenever you want to bring Riven online, open PowerShell in the repository root and run:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
./scripts/Start-Backend.ps1

Use -Port <number> to choose a different listening port, -SkipInstall when you only want to reuse the existing virtual environment, and -EnableDebugger to opt into extra debugging output.

The backend bundles the settings UI, but you can also run the standalone frontend when you want hot reloading or to work on UI changes. After cloning the UI repository next to this one (for example C:\Riven\frontend), run:

./scripts/Start-Frontend.ps1 -FrontendPath ..\frontend

The script picks npm by default. Override it with -PackageManager pnpm, -PackageManager yarn, or -PackageManager bun if you use an alternative toolchain. Forward additional CLI flags with -ScriptArguments "-- --host localhost --port 3000".

Create the library folders you want Plex to index beneath your chosen mount directory. Riven expects the following sections to exist:

Point Plex at the same Windows paths that Riven uses (for example C:\Riven\mount\movies). Keeping the paths identical between Riven and Plex avoids sync issues.

• Riven UI cannot see your media folders: Confirm the path in Settings → Filesystem matches the directory you created earlier (for example C:\Riven\mount). Use Test-Path 'C:\Riven\mount' in PowerShell to verify it exists.
• Plex does not detect new files: Make sure Plex is pointed at the exact same Windows path as Riven and that your Windows account has permission to read the folders. Trigger a library refresh from Plex after the first sync.
• Need a clean restart: Close the PowerShell window running Riven or press Ctrl+C, then rerun ./scripts/Start-Backend.ps1.

• cache_dir: Directory to store on‑disk cache files (use a user‑writable path).

• cache_max_size_mb: Max cache size (MB) for the VFS cache directory.

• chunk_size_mb: Size of individual CDN requests (MB). Default 32MB provides good balance between efficiency and connection reliability.

• fetch_ahead_chunks: Number of chunks to prefetch ahead of current read position. Default 4 chunks prefetches 128MB ahead (4 × 32MB) for smooth streaming with fair multi-user scheduling.

• ttl_seconds: Optional expiry horizon when using eviction = "TTL" (default eviction is LRU).

• Eviction behavior:

  • LRU (default): Strictly enforces the configured size caps by evicting least‑recently‑used blocks when space is needed.
  • TTL: First removes entries that have been idle longer than ttl_seconds (sliding expiration). If the cache still exceeds the configured size cap after TTL pruning, it additionally trims oldest entries (LRU) until usage is within the limit.

Welcome to the development section! Here, you'll find the steps required to set up a native Windows environment and start contributing to the project.

1. Clone the Repository

   git clone https://github.com/rivenmedia/riven.git
   Set-Location riven

2. Provision the Virtual Environment

   Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
   ./scripts/Start-Backend.ps1 -IncludeDevDependencies

   Running the script once sets up the .venv directory, installs Poetry, restores dependencies (including the developer extras), and starts the backend. Use Ctrl+C to stop it after the install completes.

After the initial bootstrap you can control the backend directly from PowerShell:

.\.venv\Scripts\Activate.ps1
poetry run python src/main.py --port 8080
deactivate

Adjust the --port argument as needed. Activating the virtual environment first ensures poetry and the project dependencies resolve correctly.

Activate the virtual environment and invoke the test suite through Poetry:

.\.venv\Scripts\Activate.ps1
poetry run pytest
deactivate

Pass additional arguments (for example poetry run pytest src/tests/test_updaters.py) to narrow the scope during development.

• Environment Variables: Set the ORIGIN environment variable to the URL where the frontend will be accessible.

  $Env:ORIGIN = 'http://localhost:3000'

• Dependency Tweaks: Re-run ./scripts/Start-Backend.ps1 -IncludeDevDependencies after modifying pyproject.toml to make sure the lock file and virtual environment stay in sync.

• Frontend Workflows: Use ./scripts/Start-Frontend.ps1 for hot reloading and pass -ScriptArguments to forward flags directly to the underlying package manager.

We welcome contributions from the community! To ensure a smooth collaboration, please follow these guidelines:

1. Open an Issue: For major changes, start by opening an issue to discuss your proposed modifications. This helps us understand your intentions and provide feedback early in the process.
2. Pull Requests: Once your changes are ready, submit a pull request. Ensure your code adheres to our coding standards and passes all tests. Commits should follow conventional-commits specification.

• We use Black for code formatting. Run black on your code before submitting.
• Use CRLF line endings unless the file is a shell script or another format that requires LF line endings.

We use Poetry for managing dependencies. Poetry simplifies dependency management by automatically handling package versions and resolving conflicts, ensuring consistency across all environments.

• Add a Dependency: Use poetry add <package-name> to add a new dependency.
• Update a Dependency: Use poetry update <package-name> to update an existing dependency.

Before submitting a pull request, ensure your changes are compatible with the project's dependencies and coding standards. Use the following commands to run tests and linters:

• Run Tests: poetry run pytest
• Run Linters: poetry run ruff check backend and poetry run isort --check-only backend

By following these guidelines, you help us maintain a high-quality codebase and streamline the review process. Thank you for contributing!

Riven Analytics

This project is licensed under the GNU GPLv3 License - see the LICENSE file for details