diff --git a/Home.md b/Home.md index 784451c..fe1fda2 100644 --- a/Home.md +++ b/Home.md @@ -84,6 +84,7 @@ https://:9443 ## Próximos Pasos - 🌐 [Integración con Traefik](Traefik) - Configurar proxy inverso con TLS automático +- 🌐 [Integración con NPM](NPM) - Configurar NGINX Proxy Manager - 🔌 [Edge Agents](Edge-Agents) - Gestionar entornos remotos con agentes Edge ## Solución Rápida de Problemas diff --git a/NPM.md b/NPM.md new file mode 100644 index 0000000..a7366a5 --- /dev/null +++ b/NPM.md @@ -0,0 +1,252 @@ +# Integración con NGINX Proxy Manager + +Esta guía explica cómo integrar Portainer CE con **NGINX Proxy Manager (NPM)** como proxy inverso para obtener: + +- 🔒 **Certificados SSL/TLS automáticos** con Let's Encrypt +- 🌐 **Acceso mediante dominio** en lugar de IP:puerto +- 📊 **Interfaz gráfica** para gestión de proxies + +## Requisitos Previos + +- ✅ NPM desplegado desde el repositorio `groales/npm` +- ✅ Red Docker compartida `proxy` +- ✅ Dominio apuntando a tu servidor +- ✅ Puertos 80 y 443 accesibles desde Internet + +## Arquitectura + +``` +Internet → NPM (80/443) → Portainer (9443) + ↓ + Let's Encrypt +``` + +## Configuración + +### 1. Verificar Red Compartida + +Asegúrate de que la red `proxy` existe (creada por el repo de NPM): + +```bash +docker network ls | grep proxy +``` + +### 2. Crear docker-compose.override.yml + +En el directorio de Portainer, copia el ejemplo: + +```bash +cd ~/portainer # O tu ruta local +cp docker-compose.override.npm.yml.example docker-compose.override.yml +``` + +El archivo solo conecta Portainer a la red `proxy`: + +```yaml +services: + portainer: + networks: + - proxy + +networks: + proxy: + external: true +``` + +### 3. Reiniciar Portainer + +```bash +docker compose down +docker compose up -d +``` + +### 4. Verificar Conectividad + +```bash +# Ver que Portainer está en la red proxy +docker network inspect proxy | grep portainer +``` + +### 5. Configurar Proxy Host en NPM + +Accede a la interfaz de NPM (puerto 81) y crea un nuevo Proxy Host: + +#### Pestaña "Details" + +- **Domain Names**: `portainer.tudominio.com` +- **Scheme**: `https` (Portainer usa HTTPS) +- **Forward Hostname / IP**: `portainer` (nombre del contenedor) +- **Forward Port**: `9443` +- **Cache Assets**: ❌ (no recomendado para apps dinámicas) +- **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** + +#### Pestaña "Advanced" (Opcional) + +Si tienes problemas con el certificado autofirmado de Portainer, añade: + +```nginx +proxy_ssl_verify off; +``` + +**Nota**: NPM maneja automáticamente las conexiones HTTPS al backend. + +### 6. Guardar y Verificar + +- Click en **Save** +- Espera 10-30 segundos para la generación del certificado +- Accede a: `https://portainer.tudominio.com` + +## Configuración Avanzada + +### Restricción por IP + +En NPM, puedes crear una **Access List** para restringir el acceso: + +1. **Access Lists** → **Add Access List** +2. **Name**: `Solo oficina` +3. **Access** → **Allow** → Añadir IPs/rangos permitidos (ej: `192.168.1.0/24`) +4. **Access** → **Deny** → `0.0.0.0/0` (denegar todo lo demás) +5. **Save** + +Luego aplícala al Proxy Host de Portainer: +- Editar Proxy Host → **Access List** → Seleccionar "Solo oficina" + +### Autenticación HTTP Básica + +Si quieres capa adicional de autenticación: + +1. En la **Access List**, marca **Pass Auth** +2. **Authorization** → **Add** + - **Username**: `admin` + - **Password**: `tu_password` +3. **Save** + +### Custom NGINX Configuration + +En la pestaña **Advanced** del Proxy Host, puedes añadir configuración personalizada: + +```nginx +# Rate limiting +limit_req zone=general burst=20 nodelay; + +# Headers de seguridad adicionales +add_header X-Frame-Options "SAMEORIGIN" always; +add_header X-Content-Type-Options "nosniff" always; +add_header Referrer-Policy "no-referrer-when-downgrade" always; +``` + +## Troubleshooting + +### Error 502 Bad Gateway + +1. **Verificar red compartida**: + ```bash + docker network inspect proxy + ``` + +2. **Verificar que Portainer está corriendo**: + ```bash + docker ps | grep portainer + ``` + +3. **Ver logs de NPM**: + ```bash + docker logs nginx-proxy-manager + ``` + +4. **Ver logs de Portainer**: + ```bash + docker logs portainer + ``` + +### Error 503 Service Unavailable + +- Verifica el nombre del contenedor: debe ser `portainer` (coincide con **Forward Hostname**) +- Verifica el puerto: debe ser `9443` +- Asegúrate de que Portainer está en la red `proxy` + +### Certificado No Se Genera + +1. **Verificar DNS**: + ```bash + nslookup portainer.tudominio.com + ``` + +2. **Verificar puertos 80/443** accesibles desde Internet + +3. **Ver logs de certificados en NPM**: + - NPM UI → **SSL Certificates** → Ver estado del certificado + +### Error de Certificado Autofirmado + +Si NPM no puede conectar con el backend HTTPS de Portainer: + +En **Advanced** del Proxy Host, añade: +```nginx +proxy_ssl_verify off; +``` + +Esto hace que NPM acepte el certificado autofirmado de Portainer. + +**Nota**: El usuario final ve el certificado válido de Let's Encrypt, no el autofirmado. + +### Websockets No Funcionan + +Asegúrate de que **Websockets Support** está habilitado en el Proxy Host. Sin esto, Portainer puede mostrar errores de conexión en tiempo real. + +## Comparación NPM vs Traefik + +| Característica | NPM | Traefik | +|----------------|-----|---------| +| Configuración | Interfaz gráfica | Archivos YAML/labels | +| Curva de aprendizaje | Baja | Media | +| Automatización | Manual | Automática (labels) | +| Wildcards SSL | Sí (DNS challenge) | Sí (DNS challenge) | +| Middlewares | Custom NGINX | Middlewares integrados | +| Mejor para | Pocos servicios, gestión manual | Muchos servicios, infraestructura dinámica | + +## Ejemplo Completo + +### docker-compose.override.yml + +```yaml +services: + portainer: + networks: + - proxy + +networks: + proxy: + external: true +``` + +### Configuración en NPM (UI) + +**Proxy Host**: +- Domain: `portainer.tudominio.com` +- Forward: `https://portainer:9443` +- ✅ SSL Certificate (Let's Encrypt) +- ✅ Force SSL +- ✅ Websockets Support + +**Access List** (opcional): +- Allow: `192.168.0.0/16`, `172.16.0.0/12`, `10.0.0.0/8` +- Deny: `0.0.0.0/0` + +--- + +**Recursos adicionales**: +- [Repositorio NPM](https://git.ictiberia.com/groales/npm) +- [Wiki NPM](https://git.ictiberia.com/groales/npm/wiki) + +**Volver a**: [Página Principal](Home)