Skip to content

Commit 28e8ca0

Browse files
da2ce7da2ce7
committed
Merge #402: docs: update readme
e3e111b docs: update readme (Cameron Garnham) Pull request description: Updated and modernized the readme. Now include some basic guide for getting started. ACKs for top commit: da2ce7: ACK e3e111b Tree-SHA512: 039b74b02a68e7a14ee155e99ece3fa5f59d8a87f0702db16f0a5f5fb3b543de69e376210bc6591878d8defd453a4a9e85d3c3f301905ef314218f8c1c69f4b2
2 parents 60447f5 + e3e111b commit 28e8ca0

File tree

2 files changed

+125
-78
lines changed

2 files changed

+125
-78
lines changed

‎README.md‎

Lines changed: 124 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -1,95 +1,143 @@
11
# Torrust Tracker
22

3-
[![container_wf_b]][container_wf] [![coverage_wf_b]][coverage_wf] [![testing_wf_b]][testing_wf]
3+
[![container_wf_b]][container_wf] [![coverage_wf_b]][coverage_wf] [![deployment_wf_b]][deployment_wf] [![testing_wf_b]][testing_wf]
44

5-
Torrust Tracker is a lightweight but incredibly high-performance and feature-rich BitTorrent tracker written in [Rust Language][rust].
5+
__Torrust Tracker__, is a [BitTorrent][bittorrent] Tracker (a service that matchmakes peers and collects statistics) written in [Rust Language][rust] and [axum] (a modern web application framework). ___This tracker aims to be respectful to established standards, (both [formal][BEP 00] and [otherwise][torrent_source_felid]).___
66

7-
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.
7+
> This is a [Torrust][torrust] project and is in active development. It is community supported as well as sponsored by [Nautilus Cyberneering][nautilus].
88
9-
_We have a [container guide][containers.md] to get started with Docker or Podman_
9+
- _We have a [container guide][containers.md] for those who wish to get started with __Docker__ or __Podman___
1010

1111
## Key Features
1212

13-
* [x] Multiple UDP server and HTTP(S) server blocks for socket binding are possible.
14-
* [x] Full IPv4 and IPv6 support for both UDP and HTTP(S).
15-
* [x] Private & Whitelisted mode.
16-
* [x] Built-in API.
17-
* [x] Torrent whitelisting.
18-
* [x] Peer authentication using time-bound keys.
19-
* [x] [newTrackon][newtrackon] check is supported for both HTTP and UDP, where IPv4 and IPv6 are properly handled.
20-
* [x] SQLite3 and MySQL persistence, loading and saving of the torrent hashes and downloads completed count.
21-
* [x] Comprehensive documentation.
22-
* [x] A complete suite of tests. See our [code coverage report][coverage].
13+
- [x] High Quality and Modern Rust Codebase.
14+
- [x] [Documentation] Generated from Code Comments.
15+
- [x] [Comprehensive Suit][coverage] of Unit and Functional Tests.
16+
- [x] Good Performance in Busy Conditions.
17+
- [x] Support for `UDP`, `HTTP`, and `TLS` Sockets.
18+
- [x] Native `IPv4` and `IPv6` support.
19+
- [x] Private & Whitelisted mode.
20+
- [x] Tracker Management API.
21+
- [x] Support [newTrackon][newtrackon] checks.
22+
- [x] Persistent `SQLite3` or `MySQL` Databases.
2323

24-
## Implemented BEPs
24+
## Implemented BitTorrent Enhancement Proposals (BEPs)
25+
> _[Learn more about BitTorrent Enhancement Proposals][BEP 00]_
2526
26-
* [BEP 03]: The BitTorrent Protocol.
27-
* [BEP 07]: IPv6 Support.
28-
* [BEP 15]: UDP Tracker Protocol for BitTorrent.
29-
* [BEP 23]: Tracker Returns Compact Peer Lists.
30-
* [BEP 27]: Private Torrents.
31-
* [BEP 48]: Tracker Protocol Extension: Scrape.
27+
- [BEP 03] : The BitTorrent Protocol.
28+
- [BEP 07] : IPv6 Support.
29+
- [BEP 15] : UDP Tracker Protocol for BitTorrent.
30+
- [BEP 23] : Tracker Returns Compact Peer Lists.
31+
- [BEP 27] : Private Torrents.
32+
- [BEP 48] : Tracker Protocol Extension: Scrape.
3233

