Skip to content

Commit

Permalink
docs: update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@da2ce7
da2ce7 committed Sep 6, 2023
1 parent 8e40ca5 commit 8230c20
Show file tree
Hide file tree
Showing 2 changed files with 79 additions and 41 deletions.
119 changes: 78 additions & 41 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,13 @@

[![container_wf_b]][container_wf] [![coverage_wf_b]][coverage_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

Expand All @@ -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]
Expand All @@ -101,17 +146,21 @@ 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
[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
Expand All @@ -121,18 +170,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
Expand Down
1 change: 1 addition & 0 deletions cSpell.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,7 @@
"libz",
"LOGNAME",
"Lphant",
"matchmakes",
"metainfo",
"middlewares",
"mockall",
Expand Down

0 comments on commit 8230c20

Please sign in to comment.