pagetop-website/doc/v0.6/es/src/how-to/deployment.md
Manuel Cillero f42f5e9b89 📝 Add mail and file upload guides
Document pagetop-mail (configuration, templates, layout, previews,
queue and tests with the outbox) and file uploads (`web::Upload`,
`form::File`, `web::Download` and the [upload] settings). doccheck
enables the mail queue, keeps mail in memory and saves uploads under
`target/`.
2026-11-02 17:29:37 +01:00

5.2 KiB

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

cargo build --release

Para un binario más pequeño y rápido, añade a tu Cargo.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

/opt/my-app/
├── my-app            <- the binary
└── config/
    ├── common.toml
    ├── production.toml
    └── local.production.toml   <- secrets of this server
cd /opt/my-app
PAGETOP_RUN_MODE=production ./my-app

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.

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, espera a las tareas de pagetop-cron que estén en marcha y vuelca las trazas pendientes. Una unidad de systemd sencilla:

[Unit]
Description=My PageTop application
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

[Install]
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 Dockerfile en dos fases, que compila en una imagen de Rust y copia sólo el resultado:

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. 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

Para HTTPS, certificados y compresión, pon delante un proxy inverso como nginx o Caddy. Un ejemplo con nginx:

server {
    listen 443 ssl;
    server_name my-app.example.com;

    # ssl_certificate ... ssl_certificate_key ...

    # Allows uploads up to upload.max_request_size (nginx accepts 1 MiB by default).
    client_max_body_size 32m;

    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.

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:

[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

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