Introduction

Arcadia is a comprehensive torrent platform designed to be:

• Easy to setup - Get running quickly with minimal configuration
• Highly configurable - Customize the platform to your needs
• Content agnostic - Support for movies, TV shows, music, books, software, and more
• Well organized - Clean, intuitive interface for both users and administrators

The backend is built with Rust for speed and safety. The frontend is built with Typescript and VueJS, rendered client-side.

What Arcadia Supports

Arcadia supports a wide variety of content types including:

Movies

• Feature Film: Full-length films with rich metadata support.
• Short Film: Shorter cinematic works.

Movie entry

TV Shows

• Series and seasons with episode tracking capabilities.

TV Show - Season entry

TV Show - Series view

Music

• Album: Includes “live album” as an “edition.”
• EP: Extended plays.
• Single: Individual tracks.
• Soundtrack: Music from movies, TV shows, or games.
• Anthology: Collections of works by an artist or group.
• Compilation: Curated collections of tracks.
• Remix: Reimagined versions of original tracks.
• Bootleg: Unofficial recordings.
• Mixtape: Curated playlists or unofficial releases.
• Concert Recording: Live performance recordings.
• DJ Mix: Continuous mixes by DJs.

Music

Software

• Game: Video games of all genres.
• Program: Applications and utilities.

Software - Game

Written Documents

• Book: Includes hardcover, paperback, and digital formats.
• Illustrated: Includes mangas, comics, and visual novels.
• Periodical: Newspapers, magazines, and journals.
• Article: Studies, theses, essays, and research papers.
• Manual: Guides, music sheets, and instructional documents.

Book - Entry view

Book - Illustrated

Book - Series view

Collections

Collections represent a “grouping” of content to avoid multiple uploads and reduce tracker load. Examples include site dumps, full/finished series, and monthly/yearly content groupings.

Podcast collection

Community

For contributions see CONTRIBUTING.md

Join our community:

• Discord: Join our server

Architecture

Overview

Arcadia is made of 2 main parts: the site’s API and a tracker. The site’s API is meant to be used by the frontend, while the tracker is meant to be used by torrent clients (qbittorrent, deluge, etc.).

Backend

Arcadia’s backend is a REST API written in rust with the actix framework and the sqlx database driver. It also uses PostgreSQL as its database.

Code Structure

API calls are forwarded to handlers, database requests are done by repositories, objects are defined by models. Directories with those names contain the relevant code.

A swagger for the API is available at http://localhost:8080/swagger-ui/

Frontend

Arcadia’s frontend is a SPA written in TypeScript and uses the Vue.js framework with PrimeVue components, Vite builds it.

API Schema Updates

If you make changes to structs that are listed in the swagger or the api routes, you must regenerate the typescript interfaces with this command (from the frontend directory, while the backend is running):

npx openapi-generator-cli generate -g typescript-axios -i http://127.0.0.1:8080/swagger-json/openapi.json   -o ./src/services/api-schema -t .openapi-generator/templates --config .openapi-generator/openapi-generator.config.json --global-property=apiDocs=false,modelDocs=false,skipFormModel=false

Running Arcadia

There are two main ways to run Arcadia:

Configuration

The whole project is configured by a single config.yml file at the root of the repository: backend, tracker, periodic tasks and frontend all read it. It is git ignored.

cp config.example.yml config.yml

Then edit config.yml with the values you want. config.example.yml is the reference: it documents every key, and the ones that differ under Docker carry a docker: note giving the value to use.

Other Customization

A few things need to be setup outside of config.yml.

Landing page

Arcadia allows you to display a custom landing page for not logged in users. If frontend.enable_custom_front_page is set to true in config.yml, the file public/home/index.html will be served when visiting root url.

Assets

A few assets need to be setup.

• frontend/src/assets/logo.svg: The logo of the site (displayed on the top left corner of the UI)
• frontend/public/favicon.ico: The favicon for the website
• frontend/public/default_user_avatar.png: The default avatar for users who didn’t set one
• frontend/public/bonus_points_icon.png: The icon for bonus points

