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, you must regenerate the typescript interfaces with this command (from the frontend directory, while the backend is running):

npx openapi-typescript http://127.0.0.1:8080/swagger-json/openapi.json -o ./src/api-schema/schema.d.ts

Running Arcadia

There are two main ways to run Arcadia:

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.

Environment Configuration

Before running Arcadia, you'll need to configure environment variables. Both backend and frontend require their own .env files.

Both backend and frontend directories include .env.example files that you can copy:

# Backend
cd backend
cp .env.example .env
# Edit .env with your configuration

# Frontend
cd frontend
cp .env.example .env
# Edit .env with your configuration

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
• 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. Configure and run the backend
4. Configure and run the frontend

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 backend directory
cd backend

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

Backend Setup

1. Environment Configuration

Navigate to the frontend directory and configure it:

cd backend
cp .env.example .env

Edit the .env file with your database configuration.

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

1. Environment Configuration

Navigate to the frontend directory and configure it:

cd frontend
cp .env.example .env

Edit the .env file to point to your backend.

2. 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).

Production Build

For production deployment:

Backend

cd backend
cargo build --release
# The binary will be in target/release/arcadia-backend

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_URL in .env is correct

Build Issues

Backend 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 won't start:

• Check the database connection
• Verify environment variables in .env
• Ensure migrations have been run

Frontend can't connect to backend:

• Verify the backend is running on the correct port
• Check VITE_API_URL in frontend/.env

Stopping Arcadia

To stop Arcadia:

1. Stop the frontend with Ctrl+C in its terminal
2. Stop the backend with Ctrl+C in its terminal
3. 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

1. Set up environment files:

   # Copy backend environment file
   cp backend/.env.docker backend/.env
   
   # Copy frontend environment file
   cp frontend/.env.docker frontend/.env
   

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

3. Access the application:

   • Frontend: http://localhost:5137
   • Backend API: http://localhost:8080

Individual Service Management

If you prefer to start services individually:

Database Only

docker compose up db -d

Backend 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/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 > backend/migrations/fixtures/fixtures.sql

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
cargo sqlx database setup

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

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.

Environment Setup

Backend

At runtime, Arcadia's backend will source environment variables to influence it's behavior. The simplest way to set these during development is to write them into a file named .env. A documented sample file is made available, so a quick way to get started is to use it by running cp .env.example .env.

Frontend

At build time, the frontend will be hardcoded with the site's API location sourced from an enviroment variable. A documented sample file is made available, so a quick way to get started is to use it by running cp .env.example .env.

Building and Running

Backend

# Build the backend
cargo build

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

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

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
cargo run

# Build and test
cargo build
cargo test

# Code quality checks
cargo clippy
cargo fmt

Frontend Development

# Development server with hot reload
npm run dev

# Run tests
npm run test:unit

# Lint and format
npm run lint
npm run format

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)
• Environment configuration files (.env files)
• 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. Environment variables from .env files:
   • Docker mode: backend/.env.docker → backend/.env
   • Local mode: backend/.env
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 Files

• backend/.env → backend.env
• frontend/.env → frontend.env

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
├── backend.env
├── frontend.env
└── 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".

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 before committing your changes. 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.