Skip to content

Commit f0662e0

Browse files
da2ce7da2ce7
committed
Merge #344: various: work on readme
3a9954e various: work on readme (Cameron Garnham) Pull request description: ACKs for top commit: da2ce7: ACK 3a9954e Tree-SHA512: cf62723ce1999b84665421b1c8ed099ba907b86816bdf88e867df5b640ea96ba8f05e9953efacd1bc52de027a0288eb9c0da1f23e1cb0f7c5be2f625926760d4
2 parents 812b65b + 3a9954e commit f0662e0

File tree

3 files changed

+104
-33
lines changed

3 files changed

+104
-33
lines changed

‎Cargo.toml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
[package]
2+
default-run = "torrust-index"
23
name = "torrust-index"
34
readme = "README.md"
45

‎README.md‎

Lines changed: 102 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -2,25 +2,29 @@
22

33
[![container_wf_b]][container_wf] [![coverage_wf_b]][coverage_wf] [![deployment_wf_b]][deployment_wf] [![testing_wf_b]][testing_wf]
44

5-
__Torrust Index__, is a [BitTorrent][bittorrent] Index (a service where a group of people can maintain a set of torrents and their associated metadata), written in [Rust Language][rust] and [axum] (a modern web application framework). ___This index aims to be respectful to established standards, (both [formal][BEP 00] and [otherwise][torrent_source_felid]).___
5+
__Torrust Index__, is a library for [BitTorrent][bittorrent] Files. Written in [Rust Language][rust] with the [axum] web framework. ___This index aims to be respectful to established standards, (both [formal][BEP 00] and [otherwise][torrent_source_felid]).___
66

77
> 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] for those who wish to get started with __Docker__ or __Podman___
9+
## About
10+
The core purpose of a [BitTorrent][bittorrent] Index is to maintain a database that connects torrent files with useful metadata. Allowing a community of users to keep track their torrents in a well organized and informative manner.
11+
12+
The __Torrust Index__ serves a [high-level api][api] for our [Torrust Index GUI][gui] client. It also connects to the [management api][api_tracker] of our [Torrust Tracker][tracker], to provide statistic and whitelisting functionally.
1013

1114
## Key Features
1215

1316
- [x] High Quality and Modern Rust Codebase.
14-
- [x] [Rest API][documentation] documentation generated from code comments.
17+
- [x] [Documentation][docs] Generated from Code Comments.
1518
- [x] [Comprehensive Suit][coverage] of Unit and Functional Tests.
1619
- [x] Good Performance in Busy Conditions.
1720
- [x] Native `IPv4` and `IPv6` support.
18-
- [x] Support for either `SQLite3` or `MySQL` databases.
19-
- [x] Categories and Tags
20-
- [x] Image Proxy
21+
- [x] Persistent `SQLite3` or `MySQL` Databases.
2122

2223
## Getting Started
2324

25+
### Upgrading
26+
If you are using `Version 1` of `torrust-tracker-backend`, please view our [upgrading guide][upgrade.md].
27+
2428
### Container Version
2529

2630
The Torrust Index is [deployed to DockerHub][dockerhub], you can run a demo immediately with the following commands:
@@ -41,36 +45,78 @@ podman run -it torrust/index:develop
4145
4246
### Development Version
4347

44-
Requirements:
48+
- Please assure you have the ___[latest stable (or nightly) version of rust][rust]___.
49+
- Please assure that you computer has enough ram. ___Recommended 16GB.___
50+
51+
#### Checkout, Test and Run:
52+
53+
```sh
54+
# Checkout repository into a new folder:
55+
git clone https://github.com/torrust/torrust-index.git
56+
57+
# Change into directory and create a empty database file:
58+
cd torrust-index
59+
mkdir -p ./storage/index/lib/database/
60+
touch ./storage/index/lib/database/sqlite3.db
61+
62+
# Check all tests in application:
63+
cargo test --tests --benches --examples --workspace --all-targets --all-features
64+
65+
# Run the index:
66+
cargo run
67+
```
68+
#### Customization:
69+
70+
```sh
71+
# Copy the default configuration into the standard location:
72+
mkdir -p ./storage/index/etc/
73+
cp ./share/default/config/index.development.sqlite3.toml ./storage/index/etc/index.toml
74+
75+
# Customize the index configuration (for example):
76+
vim ./storage/index/etc/index.toml
77+
78+
# Run the index with the updated configuration:
79+
TORRUST_INDEX_PATH_CONFIG="./storage/index/etc/index.toml" cargo run
80+
```
81+
82+
_Optionally, you may choose to supply the entire configuration as an environmental variable:_
4583

