Skip to content

Commit fb5f61a

Browse files
josecelanojosecelano
committed
docs: [#183] containerization documentaion
1 parent 1d0f370 commit fb5f61a

File tree

5 files changed

+380
-1
lines changed

5 files changed

+380
-1
lines changed

‎Containerfile‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,10 +36,12 @@ COPY --from=gcc --chmod=0555 /usr/local/bin/su-exec /bin/su-exec
3636

3737
ARG USER_ID=1000
3838
ARG INDEX_GUI_PORT=3000
39+
ARG NUXT_PUBLIC_API_BASE0=http://localhost:3001/v1
3940

4041
ENV TZ=Etc/UTC
4142
ENV USER_ID=${USER_ID}
4243
ENV INDEX_GUI_PORT=${INDEX_GUI_PORT}
44+
ENV NUXT_PUBLIC_API_BASE=${NUXT_PUBLIC_API_BASE}
4345

4446
EXPOSE $INDEX_GUI_PORT/tcp
4547

‎contrib/dev-tools/container/e2e/sqlite/e2e-env-up.sh‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
#!/bin/bash
22

3-
TORRUST_INDEX_CONFIG=$(cat ./share/default/config/index.e2e.container.sqlite3.toml) \
3+
USER_ID=${USER_ID:-1000} \
4+
TORRUST_INDEX_CONFIG=$(cat ./share/default/config/index.e2e.container.sqlite3.toml) \
5+
TORRUST_TRACKER_CONFIG=$(cat ./share/default/config/tracker.e2e.container.sqlite3.toml) \
46
docker compose build
57

68
USER_ID=${USER_ID:-1000} \

‎docs/containers.md‎

Lines changed: 368 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,368 @@
1+
# Containers (Docker or Podman)
2+
3+
- [Demo environment](#demo-environment)
4+
- [Requirements](#requirements)
5+
- [Container Volumes](#container-volumes)
6+
- [Pre-Create Host-Mapped Folders](#pre-create-host-mapped-folders)
7+
- [Matching Ownership ID's of Host Storage and Container Volumes](#matching-ownership-ids-of-host-storage-and-container-volumes)
8+
- [Mapped Tree Structure](#mapped-tree-structure)
9+
- [Building the Container](#building-the-container)
10+
- [Clone and Change into Repository](#clone-and-change-into-repository)
11+
- [(Docker) Setup Context](#docker-setup-context)
12+
- [(Docker) Build](#docker-build)
13+
- [(Podman) Build](#podman-build)
14+
- [Running the Container](#running-the-container)
15+
- [Basic Run](#basic-run)
16+
- [(Docker) Run Basic](#docker-run-basic)
17+
- [(Podman) Run Basic](#podman-run-basic)
18+
- [Arguments](#arguments)
19+
- [Environmental Variables](#environmental-variables)
20+
- [Sockets](#sockets)
21+
- [Volumes](#volumes)
22+
- [Complete Example](#complete-example)
23+
- [With Docker](#with-docker)
24+
- [With Podman](#with-podman)
25+
- [Docker Compose](#docker-compose)
26+
- [Build and Run](#build-and-run)
27+
- [Access Mysql with docker](#access-mysql-with-docker)
28+
- [Links](#links)
29+
30+
## Demo environment
31+
32+
It is simple to setup the Index GUI with the default
33+
configuration and run it using the pre-built public docker image:
34+
35+
With Docker:
36+
37+
```sh
38+
docker run -it torrust/index-gui:latest
39+
```
40+
41+
or with Podman:
42+
43+
```sh
44+
podman run -it torrust/index-gui:latest
45+
```
46+
47+
## Requirements
48+
49+
- Tested with recent versions of Docker or Podman.
50+
51+
## Container Volumes
52+
53+
The [Containerfile](../Containerfile) (i.e. the Dockerfile) Defines one volume:
54+
55+
```Dockerfile
56+
VOLUME ["/var/log/torrust/index-gui"]
57+
```
58+
59+
When instancing the container image with the `docker run` or `podman run` command, we map the volumes to the local storage:
60+
61+
```s
62+
./storage/index-gui/log -> /var/log/torrust/index-gui
63+
```
64+
65+
> NOTE: You can adjust this mapping for your preference, however this mapping is the default in our guides and scripts.
66+
67+
### Pre-Create Host-Mapped Folders
68+
69+
Please run this command where you wish to run the container:
70+
71+
```sh
72+
mkdir -p ./storage/index-gui/log/
73+
```
74+
75+
### Matching Ownership ID's of Host Storage and Container Volumes
76+
77+
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_ID` environmental variable.
78+
79+
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.
80+
81+
### Mapped Tree Structure
82+
83+
Using the standard mapping defined above produces this following mapped tree:
84+
85+
```s
86+
storage/index-gui/
87+
└── log => /var/log/torrust/index-gui (future use)
88+
```
89+
90+
> NOTE: we don't support `tls` directly. You have to use a reverse proxy to access the
91+
application using HTTPs. See <https://github.com/torrust/torrust-index/issues/131>.
92+
93+
## Building the Container
94+
95+
### Clone and Change into Repository
96+
97+
```sh
98+
# Inside your dev folder
99+
git clone https://github.com/torrust/torrust-index-gui.git; cd torrust-index-gui
100+
```
101+
102+
### (Docker) Setup Context
103+
104+
Before starting, if you are using docker, it is helpful to reset the context to the default:
105+
106+
```sh
107+
docker context use default
108+
```
109+
110+
### (Docker) Build
111+
112+
```sh
113+
# Release Mode
114+
docker build --target release --tag torrust-index-gui:release --file Containerfile .
115+
116+
# Debug Mode
117+
docker build --target debug --tag torrust-index-gui:debug --file Containerfile .
118+
```
119+
120+
### (Podman) Build
121+
122+
```sh
123+
# Release Mode
124+
podman build --target release --tag torrust-index-gui:release --format docker --file Containerfile .
125+
126+
# Debug Mode
127+
podman build --target debug --tag torrust-index-gui:debug --format docker --file Containerfile .
128+
```
129+
130+
> NOTE: we use `--format docker` because `HEALTHCHECK` is not supported for OCI image format and it is ignored otherwise.
131+
132+
## Running the Container
133+
134+
### Basic Run
135+
136+
No arguments are needed for simply checking the container image works:
137+
138+
#### (Docker) Run Basic
139+
140+
```sh
141+
# Release Mode
142+
docker run -it torrust-index-gui:release
143+
144+
# Debug Mode
145+
docker run -it torrust-index-gui:debug
146+
```
147+
148+
#### (Podman) Run Basic
149+
150+
```sh
151+
# Release Mode
152+
podman run -it torrust-index-gui:release
153+
154+
# Debug Mode
155+
podman run -it torrust-index-gui:debug
156+
```
157+
158+
### Arguments
159+
160+
The arguments need to be placed before the image tag. i.e.
161+
162+
`run [arguments] torrust-index-gui:release`
163+
164+
#### Environmental Variables
165+
166+
Environmental variables are loaded through the `--env`, in the format `--env VAR="value"`.
167+
168+
The following environmental variables can be set:
169+
170+
- `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`).
171+
- `INDEX_GUI_PORT` - The port on which the web application is served (default `3000`).
172+
- `NUXT_PUBLIC_API_BASE` - The base [Index API](https://github.com/torrust/torrust-index) URL the frontend connects to (default `http://localhost:3001/v1`).
173+
174+
### Sockets
175+
176+
Socket ports used internally within the container can be mapped to with the `--publish` argument.
177+
178+
The format is: `--publish [optional_host_ip]:[host_port]:[container_port]/[optional_protocol]`, for example: `--publish 127.0.0.1:3000:80/tcp`.
179+
180+
The default ports can be mapped with the following (IPv4 and IPv6):
181+
182+
```s
183+
--publish 0.0.0.0:3000:3000/tcp \
184+
--publish [::]:3000:3000/tcp
185+
```
186+
187+
> 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.
188+
189+
### Volumes
190+
191+
By default the container will install a volume for `/var/log/torrust/index-gui`, however for better administration it's good to make this volume host-mapped.
192+
193+
The argument to host-map volumes is `--volume`, with the format: `--volume=[host-src:]container-dest[:<options>]`.
194+
195+
The default mapping can be supplied with the following arguments:
196+
197+
```s
198+
--volume ./storage/index-gui/log:/var/log/torrust/index-gui:Z
199+
```
200+
201+
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.
202+
203+
## Complete Example
204+
205+
### With Docker
206+
207+
```sh
208+
## Setup Docker Default Context
209+
docker context use default
210+
211+
## Build Container Image
212+
docker build --target release --tag torrust-index-gui:release --file Containerfile .
213+
214+
## Setup Mapped Volumes
215+
mkdir -p ./storage/index-gui/log/
216+
217+
## Run Torrust Index GUI Container Image (IPv6)
218+
docker run -it \
219+
--env USER_ID="$(id -u)" \
220+
--env INDEX_GUI_PORT="3000" \
221+
--env NUXT_PUBLIC_API_BASE="http://localhost:3001/v1" \
222+
--env NITRO_HOST="::" \
223+
--env NITRO_PORT="3000" \
224+
--publish [::]:3000:3000/tcp \
225+
--volume ./storage/index-gui/log:/var/log/torrust/index-gui:Z \
226+
torrust-index-gui:release
227+
228+
## Run Torrust Index GUI Container Image (IPv4)
229+
docker run -it \
230+
--env USER_ID="$(id -u)" \
231+
--env INDEX_GUI_PORT="3000" \
232+
--env NUXT_PUBLIC_API_BASE="http://localhost:3001/v1" \
233+
--env NITRO_HOST="0.0.0.0" \
234+
--env NITRO_PORT="3000" \
235+
--publish 0.0.0.0:3000:3000/tcp \
236+
--volume ./storage/index-gui/log:/var/log/torrust/index-gui:Z \
237+
torrust-index-gui:release
238+
```
239+
240+
### With Podman
241+
242+
```sh
243+
## Build Container Image
244+
podman build --target release --tag torrust-index-gui:release --file Containerfile .
245+
246+
## Setup Mapped Volumes
247+
mkdir -p ./storage/index-gui/log/
248+
249+
## Run Torrust Index GUI Container Image (IPv6)
250+
podman run -it \
251+
--env USER_ID="$(id -u)" \
252+
--env INDEX_GUI_PORT="3000" \
253+
--env NUXT_PUBLIC_API_BASE="http://localhost:3001/v1" \
254+
--env NITRO_HOST="::" \
255+
--env NITRO_PORT="3000" \
256+
--publish [::]:3000:3000/tcp \
257+
--volume ./storage/index-gui/log:/var/log/torrust/index-gui:Z \
258+
torrust-index-gui:release
259+
260+
## Run Torrust Index GUI Container Image (IPv4)
261+
podman run -it \
262+
--env USER_ID="$(id -u)" \
263+
--env INDEX_GUI_PORT="3000" \
264+
--env NUXT_PUBLIC_API_BASE="http://localhost:3001/v1" \
265+
--env NITRO_HOST="0.0.0.0" \
266+
--env NITRO_PORT="3000" \
267+
--publish 0.0.0.0:3000:3000/tcp \
268+
--volume ./storage/index-gui/log:/var/log/torrust/index-gui:Z \
269+
torrust-index-gui:release
270+
```
271+
272+
## Docker Compose
273+
274+
The docker-compose configuration includes the MySQL service configuration. It's only used for the Tracker and Index.
275+
Please refer to their documentation for more information.
276+
277+
### Build and Run
278+
279+
```sh
280+
mkdir -p ./storage/index-gui/log/
281+
282+
USER_ID=${USER_ID:-1000} \
283+
TORRUST_INDEX_CONFIG=$(cat ./share/default/config/index.e2e.container.sqlite3.toml) \
284+
TORRUST_TRACKER_CONFIG=$(cat ./share/default/config/tracker.e2e.container.sqlite3.toml) \
285+
docker compose build
286+
287+
USER_ID=${USER_ID:-1000} \
288+
TORRUST_INDEX_CONFIG=$(cat ./share/default/config/index.e2e.container.sqlite3.toml) \
289+
TORRUST_INDEX_DATABASE="e2e_testing_sqlite3" \
290+
TORRUST_INDEX_DATABASE_DRIVER="sqlite3" \
291+
TORRUST_INDEX_TRACKER_API_TOKEN="MyAccessToken" \
292+
TORRUST_TRACKER_CONFIG=$(cat ./share/default/config/tracker.e2e.container.sqlite3.toml) \
293+
TORRUST_TRACKER_DATABASE="e2e_testing_sqlite3" \
294+
TORRUST_TRACKER_DATABASE_DRIVER="sqlite3" \
295+
TORRUST_TRACKER_API_ADMIN_TOKEN="MyAccessToken" \
296+
docker compose up --detach --pull always --remove-orphans
297+
```
298+
299+
After running the `compose up` command you will have these running containers:
300+
301+
```s
302+
$ docker ps
303+
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
304+
87a79326ec4e torrust-index-gui "/usr/local/bin/entr…" 12 seconds ago Up 10 seconds (healthy) 0.0.0.0:3000->3000/tcp, :::3000->3000/tcp, 0.0.0.0:24678->24678/tcp, :::24678->24678/tcp torrust-index-gui-1
305+
1e81272eea9c torrust/index:develop "/usr/local/bin/entr…" 12 seconds ago Up 11 seconds (healthy) 0.0.0.0:3001->3001/tcp, :::3001->3001/tcp torrust-index-1
306+
79812c5b9c5f torrust/tracker:develop "/usr/local/bin/entr…" 12 seconds ago Up 11 seconds (healthy) 0.0.0.0:1212->1212/tcp, :::1212->1212/tcp, 0.0.0.0:7070->7070/tcp, :::7070->7070/tcp, 1313/tcp, 0.0.0.0:6969->6969/udp, :::6969->6969/udp torrust-tracker-1
307+
36bf4c48df1d dockage/mailcatcher:0.8.2 "entrypoint mailcatc…" 12 seconds ago Up 11 seconds 0.0.0.0:1025->1025/tcp, :::1025->1025/tcp, 0.0.0.0:1080->1080/tcp, :::1080->1080/tcp torrust-mailcatcher-1
308+
fc5830c1b105 mysql:8.0 "docker-entrypoint.s…" 12 seconds ago Up 11 seconds (healthy) 0.0.0.0:3306->3306/tcp, :::3306->3306/tcp, 33060/tcp torrust-mysql-1 torrust-mysql-1
309+
```
310+
311+
And you should be able to use the application, for example making a request to:
312+
313+
<http://127.0.0.1:3000>
314+
315+
You can stop the containers with:
316+
317+
```s
318+
docker compose down
319+
```
320+
321+
Additionally, you can delete all resources (containers, volumes, networks) with:
322+
323+
```s
324+
docker compose down -v
325+
```
326+
327+
### Access Mysql with docker
328+
329+
These are some useful commands for MySQL.
330+
331+
Open a shell in the MySQL container using docker or docker-compose.
332+
333+
```s
334+
docker exec -it torrust-mysql-1 /bin/bash
335+
docker compose exec mysql /bin/bash
336+
```
337+
338+
Connect to MySQL from inside the MySQL container or from the host:
339+
340+
```s
341+
mysql -h127.0.0.1 -uroot -proot_secret_password
342+
```
343+
344+
The when MySQL container is started the first time, it creates the database, user, and permissions needed.
345+
If you see the error "Host is not allowed to connect to this MySQL server" you can check that users have the right permissions in the database. Make sure the user `root` and `db_user` can connect from any host (`%`).
346+
347+
```s
348+
mysql> SELECT host, user FROM mysql.user;
349+
+-----------+------------------+
350+
| host | user |
351+
+-----------+------------------+
352+
| % | db_user |
353+
| % | root |
354+
| localhost | mysql.infoschema |
355+
| localhost | mysql.session |
356+
| localhost | mysql.sys |
357+
| localhost | root |
358+
+-----------+------------------+
359+
6 rows in set (0.00 sec)
360+
```
361+
362+
If the database, user or permissions are not created the reason could be the MySQL container volume can be corrupted. Delete it and start again the containers.
363+
364+
## Links
365+
366+
- [Deploying Docker containers on Azure](https://docs.docker.com/cloud/aci-integration/).
367+
- [Docker run options for ACI containers](https://docs.docker.com/cloud/aci-container-features/).
368+
- [Quickstart: Deploy a container instance in Azure using the Docker CLI](https://learn.microsoft.com/en-us/azure/container-instances/quickstart-docker-cli).

0 commit comments

Comments
 (0)