Skip to content

Commit

Permalink
docs: fix linter warnings
Browse files Browse the repository at this point in the history
  • Loading branch information
josecelano committed Feb 9, 2024
1 parent 286d9cf commit 67a8827
Showing 1 changed file with 17 additions and 8 deletions.
25 changes: 17 additions & 8 deletions docs/containers.md
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 index 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 torrust/index: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/index/lib/ ./storage/index/log/ ./storage/index/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-index.git; cd torrust-index
```

### (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-index: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-index:release
# Debug Mode
docker run -it torrust-index:debug
```

#### (Podman) Run Basic

```sh
Expand All @@ -129,11 +136,13 @@ podman run -it torrust-index:debug
```

### Arguments

The arguments need to be placed before the image tag. i.e.

`run [arguments] torrust-index:release`

#### Environmental Variables:

Environmental variables are loaded through the `--env`, in the format `--env VAR="value"`.

The following environmental variables can be set:
Expand All @@ -145,8 +154,8 @@ The following environmental variables can be set:
- `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`).
- `API_PORT` - The port for the index API. This should match the port used in the configuration, (default `3001`).


### 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 @@ -159,8 +168,9 @@ 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
By default the container will use install volumes for `/var/lib/torrust/index`, `/var/log/torrust/index`, and `/etc/torrust/index`, however for better administration it good to make these volumes host-mapped.
### Mapped Volumes

By default the container will install volumes for `/var/lib/torrust/index`, `/var/log/torrust/index`, and `/etc/torrust/index`, 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 @@ -172,10 +182,9 @@ The default mapping can be supplied with the following arguments:
--volume ./storage/index/etc:/etc/torrust/index: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

0 comments on commit 67a8827

Please sign in to comment.