diff --git a/README.md b/README.md index 74ba5e72..18f3d361 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,6 @@ # Torrust Tracker -[![container_wf_b]][container_wf] [![coverage_wf_b]][coverage_wf] [![deployment_wf_b]][deployment_wf] [![testing_wf_b]][testing_wf] - -__Torrust Tracker__, is a [BitTorrent][bittorrent] Tracker that matchmakes peers and collects statistics. Written in [Rust Language][rust] with the [axum] web framework. ___This tracker aims to be respectful to established standards, (both [formal][BEP 00] and [otherwise][torrent_source_felid]).___ +[![container_wf_b]][container_wf] [![coverage_wf_b]][coverage_wf] [![deployment_wf_b]][deployment_wf] [![testing_wf_b]][testing_wf]**Torrust Tracker** is a [BitTorrent][bittorrent] Tracker that matchmakes peers and collects statistics. Written in [Rust Language][rust] with the [Axum] web framework. _**This tracker aims to be respectful to established standards, (both [formal][BEP 00] and [otherwise][torrent_source_felid]).___ > This is a [Torrust][torrust] project and is in active development. It is community supported as well as sponsored by [Nautilus Cyberneering][nautilus]. @@ -20,14 +18,15 @@ __Torrust Tracker__, is a [BitTorrent][bittorrent] Tracker that matchmakes peers - [x] Persistent `SQLite3` or `MySQL` Databases. ## Implemented BitTorrent Enhancement Proposals (BEPs) +> > _[Learn more about BitTorrent Enhancement Proposals][BEP 00]_ -- [BEP 03] : The BitTorrent Protocol. -- [BEP 07] : IPv6 Support. -- [BEP 15] : UDP Tracker Protocol for BitTorrent. -- [BEP 23] : Tracker Returns Compact Peer Lists. -- [BEP 27] : Private Torrents. -- [BEP 48] : Tracker Protocol Extension: Scrape. +- [BEP 03]: The BitTorrent Protocol. +- [BEP 07]: IPv6 Support. +- [BEP 15]: UDP Tracker Protocol for BitTorrent. +- [BEP 23]: Tracker Returns Compact Peer Lists. +- [BEP 27]: Private Torrents. +- [BEP 48]: Tracker Protocol Extension: Scrape. ## Getting Started @@ -35,26 +34,28 @@ __Torrust Tracker__, is a [BitTorrent][bittorrent] Tracker that matchmakes peers The Torrust Tracker is [deployed to DockerHub][dockerhub], you can run a demo immediately with the following commands: -#### Docker: +#### Docker ```sh docker run -it torrust/tracker:develop ``` + > Please read our [container guide][containers.md] for more information. -#### Podman: +#### Podman ```sh podman run -it docker.io/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.___ +- Please ensure you have the _**[latest stable (or nightly) version of rust][rust]___. +- Please ensure that your computer has enough RAM. _**Recommended 16GB.___ -#### Checkout, Test and Run: +#### Checkout, Test and Run ```sh # Checkout repository into a new folder: @@ -71,7 +72,8 @@ cargo test --tests --benches --examples --workspace --all-targets --all-features # Run the tracker: cargo run ``` -#### Customization: + +#### Customization ```sh # Copy the default configuration into the standard location: @@ -92,7 +94,7 @@ _Optionally, you may choose to supply the entire configuration as an environment 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:_ +_For deployment, you **should** override the `api_admin_token` by using an environmental variable:_ ```sh # Generate a Secret Token: @@ -105,9 +107,10 @@ TORRUST_TRACKER_CONFIG=$(cat "./storage/tracker/etc/tracker.toml") \ cargo run ``` -> Please view our [crate documentation][documentation] for more detailed instructions. +> Please view our [crate documentation][docs] for more detailed instructions. ### Services + The following services are provided by the default configuration: - UDP _(tracker)_ @@ -119,19 +122,20 @@ The following services are provided by the default configuration: ## Documentation -- [Management API (Version 1)][api] -- [Tracker (HTTP/TLS)][http] -- [Tracker (UDP)][udp] +- [Management API (Version 1)][API] +- [Tracker (HTTP/TLS)][HTTP] +- [Tracker (UDP)][UDP] ## Contributing + We are happy to support and welcome new people to our project. Please consider our [contributor guide][guide.md].
-This is an open-source community supported project. We welcome contributions from the community! +This is an open-source community-supported project. We welcome contributions from the community! -__How can you contribute?__ +**How can you contribute?** - Bug reports and feature requests. - Code contributions. You can start by looking at the issues labeled "[good first issues]". -- Documentation improvements. Check the [documentation][docs] and [API documentation][api] for typos, errors, or missing information. +- Documentation improvements. Check the [documentation][docs] and [API documentation][API] for typos, errors, or missing information. - Participation in the community. You can help by answering questions in the [discussions]. ## License @@ -151,11 +155,13 @@ Some files include explicit copyright notices and/or license notices. For prosperity, versions of Torrust Tracker that are older than five years are automatically granted the [MIT-0][MIT_0] license in addition to the existing [AGPL-3.0-only][AGPL_3_0] license. ## Contributor Agreement + The copyright of the Torrust Tracker is retained by the respective authors. **Contributors agree:** -- That all their contributions be granted a license(s) **compatible** with the [Torrust Trackers License](#License). -- That all contributors signal **clearly** and **explicitly** any other compilable licenses if they are not: *[AGPL-3.0-only with the legacy MIT-0 exception](#License)*. + +- That all their contributions be granted a license(s) **compatible** with the [Torrust Trackers License](#license). +- That all contributors signal **clearly** and **explicitly** any other compilable licenses if they are not: _[AGPL-3.0-only with the legacy MIT-0 exception](#license)_. **The Torrust-Tracker project has no copyright assignment agreement.** @@ -165,8 +171,6 @@ _We kindly ask you to take time and consider The Torrust Project [Contributor Ag This project was a joint effort by [Nautilus Cyberneering GmbH][nautilus] and [Dutch Bits]. Also thanks to [Naim A.] and [greatest-ape] for some parts of the code. Further added features and functions thanks to [Power2All]. - - [container_wf]: ../../actions/workflows/container.yaml [container_wf_b]: ../../actions/workflows/container.yaml/badge.svg [coverage_wf]: ../../actions/workflows/coverage.yaml diff --git a/docs/containers.md b/docs/containers.md index 2526b880..6622e29b 100644 --- a/docs/containers.md +++ b/docs/containers.md @@ -1,10 +1,10 @@ # Containers (Docker or Podman) ## Demo environment + It is simple to setup the tracker with the default configuration and run it using the pre-built public docker image: - With Docker: ```sh @@ -17,11 +17,12 @@ or with Podman: podman run -it docker.io/torrust/tracker:latest ``` - ## Requirements + - Tested with recent versions of Docker or Podman. ## Volumes + The [Containerfile](../Containerfile) (i.e. the Dockerfile) Defines Three Volumes: ```Dockerfile @@ -38,7 +39,8 @@ When instancing the container image with the `docker run` or `podman run` comman > NOTE: You can adjust this mapping for your preference, however this mapping is the default in our guides and scripts. -### Pre-Create Host-Mapped Folders: +### Pre-Create Host-Mapped Folders + Please run this command where you wish to run the container: ```sh @@ -46,11 +48,13 @@ mkdir -p ./storage/tracker/lib/ ./storage/tracker/log/ ./storage/tracker/etc/ ``` ### Matching Ownership ID's of Host Storage and Container Volumes + It is important that the `torrust` user has the same uid `$(id -u)` as the host mapped folders. In our [entry script](../share/container/entry_script_sh), installed to `/usr/local/bin/entry.sh` inside the container, switches to the `torrust` user created based upon the `USER_UID` environmental variable. When running the container, you may use the `--env USER_ID="$(id -u)"` argument that gets the current user-id and passes to the container. ### Mapped Tree Structure + Using the standard mapping defined above produces this following mapped tree: ```s @@ -78,6 +82,7 @@ git clone https://github.com/torrust/torrust-tracker.git; cd torrust-tracker ``` ### (Docker) Setup Context + Before starting, if you are using docker, it is helpful to reset the context to the default: ```sh @@ -107,6 +112,7 @@ podman build --target debug --tag torrust-tracker:debug --file Containerfile . ## Running the Container ### Basic Run + No arguments are needed for simply checking the container image works: #### (Docker) Run Basic @@ -118,6 +124,7 @@ docker run -it torrust-tracker:release # Debug Mode docker run -it torrust-tracker:debug ``` + #### (Podman) Run Basic ```sh @@ -129,11 +136,13 @@ podman run -it docker.io/torrust-tracker:debug ``` ### Arguments + The arguments need to be placed before the image tag. i.e. `run [arguments] torrust-tracker:release` -#### Environmental Variables: +#### Environmental Variables + Environmental variables are loaded through the `--env`, in the format `--env VAR="value"`. The following environmental variables can be set: @@ -148,8 +157,8 @@ The following environmental variables can be set: - `API_PORT` - The port for the tracker API. This should match the port used in the configuration, (default `1212`). - `HEALTH_CHECK_API_PORT` - The port for the Health Check API. This should match the port used in the configuration, (default `1313`). - ### Sockets + Socket ports used internally within the container can be mapped to with the `--publish` argument. The format is: `--publish [optional_host_ip]:[host_port]:[container_port]/[optional_protocol]`, for example: `--publish 127.0.0.1:8080:80/tcp`. @@ -164,7 +173,8 @@ The default ports can be mapped with the following: > NOTE: Inside the container it is necessary to expose a socket with the wildcard address `0.0.0.0` so that it may be accessible from the host. Verify that the configuration that the sockets are wildcard. -### Volumes +### Host-mapped Volumes + By default the container will use install volumes for `/var/lib/torrust/tracker`, `/var/log/torrust/tracker`, and `/etc/torrust/tracker`, however for better administration it good to make these volumes host-mapped. The argument to host-map volumes is `--volume`, with the format: `--volume=[host-src:]container-dest[:]`. @@ -177,10 +187,9 @@ The default mapping can be supplied with the following arguments: --volume ./storage/tracker/etc:/etc/torrust/tracker:Z \ ``` - Please not the `:Z` at the end of the podman `--volume` mapping arguments, this is to give read-write permission on SELinux enabled systemd, if this doesn't work on your system, you can use `:rw` instead. -## Complete Example: +## Complete Example ### With Docker @@ -257,7 +266,7 @@ $ docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 06feacb91a9e torrust-tracker "cargo run" 18 minutes ago Up 4 seconds 0.0.0.0:1212->1212/tcp, :::1212->1212/tcp, 0.0.0.0:7070->7070/tcp, :::7070->7070/tcp, 0.0.0.0:6969->6969/udp, :::6969->6969/udp torrust-tracker-1 34d29e792ee2 mysql:8.0 "docker-entrypoint.s…" 18 minutes ago Up 5 seconds (healthy) 0.0.0.0:3306->3306/tcp, :::3306->3306/tcp, 33060/tcp torrust-mysql-1 -``` +``` And you should be able to use the application, for example making a request to the API: