Nginx Proxy Manager (NPM) sobre Proxmox — un solo punto de entrada TLS

Recursos más chicos que Zabbix/GLPI porque NPM es un solo container liviano: 1 vCPU / 2 GB / 20 GB alcanzan sobrado para < 200 proxy hosts.

qm clone 9000 232 \
  --name npm-lab \
  --description "Nginx Proxy Manager · Ubuntu 24.04 · lab Harper" \
  --full 0 --pool lab

qm set 232 --cores 1 --sockets 1 --cpu host --memory 2048 --balloon 0
qm resize 232 scsi0 20G

qm set 232 \
  --ciuser rbatista \
  --sshkeys ~/.ssh/dojo_authorized_keys \
  --ipconfig0 ip=192.168.0.232/24,gw=192.168.0.1 \
  --nameserver "192.168.0.1 1.1.1.1" \
  --searchdomain lab.harper.local

qm cloudinit update 232
qm set 232 --onboot 1
qm start 232

until qm agent 232 ping 2>/dev/null; do echo "esperando cloud-init..."; sleep 5; done
qm agent 232 network-get-interfaces | jq -r '.[] | select(.name!="lo").["ip-addresses"][]?."ip-address"'

ssh rbatista@192.168.0.232 "hostnamectl; lsb_release -d; ip -brief a"

3.1 Añadir el repo Docker

sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] \
https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list

sudo apt update

3.2 Instalar Engine + Compose + Buildx

sudo apt -y install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Añadir rbatista al grupo docker (para no sudo cada comando).
sudo usermod -aG docker rbatista

# Habilitar al boot.
sudo systemctl enable --now docker

# Verificar versiones.
sudo docker version
sudo docker compose version

docker run --rm hello-world

4.1 Crear la estructura de directorios

Los dos volúmenes críticos son data/ (configs, SQLite, custom nginx snippets) y letsencrypt/ (certs emitidos). Todo lo demás es efímero.

sudo mkdir -p /opt/npm/{data,letsencrypt}
sudo chown -R rbatista:rbatista /opt/npm
cd /opt/npm

4.2 Escribir el docker-compose.yml

Usamos SQLite (default). Es más que suficiente hasta ~200 proxy hosts. Si el cliente supera esa escala o quiere HA, se migra a MariaDB añadiendo un service db: y las variables DB_MYSQL_* (documentado al final del tutorial).

tee /opt/npm/docker-compose.yml >/dev/null <<'EOF'
name: npm

services:
  app:
    image: 'jc21/nginx-proxy-manager:2'
    container_name: npm
    restart: unless-stopped
    ports:
      - '80:80'      # HTTP público (proxy)
      - '443:443'    # HTTPS público (proxy)
      - '81:81'      # Admin UI — protegida por UFW a la LAN
    environment:
      DISABLE_IPV6: 'true'          # simplifica logs en clientes IPv4-only
      TZ: America/Santo_Domingo
    volumes:
      - ./data:/data
      - ./letsencrypt:/etc/letsencrypt
    healthcheck:
      test: ["CMD", "/usr/bin/check-health"]
      interval: 30s
      timeout: 5s
      retries: 5
EOF

4.3 Levantar el stack

cd /opt/npm
docker compose up -d
docker compose ps
docker compose logs -f --tail 20 app
# Ctrl+C para salir del log una vez veas "Backend PID X listening on port 3000"

5.1 Login default

NPM crea al primer boot un usuario admin con credenciales conocidas PÚBLICAMENTE — es el equivalente al zabbix/zabbix del otro tutorial. Cambiarlo es OBLIGATORIO antes de crear cualquier proxy host.

1. Abrir http://192.168.0.232:81/ en el navegador.
2. Login:
   • Email: admin@example.com
   • Password: changeme
3. NPM fuerza cambio de datos en el mismo momento:
   • Full name: Ramces Batista (o el operador del cliente)
   • Nickname: Ramces
   • Email: infra@har-per.com (email real del cliente)
4. Password nuevo, mínimo 8 chars, con complejidad.

5.2 Crear usuarios adicionales (opcional)

Si el cliente tiene un equipo de infra que va a operar NPM, crea usuarios por técnico con permisos limitados en vez de compartir el admin.

1. Menú superior derecho → Users → Create User.
2. Marcar los permisos por sección — para técnicos operativos suele bastar: Proxy Hosts: Manage, Access Lists: View Only, Streams: Hidden, Redirection Hosts: Manage, 404 Hosts: Hidden.

6.1 Confirmar DNS público

Cada FQDN debe resolver a la IP pública del cliente. Ejemplo con Zabbix y GLPI:

dig +short zbx.cliente.com
dig +short glpi.cliente.com
# Ambos deben devolver la IP pública del router del cliente.

6.2 Confirmar NAT/port-forward en el router del cliente

