✨ Serve the PageTop guides with pagetop-mdbook

Rebuild the website on the current PageTop API, with Bootsier as its
theme and edition 2024. Add the first Spanish guide (doc/v0.6/es) as an
mdBook book, built in build.rs and served with pagetop-mdbook, and the
/doc/latest/{lang} redirect.

Add `tools/doccheck.sh` to check the links of the guides and to compile,
run and test their examples against PageTop.

Move the configuration to config/common.toml and translate the README
to English.
This commit is contained in:
Manuel Cillero 2026-10-17 08:06:02 +02:00
parent e41e71cc78
commit 1a41a456d4
80 changed files with 14112 additions and 1218 deletions

View file

@ -0,0 +1,133 @@
# Desplegar en producción
**Objetivo:** compilar la aplicación en modo optimizado y ponerla en marcha en un servidor, como
servicio del sistema o en un contenedor, detrás de un proxy inverso con HTTPS.
## 1. Compila para producción
```sh
cargo build --release
```
Para un binario más pequeño y rápido, añade a tu `Cargo.toml`:
```toml
[profile.release]
opt-level = 3
lto = "fat"
codegen-units = 1
strip = true
```
El ejecutable de `target/release/` incluye estilos, *scripts*, imágenes y traducciones. Sólo
necesita, a su lado, el directorio `config/`.
## 2. Ponla en marcha
```text
/opt/my-app/
├── my-app <- the binary
└── config/
├── common.toml
├── production.toml
└── local.production.toml <- secrets of this server
```
```sh
cd /opt/my-app
PAGETOP_RUN_MODE=production ./my-app
```
O, desde cualquier directorio, indicando dónde está la configuración:
```sh
CONFIG_DIR=/opt/my-app/config PAGETOP_RUN_MODE=production /opt/my-app/my-app
```
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:
```ini
[Unit]
Description=My PageTop application
After=network.target
[Service]
WorkingDirectory=/opt/my-app
Environment=PAGETOP_RUN_MODE=production
ExecStart=/opt/my-app/my-app
Restart=on-failure
User=my-app
[Install]
WantedBy=multi-user.target
```
## 4. En un contenedor
El binario no necesita nada a su lado salvo `config/`, así que la imagen final puede ser mínima. Un
`Dockerfile` en dos fases, que compila en una imagen de Rust y copia sólo el resultado:
```dockerfile
FROM rust:1.88 AS build
WORKDIR /src
COPY . .
RUN cargo build --release
FROM debian:bookworm-slim
WORKDIR /app
COPY --from=build /src/target/release/my-app /app/my-app
COPY config /app/config
ENV PAGETOP_RUN_MODE=production
EXPOSE 8080
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.
## 5. Detrás de un proxy inverso
Para HTTPS, certificados y compresión, pon delante un proxy inverso como nginx o Caddy. Un ejemplo
con nginx:
```nginx
server {
listen 443 ssl;
server_name my-app.example.com;
# ssl_certificate ... ssl_certificate_key ...
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
```
Con el proxy delante, deja `bind_address = "localhost"` (el valor por defecto): así sólo el proxy
llega a la aplicación.
## Comprueba
```sh
curl -I https://my-app.example.com/
```
Responde `200` a través del proxy. En el servidor, `systemctl status my-app` (o `docker logs`)
muestra las trazas de arranque, y `systemctl stop my-app` detiene la aplicación sin cortar las
peticiones en curso.
## Siguiente
- [Registrar trazas](logging.md): trazas en archivos con rotación.
- [Opciones de configuración](../reference/configuration.md).