Añadir documentación de integración con NPM
1
Home.md
1
Home.md
@@ -84,6 +84,7 @@ https://<IP-del-servidor>: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
|
||||
|
||||
252
NPM.md
Normal file
252
NPM.md
Normal file
@@ -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)
|
||||
Reference in New Issue
Block a user