3334

3435
## Getting Started
3536

36-
Requirements:
37+
### Container Version
3738

38-
* Rust Stable `1.68`
39-
* 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.
39+
The Torrust Tracker is [deployed to DockerHub][dockerhub_torrust_tracker], you can run a demo immediately with the following commands:
4040

41-
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:
41+
#### Docker:
4242

43-
```s
44-
git clone https://github.com/torrust/torrust-tracker.git \
45-
&& cd torrust-tracker \
46-
&& cargo build --release \
47-
&& mkdir -p ./storage/tracker/lib/database \
48-
&& mkdir -p ./storage/tracker/lib/tls
43+
```sh
44+
docker run -it torrust/tracker:develop
4945
```
46+
> Please read our [container guide][containers.md] for more information.
5047
51-
### Configuration
48+
#### Podman:
5249

53-
The [default configuration folder: `/share/default/config`][share.default.config]:
50+
```sh
51+
podman run -it torrust/tracker:develop
52+
```
53+
> Please read our [container guide][containers.md] for more information.
54+
55+
### Development Version
56+
57+
- Please assure you have the ___[latest stable (or nightly) version of rust][rust]___.
58+
- Please assure that you computer has enough ram. ___Recommended 16GB.___
59+
60+
#### Checkout, Test and Run:
61+
62+
```sh
63+
# Checkout repository into a new folder:
64+
git clone https://github.com/torrust/torrust-tracker.git
65+
66+
# Change into directory and create a empty database file:
67+
cd torrust-tracker
68+
mkdir -p ./storage/tracker/lib/database/
69+
touch ./storage/tracker/lib/database/sqlite3.db
70+
71+
# Check all tests in application:
72+
cargo test --tests --benches --examples --workspace --all-targets --all-features
73+
74+
# Run the tracker:
75+
cargo run
76+
```
77+
#### Customization:
5478

55-
- Contains the [development default][src.bootstrap.config.default] i.e: [`tracker.development.sqlite3.toml`][tracker.development.sqlite3.toml].
79+
```sh
80+
# Copy the default configuration into the standard location:
81+
mkdir -p ./storage/tracker/etc/
82+
cp ./share/default/config/tracker.development.sqlite3.toml ./storage/tracker/etc/tracker.toml
5683

57-
- Also contains the container defaults: [`sqlite3`][tracker.container.sqlite3.toml] and [`mysql`][tracker.container.mysql.toml].
84+
# Customize the tracker configuration (for example):
85+
vim ./storage/tracker/etc/tracker.toml
5886

59-
To override the default configuration there is two options:
87+
# Run the tracker with the updated configuration:
88+
TORRUST_TRACKER_PATH_CONFIG="./storage/tracker/etc/tracker.toml" cargo run
89+
```
6090

61-
- Configure a different configuration path by setting the [`TORRUST_TRACKER_PATH_CONFIG`][src.bootstrap.config.path.config] environmental variable.
91+
_Optionally, you may choose to supply the entire configuration as an environmental variable:_
6292

63-
- Supply the entire configuration via the [`TORRUST_TRACKER_CONFIG`][src.bootstrap.config.config] environmental variable.
93+
```sh
94+
# Use a configuration supplied on an environmental variable:
95+
TORRUST_TRACKER_CONFIG=$(cat "./storage/tracker/etc/tracker.toml") cargo run
96+
```
6497

98+
_For deployment you __should__ override the `api_admin_token` by using an environmental variable:_
6599

66-
> 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.
100+
```sh
101+
# Generate a Secret Token:
102+
gpg --armor --gen-random 1 10 | tee ./storage/tracker/lib/tracker_api_admin_token.secret
103+
chmod go-rwx ./storage/tracker/lib/tracker_api_admin_token.secret
67104

