From 6b800a6ee54f0b0848086feb01fc12238d5b6e2a Mon Sep 17 00:00:00 2001 From: Cameron Garnham Date: Wed, 6 Sep 2023 21:00:18 +0200 Subject: [PATCH] docs: update readme --- README.md | 123 ++++++++++++++++++++++++++++++++++------------------ cSpell.json | 1 + 2 files changed, 82 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index 832af0d85..97a9312c0 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,14 @@ # Torrust Tracker -[![container_wf_b]][container_wf] [![coverage_wf_b]][coverage_wf] [![testing_wf_b]][testing_wf] +[![container_wf_b]][container_wf] [![coverage_wf_b]][coverage_wf] [![deployment_wf_b]][deployment_wf] [![testing_wf_b]][testing_wf] -Torrust Tracker is a lightweight but incredibly high-performance and feature-rich BitTorrent tracker written in [Rust Language][rust]. +__Torrust Tracker__, is a [BitTorrent] Tracker (a service that matchmakes peers, and collects statistics) written in [Rust Language][rust] and [axum] (a modern web application framework). -It aims to provide a reliable and efficient solution for serving torrents to a vast number of peers while maintaining a high level of performance, robustness, extensibility, security, usability and with community-driven development. +_This project is under active development, and is growing a vibrant community._ -_We have a [container guide][containers.md] to get started with Docker or Podman_ + > This tracker is respectful to established standards (both formal and defacto) and maintains good performance under heavy loads. + +_We have a [container guide][containers.md] to get started with __Docker__ or __Podman___ ## Key Features @@ -33,49 +35,92 @@ _We have a [container guide][containers.md] to get started with Docker or Podman ## Getting Started -Requirements: +### Container Version -* Rust Stable `1.68` -* You might have problems compiling with a machine or docker container with low resources. It has been tested with docker containers with 6 CPUs, 7.5 GM of memory and 2GB of swap. +The Torrust Tracker is [deployed to DockerHub][dockerhub_torrust_tracker], you can run a demo immediately with the following commands: -You can follow the [documentation] to install and use Torrust Tracker in different ways, but if you want to give it a quick try, you can use the following commands: +#### Docker: -```s -git clone https://github.com/torrust/torrust-tracker.git \ - && cd torrust-tracker \ - && cargo build --release \ - && mkdir -p ./storage/tracker/lib/database \ - && mkdir -p ./storage/tracker/lib/tls +```sh +docker run -it torrust/tracker:develop ``` +> Please read our [container guide][containers.md] for more information. + +#### Podman: + +```sh +podman run -it torrust/tracker:develop +``` +> Please read our [container guide][containers.md] for more information. + +### Development Version + +- Please assure you have the ___[latest stable (or nightly) version of rust][rust]___. +- Please assure that you computer has enough ram. ___Recommended 16GB.___ + +#### Checkout, Test and Run: + +```sh +# Checkout repository into a new folder: +git clone https://github.com/torrust/torrust-tracker.git + +# Change into directory and create a empty database file: +cd torrust-tracker +mkdir -p ./storage/tracker/lib/database/ +touch ./storage/tracker/lib/database/sqlite3.db -### Configuration +# Check all tests in application: +cargo test --tests --benches --examples --workspace --all-targets --all-features -The [default configuration folder: `/share/default/config`][share.default.config]: +# Run the tracker: +cargo run +``` +#### Customization: -- Contains the [development default][src.bootstrap.config.default] i.e: [`tracker.development.sqlite3.toml`][tracker.development.sqlite3.toml]. +```sh +# Copy the default configuration into the standard location: +mkdir -p ./storage/tracker/etc/ +cp ./share/default/config/tracker.development.sqlite3.toml ./storage/tracker/etc/tracker.toml -- Also contains the container defaults: [`sqlite3`][tracker.container.sqlite3.toml] and [`mysql`][tracker.container.mysql.toml]. +# Customize the tracker configuration (for example): +vim ./storage/tracker/etc/tracker.toml -To override the default configuration there is two options: +# Run the tracker with the updated configuration: +TORRUST_TRACKER_PATH_CONFIG="./storage/tracker/etc/tracker.toml" cargo run +``` -- Configure a different configuration path by setting the [`TORRUST_TRACKER_PATH_CONFIG`][src.bootstrap.config.path.config] environmental variable. +_Optionally, you may choose to supply the entire configuration as an environmental variable:_ -- Supply the entire configuration via the [`TORRUST_TRACKER_CONFIG`][src.bootstrap.config.config] environmental variable. +```sh +# Use a configuration supplied on an environmental variable: +TORRUST_TRACKER_CONFIG=$(cat "./storage/tracker/etc/tracker.toml") cargo run +``` +_For deployment you __should__ override the `api_admin_token` by using an environmental variable:_ -> NOTE: It is recommended for production you override the `api admin token` by placing your secret in the [`ENV_VAR_API_ADMIN_TOKEN`][src.bootstrap.config.admin.token] environmental variable. +```sh +# Generate a Secret Token: +gpg --armor --gen-random 1 10 | tee ./storage/tracker/lib/tracker_api_admin_token.secret +chmod go-rwx ./storage/tracker/lib/tracker_api_admin_token.secret + +# Override secret in configuration using an environmental variable: +TORRUST_TRACKER_CONFIG=$(cat "./storage/tracker/etc/tracker.toml") \ + TORRUST_TRACKER_API_ADMIN_TOKEN=$(cat "./storage/tracker/lib/tracker_api_admin_token.secret") \ + cargo run +``` +> Please view our [crate documentation][documentation] for more detailed instructions. ### Services -After running the tracker these services will be available (as defined in the default configuration): +The following services are provided by the default configuration: * UDP tracker: `udp://127.0.0.1:6969/announce`. * HTTP tracker: `http://127.0.0.1:6969/announce`. * API: `http://127.0.0.1:1212/api/v1/stats?token=MyAccessToken`. + ## Documentation -* [Crate documentation] * [API `v1`] * [HTTP Tracker] * [UDP Tracker] @@ -101,17 +146,23 @@ This project was a joint effort by [Nautilus Cyberneering GmbH][nautilus] and [D -[container_wf]: https://github.com/torrust/torrust-tracker/actions/workflows/container.yaml -[container_wf_b]: https://github.com/torrust/torrust-tracker/actions/workflows/container.yaml/badge.svg -[coverage_wf]: https://github.com/torrust/torrust-tracker/actions/workflows/coverage.yaml -[coverage_wf_b]: https://github.com/torrust/torrust-tracker/actions/workflows/coverage.yaml/badge.svg -[testing_wf]: https://github.com/torrust/torrust-tracker/actions/workflows/testing.yaml -[testing_wf_b]: https://github.com/torrust/torrust-tracker/actions/workflows/testing.yaml/badge.svg +[container_wf]: ../../actions/workflows/container.yaml +[container_wf_b]: ../../actions/workflows/container.yaml/badge.svg +[coverage_wf]: ../../actions/workflows/coverage.yaml +[coverage_wf_b]: ../../actions/workflows/coverage.yaml/badge.svg +[deployment_wf]: ../../actions/workflows/deployment.yaml +[deployment_wf_b]: ../../actions/workflows/deployment.yaml/badge.svg +[testing_wf]: ../../actions/workflows/testing.yaml +[testing_wf_b]: ../../actions/workflows/testing.yaml/badge.svg +[BitTorrent]: http://bittorrent.org/ [rust]: https://www.rust-lang.org/ +[axum]: https://github.com/tokio-rs/axum [newtrackon]: https://newtrackon.com/ [coverage]: https://app.codecov.io/gh/torrust/torrust-tracker +[dockerhub_torrust_tracker]: https://hub.docker.com/r/torrust/tracker/tags + [BEP 03]: https://www.bittorrent.org/beps/bep_0003.html [BEP 07]: https://www.bittorrent.org/beps/bep_0007.html [BEP 15]: http://www.bittorrent.org/beps/bep_0015.html @@ -121,18 +172,6 @@ This project was a joint effort by [Nautilus Cyberneering GmbH][nautilus] and [D [containers.md]: ./docs/containers.md -[share.default.config]: ./share/default/config/ -[tracker.development.sqlite3.toml]: ./share/default/config/tracker.development.sqlite3.toml -[src.bootstrap.config.default]: ./src/bootstrap/config.rs#L18 -[tracker.container.sqlite3.toml]: ./share/default/config/tracker.container.sqlite3.toml -[tracker.container.mysql.toml]: ./share/default/config/tracker.container.mysql.toml -[share.container.entry_script_sh.default]: ./share/container/entry_script_sh#L10 - -[src.bootstrap.config.path.config]: ./src/bootstrap/config.rs#L15 -[src.bootstrap.config.config]: ./src/bootstrap/config.rs#L11 -[src.bootstrap.config.admin.token]: ./src/bootstrap/config.rs#L12 - -[Crate documentation]: https://docs.rs/torrust-tracker/ [API `v1`]: https://docs.rs/torrust-tracker/3.0.0-alpha.4/torrust_tracker/servers/apis/v1 [HTTP Tracker]: https://docs.rs/torrust-tracker/3.0.0-alpha.4/torrust_tracker/servers/http [UDP Tracker]: https://docs.rs/torrust-tracker/3.0.0-alpha.4/torrust_tracker/servers/udp diff --git a/cSpell.json b/cSpell.json index e4ac1d90b..a02a9b8e8 100644 --- a/cSpell.json +++ b/cSpell.json @@ -63,6 +63,7 @@ "libz", "LOGNAME", "Lphant", + "matchmakes", "metainfo", "middlewares", "mockall",