additional config files

Some of the services used with Arcadia need their own config files. kiwiirc and ergo are not required to run the rest of Arcadia

cp kiwiirc/config.json.example kiwiirc/config.json
cp ergo/ergo.motd.example ergo/ergo.motd
cp ergo/ergo-conf.yaml.example ergo/ergo-conf.yaml

The API tokens declared in ergo/ergo-conf.yaml must match the ones of the ergo section of config.yml.

Setup Methods

Standard Setup

Install dependencies directly on your system. See Standard Setup for detailed instructions.

Docker Setup

Use containerized deployment with Docker Compose. See Docker Setup for detailed instructions.

Standard Setup

This page explains how to install and run Arcadia directly on your system without Docker containers.

Prerequisites

Before starting, ensure you have the following installed:

• PostgreSQL - Database server
• Redis - Cache for the auth
• Rust & Cargo - Required to build the backend
• Node.js & npm - Required to build the frontend
• Git - To clone the repository

For development tool installation instructions, see the Developer Setup guide.

Quick Start

1. Clone the repository and navigate to it
2. Set up PostgreSQL database
3. Set up Redis
4. Configure and run the backend
5. Configure and run the frontend
6. Configure and run the tracker

Database Setup

1. Install PostgreSQL

Install PostgreSQL on your system:

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install postgresql postgresql-contrib

macOS:

brew install postgresql
brew services start postgresql

Windows: Download and install from PostgreSQL official website.

2. Create Database and User

Connect to PostgreSQL and create the database:

# Connect as postgres user
sudo -u postgres psql

# Or on Windows/macOS:
psql -U postgres

In the PostgreSQL shell:

-- Create user
CREATE USER arcadia WITH PASSWORD 'your_secure_password';

-- Create database
CREATE DATABASE arcadia OWNER arcadia;

-- Grant privileges
GRANT ALL PRIVILEGES ON DATABASE arcadia TO arcadia;

-- Exit
\q

3. Run Database Migrations

Install the database migration tool and run migrations:

# Install sqlx-cli
cargo install sqlx-cli --no-default-features --features native-tls,postgres

# Navigate to storage directory
cd backend/storage

# Run migrations
sqlx migrate run --database-url postgresql://arcadia:your_secure_password@localhost:5432/arcadia

sqlx-cli only reads --database-url or DATABASE_URL, it does not know about config.yml. Use the credentials of its database section.

NOTE: if you get "Could not find directory of OpenSSL installation" error install

# Install openssl Ubuntu/Debian
sudo apt install pkg-config libssl-dev

# MacOS
brew install openssl@1.1

# Fedora
dnf install pkg-config openssl-devel

Redis setup

Official docs

Backend Setup

Build and Run

Build and start the backend server:

cargo run --release

If you encounter build errors, install the required system dependencies:

Ubuntu/Debian:

sudo apt-get install libssl-dev openssl pkg-config

macOS:

xcode-select --install

Windows: Ensure you have Visual Studio Build Tools installed.

The backend will start and be accessible at http://localhost:8080.

Frontend Setup

Build and Run

Install dependencies and start the frontend:

npm install
npm run dev

The frontend will be accessible at http://localhost:5173 (or the port shown in the terminal).

Tracker Setup

Build and Run

Build and start the tracker server:

cargo run --release

Production Build

For production deployment:

Backend API

cd backend/api
cargo build --release

# Or from the root directory
cargo build -p arcadia-api --release

# The binary will be in target/release/arcadia-api

Tracker

cd tracker/arcadia_tracker
cargo build --release

Frontend

cd frontend
npm run build
# Built files will be in the dist/ directory

Troubleshooting

Database Issues

PostgreSQL not running:

# Ubuntu/Debian
sudo systemctl start postgresql
sudo systemctl enable postgresql

# macOS
brew services start postgresql

Connection errors:

• Verify PostgreSQL is running on port 5432
• Check that the database and user exist
• Ensure the database section of config.yml is correct

Build Issues

Backend API build fails:

• Install system dependencies listed above
• Update Rust: rustup update
• Clear build cache: cargo clean

Frontend build fails:

• Check Node.js version compatibility
• Clear npm cache: npm cache clean --force
• Delete node_modules and run npm install again

Runtime Issues

Backend API won’t start:

• Check the database connection
• Verify the values in config.yml
• Ensure migrations have been run

Frontend can’t connect to backend API:

• Verify the backend is running on the correct port
• Check frontend.api_base_url in config.yml, and restart the frontend: the section is inlined in the bundle at build time

Stopping Arcadia

To stop Arcadia:

1. Stop the frontend with Ctrl+C in its terminal
2. Stop the tracker with Ctrl+C in its terminal and wait for its graceful shutdown
3. Stop the backend API with Ctrl+C in its terminal
4. Optionally stop PostgreSQL if you don’t need it for other applications

Docker Setup

This guide will help you get Arcadia running quickly using Docker Compose.

Prerequisites

• Docker and Docker Compose installed
• Git (to clone the repository)

Quick Setup

0. Configuration:

   cp config.example.yml config.yml
   

1. Start all services:

   docker compose up -d
   

   This command will:

   • Build the backend and frontend images
   • Start PostgreSQL database
   • Run database migrations automatically
   • Start the backend API server
   • Start the frontend development server

2. Access the application:

   • Frontend: http://localhost:5173
   • Backend API: http://localhost:8080/api/

The backend and the tracker are built without optimizations, which keeps the builds short. Pass --build-arg PRODUCTION_BUILD=true to build them in release mode.

Individual Service Management

If you prefer to start services individually:

Database Only

docker compose up db -d

Redis Only

docker compose up redis -d

Backend Api Only

docker compose up backend -d

Frontend Only

docker compose up frontend -d

Development Features

Auto-rebuild with Compose Watch

For development, you can use Compose Watch to automatically rebuild when source code changes:

docker compose up --watch

Or when running attached (without -d), press W to enable watch mode.

Adding Test Data

You can optionally add “fake” data (fixtures) to the database for development:

docker exec -i arcadia_db psql -U arcadia -d arcadia < backend/storage/migrations/fixtures/fixtures.sql

The default test user is picolo with password test.

Exporting Test Data

If you added some new test data and wish to include it in your commit, you can export it like so:

docker exec -i arcadia_db pg_dump -U arcadia -d arcadia --data-only --inserts --column-inserts > backend/storage/migrations/fixtures/fixtures.sql && sed -i '/SELECT pg_catalog.set_config(\x27search_path\x27, \x27\x27, false);/d' migrations/fixtures/fixtures.sql

1 line generated by pgdump must be removed as it prevents the collage_entry fixtures from being inserted (the trigger somehow can’t be interprted). If someone has an explanation, please let us know/open a PR!

Manual Database Setup (if needed)

Arcadia automatically runs migrations on launch, but if you need to manually set up the database:

cargo install sqlx-cli
DATABASE_URL=postgresql://arcadia:password@localhost:4321/arcadia cargo sqlx database setup

sqlx-cli only reads DATABASE_URL, it does not know about config.yml. Use the credentials of the database section, with the port published on the host (4321 by default).

Troubleshooting

• If services fail to start, check logs with: docker compose logs [service-name]
• To rebuild images: docker compose build
• To reset everything: docker compose down -v && docker compose up -d

Developer Setup

Development Containers (Optional)

You can also use GitHub Codespaces to build Arcadia in the cloud without having to download anything but streams of text, although it’s not as free as a local dev container.

It isn’t required to use them but can be useful in some cases (especially if you’re using an immutable OS).

Required Tools

You need these to make meaningful contributions to Arcadia, outside the cases of documentation for example.

• Node.js & npm
• Cargo (version 1.88.0 and higher)

Recommended Tools

• Prettier for proper formatting of the frontend’s code.
• sqlx-cli for managing database related stuff, including migrations.
• Docker for setting up dependencies. Optional but HIGHLY recommended!
• Insomnia for testing the backend’s API. You could also use any other client if you want.

