groales/npm

Fork 0

Table of Contents

NGINX Proxy Manager - Documentación

¿Qué es NGINX Proxy Manager?
Características Principales

Gestión de Proxy Hosts
SSL/TLS
Seguridad

Componentes del Stack

Servicio Principal
Puertos Expuestos
Volúmenes
Red

Requisitos Previos
Despliegue Rápido

1. Clonar el Repositorio
2. Levantar el Stack
3. Verificar el Estado
4. Acceder a la Interfaz Web
5. Login Inicial

Primer Proxy Host (Guía Rápida)

Ejemplo: Exponer Portainer con SSL

Casos de Uso Comunes

1. Proxy a Contenedores Docker en la Misma Red
2. Redirección Permanente
3. Stream TCP (Ejemplo: SSH)
4. Access List (Restringir por IP)

Próximos Pasos
Troubleshooting Rápido
Recursos Oficiales

NGINX Proxy Manager - Documentación

Bienvenido a la documentación del despliegue de NGINX Proxy Manager usando Docker Compose.

¿Qué es NGINX Proxy Manager?

NGINX Proxy Manager (NPM) es una interfaz de gestión intuitiva para configurar y administrar proxy inversos NGINX sin necesidad de conocimientos profundos de NGINX. Ideal para:

🏠 Self-hosting casero - Exponer servicios locales a Internet de forma segura
🔒 Certificados SSL automáticos - Let's Encrypt integrado con renovación automática
🌐 Múltiples dominios - Gestionar decenas o cientos de proxy hosts desde una UI
📱 Interfaz moderna - Administración web responsive y fácil de usar
🔐 Control de acceso - Listas de acceso y autenticación básica HTTP

Características Principales

Gestión de Proxy Hosts

Proxy Hosts: Redirigir dominios a servicios backend (HTTP/HTTPS)
Redirection Hosts: Redirecciones 301/302 permanentes o temporales
404 Hosts: Páginas personalizadas para dominios no configurados
Streams: Proxy TCP/UDP para servicios no-HTTP (SSH, bases de datos, etc.)

SSL/TLS

✅ Let's Encrypt gratuito con renovación automática
✅ Certificados personalizados (upload de cert + key)
✅ Wildcard certificates vía DNS challenge
✅ HTTP/2 y HTTP/3 (QUIC) support
✅ Force SSL (redirección automática HTTP → HTTPS)
✅ HSTS (HTTP Strict Transport Security)

Seguridad

🔐 Access Lists - Restricción por IP, username/password
🛡️ Headers personalizados - X-Frame-Options, CSP, CORS
🚫 Bloqueo de exploits comunes - Configuración NGINX hardening
🔑 Gestión de usuarios - Multi-usuario con roles y permisos

Componentes del Stack

Este repositorio despliega NPM con la siguiente configuración:

Servicio Principal

Imagen: jc21/nginx-proxy-manager:latest
Contenedor: nginx-proxy-manager
Reinicio: unless-stopped

Puertos Expuestos

80: HTTP público (redirige automáticamente a HTTPS)
81: Interfaz web de administración
443: HTTPS público

Volúmenes

npm_data → /data - Base de datos SQLite, configuraciones, logs
npm_letsencrypt → /etc/letsencrypt - Certificados SSL de Let's Encrypt

Red

proxy - Red externa compartida con otros servicios

Requisitos Previos

Antes de desplegar NPM, asegúrate de tener:

✅ Docker Engine y Docker Compose instalados
✅ Puertos 80, 443 y 81 disponibles (o configurar puertos alternativos)
✅ Dominio(s) apuntando al servidor (para certificados SSL)
✅ Acceso a Internet (para validación de Let's Encrypt)
✅ Firewall configurado para permitir tráfico en puertos 80/443

Despliegue Rápido

1. Clonar el Repositorio

git clone https://git.ictiberia.com/groales/npm
cd npm

2. Levantar el Stack

docker compose up -d

3. Verificar el Estado

docker ps --filter name=nginx-proxy-manager
docker logs nginx-proxy-manager

4. Acceder a la Interfaz Web

Abre tu navegador en: http://IP-del-servidor:81

⏱️ Primera vez: El inicio puede tardar 1-2 minutos. Espera a ver en los logs:

[setup ] Starting backend

Credenciales por defecto:

Email:    admin@example.com
Password: changeme

🔒 Obligatorio: Al primer login, se te pedirá:

Cambiar el email
Cambiar el nombre de usuario
Establecer una nueva contraseña

Primer Proxy Host (Guía Rápida)

Ejemplo: Exponer Portainer con SSL

Supongamos que tienes Portainer corriendo en 192.168.1.100:9443 y quieres acceder via https://portainer.tudominio.com.

Ir a "Hosts" → "Proxy Hosts" → "Add Proxy Host"
Pestaña "Details":
- Domain Names: portainer.tudominio.com
- Scheme: https (Portainer usa HTTPS)
- Forward Hostname / IP: 192.168.1.100
- Forward Port: 9443
- Cache Assets: ✅ (opcional)
- Block Common Exploits: ✅
- Websockets Support: ✅ (necesario para Portainer)
Pestaña "SSL":
- ✅ Request a new SSL Certificate with Let's Encrypt
- ✅ Force SSL (redirigir HTTP → HTTPS)
- ✅ HTTP/2 Support
- ✅ HSTS Enabled (opcional, recomendado)
- Email: tu@email.com (para notificaciones de Let's Encrypt)
- ✅ I Agree to the Let's Encrypt Terms of Service
Save

✅ En 10-30 segundos, el certificado SSL se generará y el proxy estará activo.

Accede a: https://portainer.tudominio.com 🎉

Casos de Uso Comunes

1. Proxy a Contenedores Docker en la Misma Red

Si tienes servicios corriendo en Docker en el mismo host:

# En el docker-compose.yml de tu servicio
networks:
  - proxy

networks:
  proxy:
    external: true

Luego en NPM:

Forward Hostname: Nombre del contenedor (ej: portainer)
Forward Port: Puerto interno del contenedor (no el publicado)

2. Redirección Permanente

Ejemplo: Redirigir www.tudominio.com → tudominio.com

"Hosts" → "Redirection Hosts" → "Add Redirection Host"
Domain Names: www.tudominio.com
Scheme: https
Forward Domain Name: tudominio.com
Preserve Path: ✅
HTTP Code: 301 (permanente)
SSL: Solicitar certificado para www.tudominio.com

3. Stream TCP (Ejemplo: SSH)

Objetivo: Acceder a SSH del servidor via puerto 2222 externo.

"Streams" → "Add Stream"
Incoming Port: 2222
Forwarding Host: 127.0.0.1 (localhost)
Forwarding Port: 22 (SSH)
TCP Forwarding: ✅
Save

Añadir puerto al docker-compose.yml:

ports:
  - "80:80"
  - "81:81"
  - "443:443"
  - "2222:2222"  # Stream SSH

Reiniciar: docker compose up -d

Conectar: ssh usuario@IP-servidor -p 2222

4. Access List (Restringir por IP)

"Access Lists" → "Add Access List"
Name: Solo oficina
Pass Auth: ✅ (si quieres autenticación adicional)
Authorization → Add → Username: admin, Password: ***
Access → Allow → 192.168.1.0/24 (red local)
Access → Deny → 0.0.0.0/0 (todo lo demás)
Save

Aplicar a Proxy Host:

Editar Proxy Host → Access List: Seleccionar "Solo oficina"

Próximos Pasos

📖 Configuración Avanzada - MySQL, secrets, custom NGINX configs
🔒 Certificados SSL/TLS - Wildcard, DNS challenge, certificados propios

Troubleshooting Rápido

Problema	Solución
Puerto 80/443 ocupado	Ver proceso: `sudo netstat -tulpn \| grep :80`, cambiar puertos en compose
No se genera certificado SSL	Verificar DNS apunta al servidor, puertos 80/443 abiertos en firewall
Olvido de contraseña	Resetear credenciales a valores por defecto (ver documentación oficial)
Error "Address family not supported"	Añadir `DISABLE_IPV6: 'true'` en environment
502 Bad Gateway	Verificar que el backend esté corriendo y el puerto correcto

Recursos Oficiales

Versión: Latest (rolling release)
Última actualización: Noviembre 2025