📝 Doc cron, mail queue, CSRF and flash messages

Add the scheduled tasks guide, environment variable overrides, the
[mail] and [cron] references, CSRF protection without tokens, flash
messages after redirects and the username policies of pagetop-user.
Update the framework comparison with Poem and Topcoat.
This commit is contained in:
Manuel Cillero 2026-11-02 14:46:28 +01:00
parent 1a41a456d4
commit 4e007feec8
23 changed files with 946 additions and 125 deletions

View file

@ -44,14 +44,19 @@ O, desde cualquier directorio, indicando dónde está la configuración:
CONFIG_DIR=/opt/my-app/config PAGETOP_RUN_MODE=production /opt/my-app/my-app
```
Los secretos pueden ir también en variables de entorno en lugar de `local.production.toml`:
cualquier clave se sobrescribe con `PAGETOP_<SECCIÓN>__<CLAVE>` (p. ej.
`PAGETOP_DATABASE__DB_PASS`), como explica la
[referencia de la configuración](../reference/configuration.md).
Recuerda que, por defecto, el servidor sólo escucha en `localhost`. Para aceptar conexiones de
fuera, o de un proxy en otro equipo, fija `bind_address = "0.0.0.0"` en `[server]`.
## 3. Como servicio del sistema
PageTop se detiene de forma ordenada con `SIGTERM`, la señal que envían `systemd` o Docker: deja de
aceptar conexiones, termina las peticiones en curso y vuelca las trazas pendientes. Una unidad de
`systemd` sencilla:
aceptar conexiones, termina las peticiones en curso, espera a las tareas de `pagetop-cron` que estén
en marcha y vuelca las trazas pendientes. Una unidad de `systemd` sencilla:
```ini
[Unit]
@ -61,6 +66,7 @@ After=network.target
[Service]
WorkingDirectory=/opt/my-app
Environment=PAGETOP_RUN_MODE=production
EnvironmentFile=-/etc/my-app/secrets.env
ExecStart=/opt/my-app/my-app
Restart=on-failure
User=my-app
@ -69,6 +75,9 @@ User=my-app
WantedBy=multi-user.target
```
`EnvironmentFile` es opcional (el `-` lo admite ausente): un archivo legible sólo por `root`, con
una variable por línea, como `PAGETOP_DATABASE__DB_PASS=secret`.
## 4. En un contenedor
El binario no necesita nada a su lado salvo `config/`, así que la imagen final puede ser mínima. Un
@ -91,7 +100,8 @@ CMD ["/app/my-app"]
Dentro del contenedor, el servidor debe escuchar en todas las interfaces: pon
`bind_address = "0.0.0.0"` en `config/production.toml`. Docker detiene los contenedores con
`SIGTERM`, que PageTop atiende cerrando de forma ordenada.
`SIGTERM`, que PageTop atiende cerrando de forma ordenada. Los secretos no van en la imagen: se
pasan al arrancar el contenedor, por ejemplo con `docker run --env-file secrets.env`.
## 5. Detrás de un proxy inverso
@ -117,6 +127,24 @@ server {
Con el proxy delante, deja `bind_address = "localhost"` (el valor por defecto): así sólo el proxy
llega a la aplicación.
Todas las conexiones llegan entonces desde el proxy. Para que la aplicación conozca la dirección de
cada visitante, que usan por ejemplo los límites por IP de `pagetop-user`, indica la cabecera en
la que el proxy la escribe:
```toml
[server]
client_ip_header = "X-Forwarded-For"
```
Si la cabecera trae varias direcciones, vale la última, la que añade el proxy: las anteriores las
envía el navegador y podrían ser falsas. Configúrala sólo si todas las peticiones pasan por el
proxy y éste escribe siempre la cabecera, como hace `$proxy_add_x_forwarded_for` en el ejemplo.
Conserva la línea `proxy_set_header Host $host;`. La protección contra CSRF compara la cabecera
`Origin` del navegador con `Host` cuando el navegador no envía `Sec-Fetch-Site` (los antiguos, o
cualquiera en una conexión HTTP sin cifrar fuera de `localhost`). Si el proxy cambia `Host` por
`127.0.0.1:8080`, esos navegadores reciben un `403` al enviar cualquier formulario.
## Comprueba
```sh
@ -130,4 +158,6 @@ peticiones en curso.
## Siguiente
- [Registrar trazas](logging.md): trazas en archivos con rotación.
- [Programar tareas periódicas](cron.md#6-con-varias-instancias-elige-el-modo): con varias
instancias, quién ejecuta las tareas.
- [Opciones de configuración](../reference/configuration.md).