Skip to content

Commit

Permalink
docs: fix linter warnings in markdown
Browse files Browse the repository at this point in the history
  • Loading branch information
@josecelano
josecelano committed Feb 23, 2024
1 parent d673a59 commit c348f72
Show file tree
Hide file tree
Showing 2 changed files with 49 additions and 36 deletions.
58 changes: 31 additions & 27 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -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].
Expand All @@ -20,41 +18,44 @@ __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

### Container Version

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:
Expand All @@ -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:
Expand All @@ -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:
Expand All @@ -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)_
Expand All @@ -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].</br>
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
Expand All @@ -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.**

Expand All @@ -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
Expand Down
27 changes: 18 additions & 9 deletions docs/containers.md
View file
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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
Expand All @@ -38,19 +39,22 @@ 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
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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -118,6 +124,7 @@ docker run -it torrust-tracker:release
# Debug Mode
docker run -it torrust-tracker:debug
```

#### (Podman) Run Basic

```sh
Expand All @@ -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:
Expand All @@ -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`.
Expand All @@ -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[:<options>]`.
Expand All @@ -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

Expand Down Expand Up @@ -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:

Expand Down

0 comments on commit c348f72

Please sign in to comment.