Skip to content

Commit 6970a37

Browse files
almereydaalmereyda
committed
Docs(README): adapt to build + compose changes
1 parent 8991235 commit 6970a37

File tree

1 file changed

+306
-63
lines changed

1 file changed

+306
-63
lines changed

‎README.md

Lines changed: 306 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -1,65 +1,308 @@
11
# pretalx-docker
22

3-
This repository contains a docker-compose setup as well as an [ansible](https://docs.ansible.com) role for a
4-
[pretalx](https://github.com/pretalx/pretalx) installation based on docker.
5-
6-
**Please note that this repository is provided by the pretalx community, and not supported by the pretalx team.**
7-
8-
## Installation with docker-compose
9-
10-
### For testing
11-
12-
* Run ``docker-compose up -d``. After a few minutes the setup should be accessible at http://localhost/orga
13-
* Set up a user and an organizer by running ``docker exec -ti pretalx pretalx init``.
14-
15-
### For production
16-
17-
* Edit ``conf/pretalx.cfg`` and fill in your own values (→ [configuration
18-
documentation](https://docs.pretalx.org/en/latest/administrator/configure.html))
19-
* Edit ``docker-compose.yml`` and remove the complete section with ``ports: - "80:80"`` from the file (if you go with
20-
traefic as reverse proxy) or change the line to ``ports: - "127.0.0.1:8355:80"`` (if you use nginx). **Change the
21-
database password.**
22-
* If you don't want to use docker volumes, create directories for the persistent data and make them read-writeable for
23-
the userid 999 and the groupid 999. Change ``pretalx-redis``, ``pretalx-db``, ``pretalx-data`` and ``pretalx-public`` to the corresponding
24-
directories you've chosen.
25-
* Configure a reverse-proxy for better security and to handle TLS. Pretalx listens on port 80 in the ``pretalxdocker``
26-
network. I recommend to go with traefik for its ease of setup, docker integration and [LetsEncrypt
27-
support](https://docs.traefik.io/user-guide/docker-and-lets-encrypt/). An example to copy into the normal compose file
28-
is located at ``reverse-proxy-examples/docker-compose``. You can also find a few words on an nginx configuration at
29-
``reverse-proxy-examples/nginx``
30-
* Make sure you serve all requests for the `/static/` and `/media/` paths (when `debug=false`). See [installation](https://docs.pretalx.org/administrator/installation/#step-7-ssl) for more information
31-
* Optional: Some of the Gunicorn parameters can be adjusted via environment viariables:
32-
* To adjust the number of [Gunicorn workers](https://docs.gunicorn.org/en/stable/settings.html#workers), provide
33-
the container with `GUNICORN_WORKERS` environment variable.
34-
* `GUNICORN_MAX_REQUESTS` and `GUNICORN_MAX_REQUESTS_JITTER` to configure the requests a worker instance will process before restarting.
35-
* `GUNICORN_FORWARDED_ALLOW_IPS` lets you specify which IPs to trust (i.e. which reverse proxies' `X-Forwarded-*` headers can be used to infer connection security).
36-
* `GUNICORN_BIND_ADDR` can be used to change the interface and port that Gunicorn will listen on. Default: `0.0.0.0:80`
37-
38-
Here's how to set an environment variable [in
39-
`docker-compose.yml`](https://docs.docker.com/compose/environment-variables/set-environment-variables/)
40-
or when using [`docker run` command](https://docs.docker.com/engine/reference/run/#env-environment-variables).
41-
* Run ``docker-compose up -d ``. After a few minutes the setup should be accessible under http://yourdomain.com/orga
42-
* Set up a user and an organizer by running ``docker exec -ti pretalx pretalx init``.
43-
* Set up a cronjob for periodic tasks like this ``15,45 * * * * docker exec pretalx-app pretalx runperiodic``
44-
45-
46-
## Installation with ansible
47-
48-
(Please note that we also provide a second ansible role for use without docker
49-
[here](https://github.com/pretalx/ansible-pretalx/)).
50-
51-
### For testing
52-
53-
* Add the role at ``ansible-role`` to your ansible setup.
54-
* Roll out the role
55-
* You should be able to reach pretalx at ``http://localhost/orga``
56-
* Set up a user and an organizer by running ``docker exec -ti pretalx pretalx init``.
57-
58-
### For production
59-
60-
* Add the role at ``ansible-role`` to your ansible setup.
61-
* Fill in the variables listed in the ``vars/main.yml`` file. **Make sure to set testing to false!**
62-
* Set up a reverse proxy to handle TLS. traefik is recommended. The containers that get rolled out are already tagged
63-
for traefik. An example role for traefik is included at ``reverse-proxy-examples/ansible/traefik``.
64-
* Roll out the role. After a few minutes pretalx should be reachable at the configured domain.
65-
* Set up a user and an organizer by running ``docker exec -ti pretalx pretalx init`` .
3+
This repository contains a Container image and a Docker Compose setup for a
4+
[pretalx](https://github.com/pretalx/pretalx) installation.
5+
6+
> **Please note that this repository is provided by the pretalx community, and not supported by the pretalx team.**
7+
8+
## Installation
9+
10+
This repository follows the Pretalx installation instructions as closely as possible.
11+
12+
- [Installation — pretalx documentation](https://docs.pretalx.org/administrator/installation/)
13+
14+
## Configuration
15+
16+
The repository implements the dot env pattern to configure all application containers through environmental variables.
17+
18+
The setup prepares all environmental variables supported by Pretalx:
19+
20+
- [Configuration — pretalx documentation](https://docs.pretalx.org/administrator/configure/)
21+
22+
Copy the example and modify it according to your setup:
23+
24+
```sh
25+
cp .env.example .env
26+
```
27+
28+
You will likely want to provide email settings to a live environment.
29+
30+
Additional variables were introduced to configure the web proxy, the containers, the image build and the database:
31+
32+
- `FQDN`, fully-qualified domain name, used for the Traefik `Host` matcher in the `live` configuration and for the `plugins` images
33+
- `POSTGRES_DB`, Postgres database name
34+
- `POSTGRES_USER`, Postgres user name
35+
- `POSTGRES_PASSWORD`, Postgres user password
36+
- `PRETALX_LOG_LEVEL`, Gunicorn and Celery log level
37+
- `PRETALX_IMAGE`, Pretalx Container image name
38+
- `PRETALX_TAG`, Pretalx Container image tag
39+
40+
The following variables are available to configure the Gunicorn web process:
41+
42+
- `GUNICORN_WORKERS`
43+
- `GUNICORN_MAX_REQUESTS`
44+
- `GUNICORN_MAX_REQUESTS_JITTER`
45+
- `GUNICORN_FORWARDED_ALLOW_IPS`
46+
- `GUNICORN_BIND_ADDR`
47+
48+
Please refer to [`context/default/entrypoint.sh`](./context/default/entrypoint.sh) and [the Gunicorn settings documentation](https://docs.gunicorn.org/en/stable/settings.html) about their usage.
49+
50+
## Build
51+
52+
This repository is used for building Container images from the source manifests present here.
53+
54+
> It does not cover the use case of building a Pretalx development environment.
55+
>
56+
> It is left for the curious reader to propose this with [development containers](https://containers.dev/) directly to the `pretalx/pretalx` repository.
57+
58+
### CI
59+
60+
We provide a CI manifest to build and push container images to Docker Hub (`docker.io`) and to the GitHub Container Registry (`ghcr.io`).
61+
62+
Find it in `.github/workflows/build.yml`.
63+
64+
### Setting up the build environment
65+
66+
For educational purposes we implement this with Docker Compose on a Rootless Podman context on a SELinux-enabled Linux host, using the Docker CLI with a context on the local socket of the Podman systemd user unit.
67+
68+
- [Using Podman and Docker Compose | Enable Sysadmin](https://www.redhat.com/sysadmin/podman-docker-compose)
69+
70+
```sh
71+
$ systemctl --user start podman.service podman.socket
72+
$ docker context create podman --docker 'host=tcp:///run/user/1000/podman/podman.sock'
73+
$ docker context use podman
74+
$ docker context ls
75+
NAME DESCRIPTION DOCKER ENDPOINT ERROR
76+
default Current DOCKER_HOST based configuration unix:///var/run/docker.sock
77+
podman * unix:///run/user/1000/podman/podman.sock
78+
```
79+
80+
If your system does not have SELinux enabled or you wish to use this only with the regular Docker and Compose tooling, remove the SELinux-specific configuration:
81+
82+
```sh
83+
sed '/selinux/d' -i compose.yml
84+
```
85+
86+
To speed up builds for the a single local platform, you can disable BuildX with:
87+
88+
```sh
89+
export DOCKER_BUILDKIT=0
90+
```
91+
92+
We are making good use of [YAML Fragments in the Compose files](https://docs.docker.com/compose/compose-file/10-fragments/).
93+
94+
Feel free to adapt these examples to your liking. E.g. you may need to copy and paste the adaptations into the single manifest, e.g. to run without `-f` modifiers, or have the main file called `docker-compose.yml` for the ancient version of `docker-compose`.
95+
96+
### Local development of the Container image and the Compose manifest
97+
98+
These were the commands frequently used to develop this Compose manifest:
99+
100+
```sh
101+
docker build --load -t library/pretalx/pretalx:latest context/default
102+
```
103+
104+
The previous command is equivalent to:
105+
106+
```sh
107+
docker compose -f compose.yml -f compose.local.yml build app
108+
```
109+
110+
This will build the image with the name `${PRETALX_IMAGE}:${PRETALX_TAG}`, as specified by the inferred `image:` directive.
111+
112+
You may want to watch your Podman for the health of the containers from another shell:
113+
114+
```sh
115+
watch -n 0.5 podman ps
116+
```
117+
118+
If you have chosen not to disable BuildX, you can preview its configuration derieved from the Compose manifests:
119+
120+
```sh
121+
docker buildx bake -f compose.yml -f compose.local.yml --print
122+
```
123+
124+
### Live deployment
125+
126+
This assumes the presence of the image at the expected location in Docker Hub and a fully configured `traefik` instance connected to the `web` network.
127+
128+
```sh
129+
docker compose -f compose.yml -f compose.live.yml config
130+
```
131+
132+
### Local live-like deployment
133+
134+
If you were running a local `traefik` instance on a local `web` network, maybe even with a Smallstep CA for provisioning ACME certificates for your `.internal` network, you could add the network and necessary labels with:
135+
136+
```sh
137+
docker compose -f compose.yml -f compose.local.yml -f compose.live.yml config
138+
```
139+
140+
### With plugins
141+
142+
There is a need to accommodate for the presence of Pretalx plugins in this configuration.
143+
144+
This is achieved by creating overlay OCI file system layers and building a custom container image based on the default build context.
145+
146+
```sh
147+
docker compose -f compose.yml -f compose.local.yml -f compose.plugins.yml config
148+
```
149+
150+
Or in a live environment:
151+
152+
```sh
153+
docker compose -f compose.yml -f compose.live.yml -f compose.plugins.yml config
154+
```
155+
156+
All Compose commands apply from here.
157+
158+
If you had successfully built your local Pretalx image, you could build the plugin images with:
159+
160+
```sh
161+
bash -c 'source .env; docker build --build-arg PRETALX_IMAGE=${PRETALX_IMAGE} --build-arg PRETALX_TAG=${PRETALX_TAG} -t pretalx-${FQDN} context/plugins'
162+
```
163+
164+
The previous command is equivalent to:
165+
166+
```sh
167+
bash -c 'source .env; docker build --build-arg PRETALX_IMAGE=${PRETALX_IMAGE} --build-arg PRETALX_TAG=${PRETALX_TAG} -t pretalx-${FQDN} context/plugins'
168+
```
169+
170+
This does not work with BuildX, which for this step must be disabled as shown above, due to known regressions.
171+
172+
<details><summary>Reference</summary>
173+
174+
- [Docker build "FROM" Fails to search local images · Issue #795 · docker/buildx](https://github.com/docker/buildx/issues/795)
175+
176+
</details>
177+
178+
## Run
179+
180+
### Locally
181+
182+
When you are done with building and preloading the images into your local image store, you can start the composition with:
183+
184+
```sh
185+
docker compose -f compose.yml -f compose.local.yml up -d
186+
```
187+
188+
Continue to *Configure* below.
189+
190+
### Live
191+
192+
To run this in a live environment, it is not needed to build the images locally. They will be provided by Docker Hub.
193+
194+
```sh
195+
docker compose -f compose.yml -f compose.plugins.yml up -d
196+
```
197+
198+
Continue to *Configure* below.
199+
200+
A default blend of plugins can be provided in a separate image for distribution and could be automated here @pretalx or in other third-party repositories.
201+
202+
This would allow to provide an alternative overlay that does not build the images that are equipped with plugins, but reuses some which are already published.
203+
204+
### Management commands
205+
206+
The image's entrypoint is configured to support passing down all management commands to Pretalx.
207+
208+
- [Management commands — pretalx documentation](https://docs.pretalx.org/administrator/commands/)
209+
210+
They can be used from within a running `app` container with directly calling the `pretalx` module with `python` and passing the name of the task, here `showmigrations`:
211+
212+
```sh
213+
docker compose -f compose.yml -f compose.local.yml -f compose.plugins.yml exec app python -m pretalx showmigrations
214+
```
215+
216+
### Maintenance and update
217+
218+
Runtime commands are used to update an instance:
219+
220+
- [Maintenance — pretalx documentation](https://docs.pretalx.org/administrator/maintenance/#updates)
221+
222+
```sh
223+
docker compose -f compose.yml -f compose.local.yml -f compose.plugins.yml exec app python -m pretalx rebuild --npm-install
224+
docker compose -f compose.yml -f compose.local.yml -f compose.plugins.yml exec app python -m pretalx regenerate_css
225+
```
226+
227+
## Initialisation
228+
229+
You can start configuring your instance, when your `web` container shows as `healthy` in `podman ps`. If you were locally developing this Compose manifest and the associated Container images for a Pretalx deployment with plugins, your initialisation command reads:
230+
231+
```sh
232+
docker compose -f compose.yml -f compose.local.yml -f compose.plugins.yml exec app python -m pretalx init
233+
```
234+
235+
Please adapt it to your use case by adding or removing `-f` arguments. You will see this configuration summary and the initialisation wizard:
236+
237+
```console
238+
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
239+
┃ ┏━━━━━━━━━━┓ pretalx v2024.1.0 ┃
240+
┃ ┃ ┌─·──╮ ┃ Settings: ┃
241+
┃ ┃ │ O │ ┃ Database: pretalx (postgresql) ┃
242+
┃ ┃ │ ┌──╯ ┃ Logging: /data/logs ┃
243+
┃ ┃ └─┘ ┃ Root dir: /pretalx/.local/lib/python3.10/site-packages/pretalx ┃
244+
┃ ┗━━━┯━┯━━━━┛ Python: /usr/local/bin/python ┃
245+
┃ ╰─╯ Plugins: pretalx_pages, pretalx_public_voting, prtx_faq ┃
246+
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
247+
248+
Welcome to pretalx! This is my initialization command, please use it only once.
249+
You can abort this command at any time using C-c, and it will save no data.
250+
251+
Let's get you a user with the right to create new events and access every event on this pretalx instance.
252+
E-mail:
253+
```
254+
255+
After finishing the questionnaire, you can login at http://localhost:8080/orga/.
256+
257+
> One of the first steps may very well be to disable telemetry and update notifications, when wanting to watch this from the outside perspective of tagged Container images.
258+
259+
As you can see, we are not using a settings file. This is not needed, due to following the dot env pattern for [12factor.net](https://12factor.net) cloud-native applications. An example for `pretalx.cfg` and how to add it to the containers is available in this repository, in case needed.
260+
261+
## Recycle
262+
263+
There are few lifecycle commands, which can help you reduce local resource usage. They are:
264+
265+
```
266+
docker compose -f compose.yml -f compose.local.yml -f compose.plugins.yml down --remove-orphans
267+
docker volume rm $(docker volume ls -q | grep pretalx)
268+
docker images | rg '<none>' | awk '{ print $3 }' | xargs docker rmi
269+
```
270+
271+
You can now start building images and creating containers from scratch.
272+
273+
Remove `.env` when you need to reset the whole setup completely.
274+
275+
## Authors
276+
277+
- Bastian Hodapp
278+
- Bruno Morisson
279+
- Daniel Goodman
280+
- Hadrien
281+
- Ian Foster
282+
- Johan Van de Wauw
283+
- Jon Richter
284+
- Jonathan Günz
285+
- Luca
286+
- Lukas
287+
- Marcus Müller
288+
- Matt Yaraskavitch
289+
- MaxR
290+
- Michal Stanke
291+
- Simeon Keske
292+
- Simon
293+
- Simon Hötten
294+
- Timon Erhart
295+
- Tobias Kunze
296+
- geleeroyale
297+
- jascha ehrenreich
298+
- kuhball
299+
- plaste
300+
- realitygaps
301+
302+
## License
303+
304+
CC0
305+
306+
## Copyright
307+
308+
© 2018—2024 Pretalx Community

0 commit comments

Comments
 (0)