46-
* Rust Stable `1.72`
84+
```sh
85+
# Use a configuration supplied on an environmental variable:
86+
TORRUST_INDEX_CONFIG=$(cat "./storage/index/etc/index.toml") cargo run
87+
```
4788

48-
You can follow the [documentation][documentation] to install and use Torrust Index in different ways, but if you want to give it a quick try, you can use the following commands:
89+
_For deployment you __should__ override the `tracker_api_token` by using an environmental variable:_
4990

50-
```s
51-
git clone https://github.com/torrust/torrust-index.git \
52-
&& cd torrust-index \
53-
&& cargo build --release
91+
```sh
92+
# Please use the secret that you generated for the torrust-tracker configuration.
93+
# Override secret in configuration using an environmental variable
94+
TORRUST_INDEX_CONFIG=$(cat "./storage/index/etc/index.toml") \
95+
TORRUST_INDEX_TRACKER_API_TOKEN=$(cat "./storage/tracker/lib/tracker_api_admin_token.secret") \
96+
cargo run
5497
```
5598

56-
And then run `cargo run` twice. The first time to generate the `config.toml` file and the second time to run the index with the default configuration.
99+
> Please view our [crate documentation][docs] for more detailed instructions.
57100
58-
After running the index the API will be available at <http://localhost:3001>.
101+
### Services
102+
The following services are provided by the default configuration:
103+
104+
- API
105+
- `http://127.0.0.1:3001/`.
59106

60107
## Documentation
61108

62-
The technical documentation is available at [docs.rs][documentation].
109+
- [API (Version 1)][api]
63110

64111
## Contributing
65-
66-
This is an open-source community supported project.</br>
67-
We welcome contributions from the community!
112+
We are happy to support and welcome new people to our project. Please consider our [contributor guide][guide.md].</br>
113+
This is an open-source community supported project. We welcome contributions from the community!
68114

69115
__How can you contribute?__
70116

71117
- Bug reports and feature requests.
72118
- Code contributions. You can start by looking at the issues labeled "[good first issues]".
73-
- Documentation improvements. Check the [documentation] and [API documentation][api] for typos, errors, or missing information.
119+
- Documentation improvements. Check the [documentation][docs] and [API documentation][api] for typos, errors, or missing information.
74120
- Participation in the community. You can help by answering questions in the [discussions].
75121

76122
## License
@@ -87,21 +133,23 @@ Some files include explicit copyright notices and/or license notices.
87133

88134
### Legacy Exception
89135

90-
For prosperity, versions of Torrust Index 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.
91-
92-
## Contributions
136+
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.
93137

94-
The copyright of the Torrust Index is retained by the respective authors.
138+
## Contributor Agreement
139+
The copyright of the Torrust Tracker is retained by the respective authors.
95140

