Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix podman commands in docs #711

Merged
merged 2 commits into from
Feb 23, 2024
Merged

Fix podman commands in docs #711

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d673a59
docs: fix podman commands
josecelano Feb 23, 2024
c348f72
docs: fix linter warnings in markdown
josecelano Feb 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 32 additions & 28 deletions README.md
View file
Open in desktop
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 torrust/tracker:develop
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
35 changes: 22 additions & 13 deletions docs/containers.md
View file
Open in desktop
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 @@ -14,14 +14,15 @@ docker run -it torrust/tracker:latest
or with Podman:

```sh
podman run -it torrust/tracker:latest
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,22 +124,25 @@ docker run -it torrust-tracker:release
# Debug Mode
docker run -it torrust-tracker:debug
```

#### (Podman) Run Basic

```sh
# Release Mode
podman run -it torrust-tracker:release
podman run -it docker.io/torrust-tracker:release

# Debug Mode
podman run -it torrust-tracker:debug
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 @@ -226,7 +235,7 @@ podman run -it \
--volume ./storage/tracker/lib:/var/lib/torrust/tracker:Z \
--volume ./storage/tracker/log:/var/log/torrust/tracker:Z \
--volume ./storage/tracker/etc:/etc/torrust/tracker:Z \
torrust-tracker:release
docker.io/torrust-tracker:release
```

## Docker Compose
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
Loading