Configuration Setup

Everything is configured by a single config.yml at the root of the repository. A quick way to get started is cp config.example.yml config.yml: that sample documents every key and is the reference for what each one does.

The one environment variable left: DATABASE_URL

The sqlx query macros check the queries against a real database at compile time, and sqlx only reads DATABASE_URL. It is needed for cargo build, cargo clippy and cargo sqlx prepare, never by the running services. Write it in a .env file at the root of the repository (git ignored), it is picked up from every crate directory:

echo 'DATABASE_URL=postgresql://arcadia:password@localhost:4321/arcadia' > .env

Docker builds don’t need it, they build with SQLX_OFFLINE=true against the committed .sqlx caches.

Building and Running

API

# Build the backend
cargo build -p arcadia-api

# Run the backend binary
./target/debug/arcadia-api

# For optimized builds
cargo build -p arcadia-api --release
./target/release/arcadia-api

Frontend

# Install dependencies
npm install

# Build and run development server
npm run dev

# For production build
npm run build

Development Workflow

Backend Development

# For development with auto-rebuild on changes
cd backend/api
cargo run

# Build and test
cargo build -p arcadia-api
cargo test

# Code quality checks
cargo clippy --fix --allow-dirty
cargo fmt --all

Frontend Development

cd frontend

# Development server with hot reload
npm run dev

# Run tests
npm run test:unit

# Lint and format
npm run lint
npm run format

Plugins

Plugins let an instance add custom behaviour without forking arcadia and without merging anything upstream. A plugin is a separate service that arcadia calls over HTTP, so it can be written in any language and deployed independently.

For now, plugins can add external sources (scrapers), like the built in TMDB, MusicBrainz, ISBN and Comic Vine ones.

Configuration

Declare your plugins in the scrapers section of config.yml, at the root of the repository:

scrapers:
  - id: anidb
    label: AniDB
    placeholder: AniDB url
    content_types:
      - tv_show
    url: http://anidb-plugin:9000/scrape
    timeout_seconds: 30

config.yml is read once at startup. When the scrapers section is absent, no plugin is registered.

Both config.yml and compose.override.yml are git ignored. compose.yml already mounts config.yml into the backend container, so only the plugin services themselves have to be declared in compose.override.yml, which Docker Compose loads automatically on top of compose.yml:

services:
  anidb-plugin:
    build: ../anidb-plugin
    restart: unless-stopped

Writing a scraper plugin

The declared endpoint is called with the identifier the user typed as the url query parameter:

GET http://anidb-plugin:9000/scrape?url=https://anidb.net/anime/1234

It must answer with JSON:

{
  "title_group": { "name": "...", "description": "...", "content_type": "tv_show", "...": "..." },
  "edition_group": null,
  "affiliated_artists": [
    {
      "name": "Some Person",
      "aliases": [],
      "description": "",
      "pictures": ["https://example.com/picture.jpg"],
      "roles": ["director"],
      "nickname": null
    }
  ]
}

title_group follows the UserCreatedTitleGroup schema and edition_group the UserCreatedEditionGroup one; both are documented in the OpenAPI specification. All three fields are optional.

Artists are given by name: arcadia creates them, merges the roles of an artist appearing several times, and returns real affiliated artists to the interface. Arcadia also checks beforehand whether a title group already has the submitted link, and appends that link to the scraped title group.

Pictures are rehosted if image rehosting is enabled.

Anything else the plugin needs (API keys, caching, rate limiting) is its own business.

Backup

This page explains how to create backups of your Arcadia installation, including the database and configuration files.

For all the possible flags and operations, check the --help flag:

./backup.sh --help

Overview

The backup process includes:

• Complete database dump (schema + data)
• The configuration file (config.yml)
• Backup metadata and timestamps

Prerequisites

• zip utility installed on your system
• For local setup: PostgreSQL client tools (pg_dump)

Quick Backup

For Docker setup:

./backup.sh --db-docker

For local/standard setup:

./backup.sh

Backup Script Options

The backup script supports both Docker and local PostgreSQL setups with various configuration options.