Todo tráfico entrante en 80/tcp y 443/tcp desde internet debe redirigirse a 192.168.0.232 (VM de NPM). Esto se configura en el router del cliente (FortiGate, Aruba, TP-Link, etc.). En FortiGate: Policy & Objects → Virtual IPs.

# Test que el 80 esté abierto y llegue a NPM (que responde con la landing "Congratulations!" cuando no hay proxy host).
curl -I http://zbx.cliente.com/
# Debe responder 200 y contener 'nginx' en el header Server.

7.1 Ruta A · HTTP-01 (por FQDN, más simple)

1. UI NPM → SSL Certificates → Add SSL Certificate → Let's Encrypt.
2. Domain names: zbx.cliente.com (uno por línea si quieres varios).
3. Email para Let's Encrypt: infra@har-per.com.
4. Aceptar los TOS. Use DNS Challenge: OFF.
5. Save. Espera ~15 segundos. Debe aparecer en verde bajo SSL Certificates.

7.2 Ruta B · DNS-01 wildcard (con Cloudflare, ejemplo)

1. En Cloudflare: My Profile → API Tokens → Create Token → template "Edit zone DNS" → seleccionar la zona del cliente. Copiar el token.
2. UI NPM → SSL Certificates → Add SSL Certificate → Let's Encrypt.
3. Domain names: *.cliente.com, cliente.com.
4. Use DNS Challenge: ON. DNS Provider: Cloudflare. Credentials File Content: dns_cloudflare_api_token=EL_TOKEN_COPIADO.
5. Propagation seconds: 30.
6. Save. Tarda ~1 minuto (espera a que el DNS propague).

8.1 Añadir el proxy host

1. UI NPM → Hosts → Proxy Hosts → Add Proxy Host.
2. Details:
   • Domain Names: zbx.cliente.com
   • Scheme: http
   • Forward Hostname/IP: 192.168.0.230 (IP de la VM Zabbix)
   • Forward Port: 80
   • Cache Assets: ON
   • Block Common Exploits: ON
   • Websockets Support: ON (Zabbix 7.0 lo usa en algunas secciones de la GUI)
3. SSL:
   • SSL Certificate: seleccionar el cert emitido en la fase 7.
   • Force SSL: ON
   • HTTP/2 Support: ON
   • HSTS Enabled: ON (después de confirmar que todo funciona por HTTPS — activar HSTS antes puede dejar clientes cacheados en HTTPS si rompes algo).
   • HSTS Subdomains: OFF (solo activar si TODOS los subdominios del cliente estarán en HTTPS — poco común).
4. Save.

9.1 Añadir el proxy host

Mismos pasos que la fase 8, cambiando datos:

• Domain Names: glpi.cliente.com
• Forward Hostname/IP: 192.168.0.231
• Forward Port: 80
• SSL con Force SSL + HTTP/2 (igual)
• Cache Assets + Block Common Exploits + Websockets — todos ON.

9.2 Ajuste crítico en GLPI para funcionar detrás de proxy

La solución es enseñarle a GLPI que confíe en el header X-Forwarded-Proto que NPM ya está pasando:

sudo tee -a /etc/glpi/local_define.php >/dev/null <<'EOF'

// --- Trust proxy: NPM al frente ---
if (isset($_SERVER['HTTP_X_FORWARDED_PROTO']) && $_SERVER['HTTP_X_FORWARDED_PROTO'] === 'https') {
    $_SERVER['HTTPS'] = 'on';
    $_SERVER['SERVER_PORT'] = 443;
}
EOF

sudo systemctl restart php8.3-fpm

9.3 Custom Nginx Configuration en NPM (opcional, headers extra)

Por defecto NPM ya pasa X-Forwarded-For, X-Forwarded-Proto, Host. Si necesitas afinar (ej. subir el client_max_body_size para que GLPI acepte adjuntos grandes en tickets), añade custom:

1. Editar el proxy host de GLPI → tab Advanced.
2. Pegar:

client_max_body_size 25M;
proxy_read_timeout   600;
proxy_send_timeout   600;
proxy_set_header X-Real-IP        $remote_addr;
proxy_set_header X-Forwarded-For  $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Host             $host;

Access Lists son una capa previa a la aplicación. NPM valida IP o credenciales HTTP Basic y solo si pasa, deja llegar el request al backend. Útil en dos escenarios:

• Restringir GLPI a la LAN corp del cliente + VPN — nada de acceso público aunque el DNS resuelva.
• Doble autenticación para dashboards internos (login del jefe + login de la app).

10.1 Crear una Access List "corp-only"

1. UI NPM → Access Lists → Add Access List.
2. Name: corp-only.
3. Satisfy Any: OFF (requiere pasar todas las reglas).
4. Pass Auth to Host: OFF (no forwardear las credenciales HTTP al back-end).
5. Tab Authorization: Allow: 192.168.0.0/24, 203.0.113.10 (IP pública corp), etc.
   (Al final: Deny all implícito).
