Crate torrust_index

Documentation for Torrust Tracker Index API.

This is the index API for Torrust Tracker Index.

It is written in Rust and uses the Axum framework. It is designed to be used with by the Torrust Tracker Index Gui.

If you are looking for information on how to use the API, please see the API v1 section of the documentation.

Table of contents

• Features
• Services
• Installation
  • Minimum requirements
  • Prerequisites
  • Install from sources
  • Run with docker
  • Development
• Configuration
• Usage
  • API
  • Tracker Statistics Importer
  • Upgrader
• Contributing
• Documentation

Features

• Torrent categories
• Image proxy cache for torrent descriptions
• User registration and authentication
• DB Support for SQLite and MySQl

Services

From the end-user perspective the Torrust Tracker exposes three different services.

• A REST API

From the administrator perspective, the Torrust Index exposes:

• A console command to update torrents statistics from the associated tracker
• A console command to upgrade the database schema from version 1.0.0 to 2.0.0

Installation

Minimum requirements

• Rust Stable 1.68

Prerequisites

In order the run the index you will need a running torrust tracker. In the configuration you need to fill the tracker section with the following:

[tracker]
url = "udp://localhost:6969"

api_url = "http://localhost:1212/"
token = "MyAccessToken"
token_valid_seconds = 7257600

Refer to the config::tracker documentation for more information.

You can follow the tracker installation instructions here or you can use the docker to run both the tracker and the index. Refer to the Run with docker section for more information.

You will also need to install this dependency:

sudo apt-get install libssl-dev

We needed because we are using native TLS support instead of rustls.

More info: https://github.com/torrust/torrust-index/issues/463.

If you are using SQLite3 as database driver, you will need to install the following dependency:

sudo apt-get install libsqlite3-dev

NOTICE: those are the commands for Ubuntu. If you are using a different OS, you will need to install the equivalent packages. Please refer to the documentation of your OS.

With the default configuration you will need to create the storage directory:

storage/
└── database
    └── data.db

The default configuration expects a directory ./storage/database to be writable by the app process.

By default the index uses SQLite and the database file name data.db.

Install from sources

git clone git@github.com:torrust/torrust-index.git \
  && cd torrust-index \
  && cargo build --release \
  && mkdir -p ./storage/database

Then you can run it with: ./target/release/torrust-index

Run with docker

You can run the index with a pre-built docker image:

cd /tmp \
  && mkdir torrust-index \
  && cd torrust-index \
  && mkdir -p ./storage/index/lib/database \
  && mkdir -p ./storage/index/log \
  && mkdir -p ./storage/index/etc \
  && sqlite3 "./storage/index/lib/database/sqlite3.db" "VACUUM;" \
  && export USER_ID=1000 \
  && docker run -it \
    --env USER_ID="$USER_ID" \
    --publish 3001:3001/tcp \
    --volume "$(pwd)/storage/index/lib":"/var/lib/torrust/index" \
    --volume "$(pwd)/storage/index/log":"/var/log/torrust/index" \
    --volume "$(pwd)/storage/index/etc":"/etc/torrust/index" \
    torrust/index:develop

For more information about using docker visit the tracker docker documentation.

Development

We are using the The Rust SQL Toolkit (sqlx) for database migrations.

You can install it with:

cargo install sqlx-cli

To initialize the database run:

echo "DATABASE_URL=sqlite://data.db?mode=rwc" > .env
sqlx db setup

The sqlx db setup command will create the database specified in your DATABASE_URL and run any pending migrations.

WARNING: The .env file is also used by docker-compose.

NOTICE: Refer to the sqlx-cli documentation for other commands to create new migrations or run them.

NOTICE: You can run the index with tmux with tmux new -s torrust-index.

Configuration

In order to run the index you need to provide the configuration. If you run the index without providing the configuration, the tracker will generate the default configuration the first time you run it. It will generate a config.toml file with in the root directory.

The default configuration is:

[website]
name = "Torrust"

[tracker]
api_url = "http://localhost:1212/"
listed = false
private = false
token = "MyAccessToken"
token_valid_seconds = 7257600
url = "udp://localhost:6969"

[net]
bind_address = "0.0.0.0:3001"

[auth]
user_claim_token_pepper = "MaxVerstappenWC2021"

[auth.password_constraints]
min_password_length = 6
max_password_length = 64

[database]
connect_url = "sqlite://data.db?mode=rwc"

[mail]
from = "example@email.com"
reply_to = "noreply@email.com"

[mail.smtp]
port = 25
server = ""

[mail.smtp.credentials]
password = ""
username = ""

[image_cache]
max_request_timeout_ms = 1000
capacity = 128000000
entry_size_limit = 4000000
user_quota_period_seconds = 3600
user_quota_bytes = 64000000

[api]
default_torrent_page_size = 10
max_torrent_page_size = 30

[tracker_statistics_importer]
torrent_info_update_interval = 3600
port = 3002

For more information about configuration you can visit the documentation for the config) module.

Alternatively to the config.toml file you can use one environment variable TORRUST_INDEX_CONFIG_TOML to pass the configuration to the tracker:

TORRUST_INDEX_CONFIG_TOML=$(cat config.toml)
cargo run

In the previous example you are just setting the env var with the contents of the config.toml file.

The env var contains the same data as the config.toml. It’s particularly useful in you are running the index with docker.

NOTICE: The TORRUST_INDEX_CONFIG_TOML env var has priority over the config.toml file.

NOTICE: You can also change the location for the configuration file with the TORRUST_INDEX_CONFIG_PATH env var.

Usage

API

Running the index with the default configuration will expose the REST API on port 3001: http://localhost:3001

Tracker Statistics Importer

This console command allows you to manually import the tracker statistics.

For more information about this command you can visit the documentation for the Import tracker statistics module.

Upgrader

This console command allows you to manually upgrade the application from one version to another.

For more information about this command you can visit the documentation for the Upgrade app from version 1.0.0 to 2.0.0 module.

Contributing

If you want to contribute to this documentation you can:

• Open a new discussion
• Open a new issue.
• Open a new pull request.

Documentation

You can find this documentation on docs.rs.

If you want to contribute to this documentation you can open a new pull request.

In addition to the production code documentation you can find a lot of examples in the tests directory.

Modules

app

bootstrap

cache

common

config

Configuration for the application.

console

Console modules.

databases

errors

mailer

models

services

App services.

tracker

ui

User interface module. Presentation layer.

upgrades

utils

web

The Torrust Index API.