96141
**Contributors agree:**
97-
- That all their contributions be granted a license(s) **compatible** with the [Torrust Index License](#License).
142+
- That all their contributions be granted a license(s) **compatible** with the [Torrust Trackers License](#License).
98143
- 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)*.
99144

100-
**The Torrust-Index project has no copyright assignment agreement.**
145+
**The Torrust-Tracker project has no copyright assignment agreement.**
146+
147+
_We kindly ask you to take time and consider The Torrust Project [Contributor Agreement][agreement.md] in full._
101148

102149
## Acknowledgments
103150

104-
This project was a joint effort by [Nautilus Cyberneering GmbH](https://nautilus-cyberneering.de/), [Dutch Bits](https://dutchbits.nl) and collaborators. Thank you to you all!
151+
This project was a joint effort by [Nautilus Cyberneering GmbH][nautilus] and [Dutch Bits].
152+
105153

106154

107155
[container_wf]: ../../actions/workflows/container.yaml
@@ -116,20 +164,44 @@ This project was a joint effort by [Nautilus Cyberneering GmbH](https://nautilus
116164
[bittorrent]: http://bittorrent.org/
117165
[rust]: https://www.rust-lang.org/
118166
[axum]: https://github.com/tokio-rs/axum
167+
[newtrackon]: https://newtrackon.com/
119168
[coverage]: https://app.codecov.io/gh/torrust/torrust-index
120169
[torrust]: https://torrust.com/
121170

171+
[tracker]: https://github.com/torrust/torrust-tracker
172+
[gui]: https://github.com/torrust/torrust-index-gui
173+
122174
[dockerhub]: https://hub.docker.com/r/torrust/index/tags
175+
123176
[torrent_source_felid]: https://github.com/qbittorrent/qBittorrent/discussions/19406
124177

178+
[BEP 00]: https://www.bittorrent.org/beps/bep_0000.html
179+
[BEP 03]: https://www.bittorrent.org/beps/bep_0003.html
180+
[BEP 07]: https://www.bittorrent.org/beps/bep_0007.html
181+
[BEP 15]: https://www.bittorrent.org/beps/bep_0015.html
182+
[BEP 23]: https://www.bittorrent.org/beps/bep_0023.html
183+
[BEP 27]: https://www.bittorrent.org/beps/bep_0027.html
184+
[BEP 48]: https://www.bittorrent.org/beps/bep_0048.html
185+
125186
[containers.md]: ./docs/containers.md
187+
[upgrade.md]: ./upgrades/from_v1_0_0_to_v2_0_0/README.md
126188

127-
[documentation]: https://docs.rs/torrust-index-backend/latest/torrust_index_backend/
128-
[api]: https://docs.rs/torrust-index-backend/latest/torrust_index_backend/web/api/v1/
189+
[docs]: https://docs.rs/torrust-index/latest/torrust_index/
190+
[api]: https://docs.rs/torrust-index/latest/torrust_index/web/api/v1/
191+
[api_tracker]: https://docs.rs/torrust-tracker/latest/torrust_tracker/servers/apis/v1
129192

130-
[good first issues]: https://github.com/torrust/torrust-index/issues?q=is%3Aissue+is%3Aopen
193+
[good first issues]: https://github.com/torrust/torrust-index/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22
131194
[discussions]: https://github.com/torrust/torrust-index/discussions
132195

196+
[guide.md]: https://github.com/torrust/.github/blob/main/info/contributing.md
197+
[agreement.md]: https://github.com/torrust/.github/blob/main/info/licensing/contributor_agreement_v01.md
198+
133199
[AGPL_3_0]: ./docs/licenses/LICENSE-AGPL_3_0
134200
[MIT_0]: ./docs/licenses/LICENSE-MIT_0
135201
[FSF]: https://www.fsf.org/
202+
203+
[nautilus]: https://github.com/orgs/Nautilus-Cyberneering/
204+
[Dutch Bits]: https://dutchbits.nl
205+
[Naim A.]: https://github.com/naim94a/udpt
206+
[greatest-ape]: https://github.com/greatest-ape/aquatic
207+
[Power2All]: https://github.com/power2all

‎docs/containers.md‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -143,9 +143,7 @@ The following environmental variables can be set:
143143
- `TORRUST_INDEX_DATABASE_DRIVER` - The database type used for the container, (options: `sqlite3`, `mysql`, default `sqlite3`). Please Note: This dose not override the database configuration within the `.toml` config file.
144144
- `TORRUST_INDEX_CONFIG` - Load config from this environmental variable instead from a file, (i.e: `TORRUST_INDEX_CONFIG=$(cat index-index.toml)`).
145145
- `USER_ID` - The user id for the runtime crated `torrust` user. Please Note: This user id should match the ownership of the host-mapped volumes, (default `1000`).
146-
- `UDP_PORT` - The port for the UDP index. This should match the port used in the configuration, (default `6969`).
147-
- `HTTP_PORT` - The port for the HTTP index. This should match the port used in the configuration, (default `7070`).
148-
- `API_PORT` - The port for the index API. This should match the port used in the configuration, (default `1212`).
146+
- `API_PORT` - The port for the index API. This should match the port used in the configuration, (default `3001`).
149147

150148

151149
### Sockets

0 commit comments

Comments
 (0)