6. Tab Access: si quieres HTTP Basic Auth encima, añade user/password.
7. Save.

10.2 Aplicar al Proxy Host

Editar el proxy host de GLPI → sección Access List → seleccionar corp-only. Save. Cualquier request desde afuera de esas IPs recibe 403 Forbidden antes de siquiera tocar GLPI.

11.1 Script

NPM entero cabe en un tar. La DB es SQLite dentro de data/, y los certs dentro de letsencrypt/. Sin nada más que respaldar. Si el cliente migró a MariaDB, añade un mariadb-dump al script.

sudo tee /usr/local/sbin/npm-backup.sh >/dev/null <<'EOF'
#!/usr/bin/env bash
# Backup nocturno de Nginx Proxy Manager — Harper.
# Los dos volúmenes bindeados en /opt/npm son toda la persistencia.
set -euo pipefail

BACKUP_DIR=/var/backups/npm
STAMP=$(date +%F_%H%M)
mkdir -p "$BACKUP_DIR"

# Detener brevemente NPM para consistencia de SQLite (segundos).
docker compose -f /opt/npm/docker-compose.yml stop app

tar -C /opt/npm -czf "$BACKUP_DIR/npm-$STAMP.tar.gz" data letsencrypt

docker compose -f /opt/npm/docker-compose.yml start app

# Retención: 14 más recientes.
ls -1t "$BACKUP_DIR"/npm-*.tar.gz | tail -n +15 | xargs -r rm --

logger -t npm-backup "backup OK · $STAMP · $(du -sh $BACKUP_DIR | cut -f1)"
EOF

sudo chmod 700 /usr/local/sbin/npm-backup.sh
sudo /usr/local/sbin/npm-backup.sh    # test manual
ls -lh /var/backups/npm/

11.2 Timer systemd

sudo tee /etc/systemd/system/npm-backup.service >/dev/null <<'EOF'
[Unit]
Description=NPM nightly backup (data + letsencrypt)
After=docker.service

[Service]
Type=oneshot
ExecStart=/usr/local/sbin/npm-backup.sh
EOF

sudo tee /etc/systemd/system/npm-backup.timer >/dev/null <<'EOF'
[Unit]
Description=Trigger npm-backup.service cada noche a las 03:00

[Timer]
OnCalendar=*-*-* 03:00:00
Persistent=true
RandomizedDelaySec=5m

[Install]
WantedBy=timers.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now npm-backup.timer
sudo systemctl list-timers npm-backup.timer

12.1 Ficha de servicio

12.2 Checklist de entrega

• VM boots limpia, Ubuntu 24.04 actualizado, UFW activo con 22/80/443/(81 LAN) abiertos.
• SSH sin password ni root login.
• Docker Engine + compose plugin oficiales, no docker.io del repo Ubuntu.
• Container npm Up y healthy.
• UI NPM accesible en http://IP:81/ (SOLO LAN).
• Usuario default admin@example.com cambiado por uno del cliente.
• DNS público resolviendo a la IP pública para cada FQDN a proxear.
• NAT/port-forward en el router del cliente: 80/443 público → 192.168.0.232.
• Al menos un cert Let's Encrypt emitido (HTTP-01 o DNS-01).
• Al menos un Proxy Host funcionando bajo HTTPS con Force SSL + HTTP/2.
• SSLLabs test devuelve Grade A o A+ para el FQDN de prueba.
• GLPI (si aplica) con local_define.php ajustado para el proxy.
• Timer npm-backup.timer activo, primer backup manual OK.
• Snapshot Proxmox "post-handoff".
• Ficha 12.1 rellena y compartida con el cliente.

12.3 Cheatsheet operativo

12.4 Migración a MariaDB (cuando el cliente escala > 50 servicios)

Si el cliente crece a decenas o cientos de proxy hosts y notas la UI lenta, migra la DB de SQLite a MariaDB:

services:
  app:
    image: 'jc21/nginx-proxy-manager:2'
    ...
    environment:
      DB_MYSQL_HOST: 'db'
      DB_MYSQL_PORT: 3306
      DB_MYSQL_USER: 'npm'
      DB_MYSQL_PASSWORD: 'CAMBIAR_PASSWORD_FUERTE'
      DB_MYSQL_NAME: 'npm'
      DISABLE_IPV6: 'true'
      TZ: America/Santo_Domingo
    depends_on:
      - db

  db:
    image: 'mariadb:10.11'
    restart: unless-stopped
    environment:
      MARIADB_ROOT_PASSWORD: 'ROOT_PASSWORD_FUERTE'
      MARIADB_DATABASE: 'npm'
      MARIADB_USER: 'npm'
      MARIADB_PASSWORD: 'CAMBIAR_PASSWORD_FUERTE'
    volumes:
      - ./mysql:/var/lib/mysql