Docker Mode

Use --db-docker flag to backup from a containerized database:

# Default Docker backup
./backup.sh --db-docker

# Custom container name
./backup.sh --db-docker --db-container my_custom_db

Docker mode options:

• --db-container: Docker container name (default: arcadia_db)

Local Mode

For standard installations with local PostgreSQL:

# Default local backup
./backup.sh

# Remote database
./backup.sh --db-host db.example.com --db-user myuser

# With password
./backup.sh --db-password mypassword

Local mode options:

• --db-host: Database host (default: localhost)
• --db-port: Database port (default: 5432)
• --db-name: Database name (default: arcadia)
• --db-user: Database user (default: arcadia)
• --db-password: Database password (optional)

Configuration Priority

The script loads configuration in this order (highest to lowest priority):

1. Command line arguments - Override everything
2. The database section of config.yml at the root of the repository
3. Built-in defaults

What Gets Backed Up

Database

• Complete PostgreSQL dump using pg_dump
• Includes all schema and data
• Uses --no-owner --no-privileges for portability

Configuration File

• config.yml (the whole project’s configuration)

Metadata

• Backup timestamp
• Database information
• Setup type (Docker/Local)
• Backup configuration details

Backup Output

The script creates:

• Temporary backup directory: backup_YYYYMMDD_HHMMSS/
• Final zip archive: arcadia_backup_YYYYMMDD_HHMMSS.zip

Example backup contents:

arcadia_backup_20241201_143022.zip
├── database_full.sql
├── config.yml
└── backup_info.txt

Testing

Backend Testing

Adding additional tests to Arcadia is strongly encouraged, especially when adding new features! For unit tests, they can be added in the module being tested using standard rust idioms.

End-to-end tests can also be authored, they should be located in tests/ and use the sqlx test fixture machinery to populate the database for testing. See tests/test_auth.rs for examples.

Frontend Testing

We don’t have any tests for the frontend. We’ll add them once it’s more “production ready”.

Maintenance

A few tools are available in the Staff Dashboard on the frontend (once the user is granted the user_maintenance_tools permission). You might make use of them in such situations:

• updated the source flag for .torrent files
• manual changes in the db that caused a drift in cached counts (amount of title groups for a given artist for example)

Contributing

First, thanks for considering contributing to Arcadia!

Contributing Process

Whether you want to add a new feature or fix an existing issue, it needs to be done on your own branch:

1. Fork this repository
2. Clone it locally on your computer
3. create a new branch feature-name or bug-name-fix (with the proper name)
4. open a pull request when your contribution is done

If you are unsure about what/how to do something, don’t hesitate to open a discussion or an issue about the topic.

You can also hop on the Discord server to chat with other devs and the community.

Finding Contributions to Make

Arcadia has boards to track the existing issues and features that need to be worked on. Feel free to claim one that isn’t claimed yet before starting to work on it.

To claim a github issue, simply leave a comment on it saying that you are working on it.

You can also search for TODOs in the code and pick one of those tasks. If you decide to do this, please open an issue first and claim it before working on the task.

Backend Development Notes

• If you make changes to/add sql queries with sqlx, you need to run cargo sqlx prepare inside the backend/storage folder before committing your changes. It reads the database from the DATABASE_URL environment variable (see Developer Setup), not from config.yml. This command will generate some files that allow the queries to be tested without a database running. Our CI pipeline relies on that, and will fail if the command hasn’t been ran. You can setup a git pre-commit hook if you want.

• For better code quality, we use clippy in our CI pipeline. You can set your editor to run cargo clippy instead of cargo check (on file save, etc.).

Legal Notice

This tool (Arcadia) is intended for legal use only. Users (both the ones hosting Arcadia and the ones using it) are solely responsible for the content they download and share through it. Downloading or distributing copyrighted material without proper authorization is illegal in most jurisdictions. By hosting and/or using Arcadia, you agree to abide by all applicable laws and respect intellectual property rights. The developers of Arcadia assume no responsibility for any illegal activities conducted by its hosters and users.