105+
# Override secret in configuration using an environmental variable:
106+
TORRUST_TRACKER_CONFIG=$(cat "./storage/tracker/etc/tracker.toml") \
107+
TORRUST_TRACKER_API_ADMIN_TOKEN=$(cat "./storage/tracker/lib/tracker_api_admin_token.secret") \
108+
cargo run
109+
```
110+
111+
> Please view our [crate documentation][documentation] for more detailed instructions.
68112
69113
### Services
70-
After running the tracker these services will be available (as defined in the default configuration):
114+
The following services are provided by the default configuration:
115+
116+
- UDP _(tracker)_
117+
- `udp://127.0.0.1:6969/announce`.
118+
- HTTP _(tracker)_
119+
- `http://127.0.0.1:6969/announce`.
120+
- API _(management)_
121+
- `http://127.0.0.1:1212/api/v1/stats?token=MyAccessToken`.
71122

72-
* UDP tracker: `udp://127.0.0.1:6969/announce`.
73-
* HTTP tracker: `http://127.0.0.1:6969/announce`.
74-
* API: `http://127.0.0.1:1212/api/v1/stats?token=MyAccessToken`.
75123

76124
## Documentation
77125

78-
* [Crate documentation]
79-
* [API `v1`]
80-
* [HTTP Tracker]
81-
* [UDP Tracker]
126+
- [Management API (Version 1)][api]
127+
- [Tracker (HTTP/TLS)][http]
128+
- [Tracker (UDP)][udp]
82129

83130
## Contributing
84131

132+
This is an open-source community supported project.</br>
85133
We welcome contributions from the community!
86134

87-
How can you contribute?
135+
__How can you contribute?__
88136

89-
* Bug reports and feature requests.
90-
* Code contributions. You can start by looking at the issues labeled "[good first issues]".
91-
* Documentation improvements. Check the [documentation] and [API documentation] for typos, errors, or missing information.
92-
* Participation in the community. You can help by answering questions in the [discussions].
137+
- Bug reports and feature requests.
138+
- Code contributions. You can start by looking at the issues labeled "[good first issues]".
139+
- Documentation improvements. Check the [documentation] and [API documentation] for typos, errors, or missing information.
140+
- Participation in the community. You can help by answering questions in the [discussions].
93141

94142
## License
95143

