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

• Table of Contents
• ElfHosted
• Self Hosted
  • Docker Compose
  • What is ORIGIN ?
  • Running outside of Docker
  • First terminal:
  • Second terminal:
  • Symlinking settings
• Development
  • Prerequisites
  • Initial Setup
  • Using make for Development
  • Development without make
  • Additional Tips
• Contributing
  • Submitting Changes
  • Code Formatting
  • Dependency Management
  • Setting Up Your Environment
  • Adding or Updating Dependencies
  • Running Tests and Linters
• License

ElfHosted

ElfHosted is a geeky open-source PaaS which provides all the "plumbing" (hosting, security, updates, etc) for your self-hosted apps.

[!IMPORTANT] ElfHosted ❤️ Riven 100%

Riven is an "Elf-icial" app in the ElfHosted app catalogue - A whopping :heart_eyes_cat::heart_eyes_cat: 100% :heart_eyes_cat::heart_eyes_cat: of your subscription goes directly to Riven developers, who can usually be found in the #elf-riven channel in the ElfHosted Discord Server.

Curious how it works? Here's an explainer video!

[!TIP] ElfHosted "Infinite Streaming" bundles

Riven is pre-packaged with Plex, Zurg, and symlinks, and ready-to-go, in these convenient bundles:

• Starter Kit (quick and easy setup)
• Hobbit Bundle (12.5% dedicated node, with extras)
• Ranger Bundle (25% dedicated node, with extras)

Self Hosted

Docker Compose

Copy over the contents of docker-compose.yml to your docker-compose.yml file.

[!NOTE] You can check out the docker-compose-full.yml file to get an idea of how things tie together.

Then run docker compose up -d to start the container in the background. You can then access the web interface at http://localhost:3000 or whatever port and origin you set in the docker-compose.yml file.

[!TIP] On first run, Riven creates a settings.json file in the data directory. You can edit the settings from frontend, or manually edit the file and restart the container or use .env or docker-compose environment variables to set the settings (see .env.example for reference).

What is ORIGIN ?

ORIGIN is the URL of the frontend on which you will access it from anywhere. If you are hosting Riven on a vps with IP address 123.45.67.890 then you will need to set the ORIGIN to http://123.45.67.890:3000 (no trailing slash). Similarly, if using a domain name, you will need to set the ORIGIN to http://riven.example.com:3000 (no trailing slash). If you change the port in the docker-compose.yml file, you will need to change it in the ORIGIN as well.

Running outside of Docker

To run outside of docker you will need to have node (v18.13+) and python (3.10+) installed. Then clone the repository

git clone https://github.com/rivenmedia/riven.git && cd riven

and open two terminals in the root of the project and run the following commands in each.

First terminal:

cd frontend
npm install
npm run build
ORIGIN=http://localhost:3000 BACKEND_URL=http://127.0.0.1 node build

Read above for more info on ORIGIN.

Second terminal:

pip install poetry
poetry install --without dev
poetry run python backend/main.py

Symlinking settings

rclone_path should point to your rclone mount that has your torrents on your host.

library_path should point to the location of the mount in plex container

    "symlink": {
        "rclone_path": "/mnt/zurg",
        "library_path": "/mnt/library"
    }

Plex libraries that are currently required to have sections:

[!NOTE] Currently, these Plex library requirements are mandatory. However, we plan to make them customizable in the future to support additional libraries as per user preferences.

Development

Welcome to the development section! Here, you'll find all the necessary steps to set up your development environment and start contributing to the project.

Prerequisites

Ensure you have the following installed on your system:

• Node.js (v18.13+)
• Python (3.10+)
• Poetry (for Python dependency management)
• Docker (optional, for containerized development)

Initial Setup

1. Clone the Repository:

   git clone https://github.com/rivenmedia/riven.git && cd riven

2. Install Backend Dependencies:

   pip install poetry
   poetry install

3. Install Frontend Dependencies:

   cd frontend
   npm install
   cd ..

Using make for Development

We provide a Makefile to simplify common development tasks. Here are some useful commands:

• Initialize the Project:

  make

• Start the Development Environment: This command stops any previous containers, removes old images, and rebuilds the image using cached layers. Any changes in the code will trigger a rebuild.

  make start

• Restart the Container:

  make restart

• View Logs:

  make logs

Development without make

If you prefer not to use make and Docker, you can manually set up the development environment with the following steps:

1. Start the Backend:

   poetry run python backend/main.py

2. Start the Frontend:

   cd frontend
   npm run dev

Additional Tips

• Environment Variables: Ensure you set the ORIGIN environment variable to the URL where the frontend will be accessible. For example:

  export ORIGIN=http://localhost:3000

• Code Formatting: We use Black for Python and Prettier for JavaScript. Make sure to format your code before submitting any changes.

• Running Tests:

  poetry run pytest

By following these guidelines, you'll be able to set up your development environment smoothly and start contributing to the project. Happy coding!

Contributing

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

Submitting Changes

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.

Code Formatting

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

Dependency Management

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

Setting Up Your Environment

1. Install Poetry: If you haven't already, install Poetry using pip install poetry.
2. Install Dependencies: After cloning the repository, navigate to the project's root directory and run poetry install. This command installs all necessary dependencies as defined in the pyproject.toml file and creates an isolated virtual environment.
3. Activate Virtual Environment: You can activate the virtual environment using poetry shell or run commands directly using poetry run <command>.

Adding or Updating Dependencies

• 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.

Running Tests and Linters

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

License

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