@@ -101,41 +149,39 @@ This project was a joint effort by [Nautilus Cyberneering GmbH][nautilus] and [D
101149

102150

103151

104-
[container_wf]: https://github.com/torrust/torrust-tracker/actions/workflows/container.yaml
105-
[container_wf_b]: https://github.com/torrust/torrust-tracker/actions/workflows/container.yaml/badge.svg
106-
[coverage_wf]: https://github.com/torrust/torrust-tracker/actions/workflows/coverage.yaml
107-
[coverage_wf_b]: https://github.com/torrust/torrust-tracker/actions/workflows/coverage.yaml/badge.svg
108-
[testing_wf]: https://github.com/torrust/torrust-tracker/actions/workflows/testing.yaml
109-
[testing_wf_b]: https://github.com/torrust/torrust-tracker/actions/workflows/testing.yaml/badge.svg
152+
[container_wf]: ../../actions/workflows/container.yaml
153+
[container_wf_b]: ../../actions/workflows/container.yaml/badge.svg
154+
[coverage_wf]: ../../actions/workflows/coverage.yaml
155+
[coverage_wf_b]: ../../actions/workflows/coverage.yaml/badge.svg
156+
[deployment_wf]: ../../actions/workflows/deployment.yaml
157+
[deployment_wf_b]: ../../actions/workflows/deployment.yaml/badge.svg
158+
[testing_wf]: ../../actions/workflows/testing.yaml
159+
[testing_wf_b]: ../../actions/workflows/testing.yaml/badge.svg
110160

161+
[bittorrent]: http://bittorrent.org/
111162
[rust]: https://www.rust-lang.org/
163+
[axum]: https://github.com/tokio-rs/axum
112164
[newtrackon]: https://newtrackon.com/
113165
[coverage]: https://app.codecov.io/gh/torrust/torrust-tracker
166+
[torrust]: https://torrust.com/
114167

168+
[dockerhub_torrust_tracker]: https://hub.docker.com/r/torrust/tracker/tags
169+
170+
[torrent_source_felid]: https://github.com/qbittorrent/qBittorrent/discussions/19406
171+
172+
[BEP 00]: https://www.bittorrent.org/beps/bep_0000.html
115173
[BEP 03]: https://www.bittorrent.org/beps/bep_0003.html
116174
[BEP 07]: https://www.bittorrent.org/beps/bep_0007.html
117-
[BEP 15]: http://www.bittorrent.org/beps/bep_0015.html
118-
[BEP 23]: http://bittorrent.org/beps/bep_0023.html
119-
[BEP 27]: http://bittorrent.org/beps/bep_0027.html
120-
[BEP 48]: http://bittorrent.org/beps/bep_0048.html
175+
[BEP 15]: https://www.bittorrent.org/beps/bep_0015.html
176+
[BEP 23]: https://www.bittorrent.org/beps/bep_0023.html
177+
[BEP 27]: https://www.bittorrent.org/beps/bep_0027.html
178+
[BEP 48]: https://www.bittorrent.org/beps/bep_0048.html
121179

122180
[containers.md]: ./docs/containers.md
123181

124-
[share.default.config]: ./share/default/config/
125-
[tracker.development.sqlite3.toml]: ./share/default/config/tracker.development.sqlite3.toml
126-
[src.bootstrap.config.default]: ./src/bootstrap/config.rs#L18
127-
[tracker.container.sqlite3.toml]: ./share/default/config/tracker.container.sqlite3.toml
128-
[tracker.container.mysql.toml]: ./share/default/config/tracker.container.mysql.toml
129-
[share.container.entry_script_sh.default]: ./share/container/entry_script_sh#L10
130-
131-
[src.bootstrap.config.path.config]: ./src/bootstrap/config.rs#L15
132-
[src.bootstrap.config.config]: ./src/bootstrap/config.rs#L11
133-
[src.bootstrap.config.admin.token]: ./src/bootstrap/config.rs#L12
134-
135-
[Crate documentation]: https://docs.rs/torrust-tracker/
136-
[API `v1`]: https://docs.rs/torrust-tracker/3.0.0-alpha.4/torrust_tracker/servers/apis/v1
137-
[HTTP Tracker]: https://docs.rs/torrust-tracker/3.0.0-alpha.4/torrust_tracker/servers/http
138-
[UDP Tracker]: https://docs.rs/torrust-tracker/3.0.0-alpha.4/torrust_tracker/servers/udp
182+
[api]: https://docs.rs/torrust-tracker/3.0.0-alpha.4/torrust_tracker/servers/apis/v1
183+
[http]: https://docs.rs/torrust-tracker/3.0.0-alpha.4/torrust_tracker/servers/http
184+
[udp]: https://docs.rs/torrust-tracker/3.0.0-alpha.4/torrust_tracker/servers/udp
139185

140186
[good first issues]: https://github.com/torrust/torrust-tracker/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22
141187
[documentation]: https://docs.rs/torrust-tracker/
@@ -144,7 +190,7 @@ This project was a joint effort by [Nautilus Cyberneering GmbH][nautilus] and [D
144190

145191
[COPYRIGHT]: ./COPYRIGHT
146192

147-
[nautilus]: https://nautilus-cyberneering.de/
193+
[nautilus]: https://github.com/orgs/Nautilus-Cyberneering/
148194
[Dutch Bits]: https://dutchbits.nl
149195
[Naim A.]: https://github.com/naim94a/udpt
150196
[greatest-ape]: https://github.com/greatest-ape/aquatic

‎cSpell.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,7 @@
6363
"libz",
6464
"LOGNAME",
6565
"Lphant",
66+
"matchmakes",
6667
"metainfo",
6768
"middlewares",
6869
"mockall",

0 commit comments

Comments
 (0)