Portainer/README.md

Portainer Stacks Repository

Este repositorio contiene la configuración de Portainer y múltiples stacks de servicios Docker gestionados mediante Docker Compose.

📋 Tabla de Contenidos

• Descripción
• Arquitectura
• Prerequisitos
• Instalación y Despliegue
• Stacks Disponibles
• Configuración
• Uso

📖 Descripción

Este proyecto proporciona una infraestructura completa de servicios containerizados utilizando:

• Portainer como gestor visual de contenedores Docker
• Traefik como reverse proxy con certificados SSL automáticos
• Authentik para autenticación SSO
• Múltiples servicios adicionales (Gitea, n8n, AdGuard, etc.)

🏗️ Arquitectura

La arquitectura sigue este orden de despliegue:

1. Portainer (gestor de contenedores) - acceso directo por puerto 9443
2. Traefik (reverse proxy) - desplegado desde Portainer
3. Authentik (SSO) - desplegado desde Portainer
4. Resto de stacks - desplegables desde Portainer

Todos los servicios se comunican a través de la red Docker proxy y están protegidos por Traefik con SSL.

⚠️ Importante: Los registros DNS deben estar configurados ANTES de desplegar Traefik y Authentik para que los certificados SSL se generen correctamente.

✅ Prerequisitos

• Docker Engine (20.10+)
• Docker Compose (v2.0+)
• Dominio(s) configurado(s) apuntando a tu servidor
• Puertos 80 y 443 abiertos (o 9443 para modo directo)

🚀 Instalación y Despliegue

Paso 1: Clonar el Repositorio

git clone <repository-url>
cd Portainer_repo

Paso 2: Crear la Red de Docker

Todos los servicios comparten la red proxy:

docker network create proxy

Paso 3: Preparar Secretos de Portainer

Crea el archivo de secreto para la clave de cifrado de Portainer:

# Crear directorio para secretos
sudo mkdir -p /opt/portainer/secrets

# Generar una clave aleatoria de 32 caracteres
openssl rand -base64 32 | sudo tee /opt/portainer/secrets/portainer

# Asegurar permisos correctos
sudo chmod 600 /opt/portainer/secrets/portainer

Paso 4: Desplegar Portainer (PRIMERO)

Despliega Portainer con acceso directo por puerto 9443:

docker compose -f docker-compose.9443.yml up -d

Verifica que Portainer esté corriendo:

docker ps | grep portainer

Accede a: https://tu-servidor:9443

Paso 5: Configuración Inicial de Portainer

1. Accede a Portainer mediante https://tu-servidor:9443
2. Crea el usuario administrador (primera vez - tienes 5 minutos)
3. Selecciona el entorno Docker local
4. Completa la configuración inicial

Paso 6: Configurar Registros DNS

Antes de desplegar Traefik y Authentik, configura los registros DNS:

• Registro A para Traefik Dashboard (ej: traefik.tudominio.com)
• Registro A para Portainer UI (ej: portainer.tudominio.com)
• Registro A para Portainer API (ej: portainer-api.tudominio.com)
• Registro A para Authentik (ej: auth.tudominio.com)
• Cualquier otro dominio que vayas a usar

⏰ Espera a que los registros DNS se propaguen antes de continuar (puede tardar de minutos a horas).

Verifica la propagación:

nslookup traefik.tudominio.com
nslookup portainer.tudominio.com
nslookup auth.tudominio.com

Paso 7: Desplegar Traefik desde Portainer

1. En Portainer, ve a Stacks → Add stack
2. Nombre: traefik
3. Selecciona Repository o Git repository
4. Configura:
   • Repository URL: <tu-repositorio>
   • Repository reference: main
   • Compose path: Traefik/docker-compose.yml
5. Añade el archivo de variables de entorno: Traefik/stack.env (o configúralas manualmente)
6. Haz clic en Deploy the stack

Verifica que Traefik esté funcionando:

docker logs traefik

Paso 8: Desplegar Authentik desde Portainer

1. En Portainer, ve a Stacks → Add stack
2. Nombre: authentik
3. Selecciona Repository o Git repository
4. Configura:
   • Repository URL: <tu-repositorio>
   • Repository reference: main
   • Compose path: authentik/docker-compose.yml
5. Añade las variables de entorno necesarias
6. Haz clic en Deploy the stack

Configuración de Authentik

Una vez desplegado Authentik, necesitarás configurar:

• Applications (aplicaciones a proteger)
• Providers de tipo Forward Auth
• Authorization Flow de tipo Implicit
• Outposts para ejecutar los providers
• Middleware en Traefik

Para instrucciones detalladas, consulta el README de Authentik.

Paso 9: Configurar Variables de Entorno para Portainer UI

Una vez Traefik y Authentik están funcionando, actualiza el archivo .env en la raíz del proyecto:

nano .env

Variables principales a configurar:

• PORTAINER_DOMAIN: Tu dominio para Portainer UI (ej: portainer.tudominio.com)
• PORTAINER_API_DOMAIN: Tu dominio para la API de Portainer (ej: portainer-api.tudominio.com)
• PORTAINER_API_IP_WHITELIST: IPs permitidas para acceso directo a la API
• TRAEFIK_AUTH_MIDDLEWARE: Middleware de autenticación (ej: ths-authentik@docker)

Paso 10: Actualizar Stack de Portainer (Opcional)

Si deseas acceder a Portainer mediante dominio con SSL (en lugar del puerto 9443):

1. En Portainer, ve a Stacks → Add stack
2. Nombre: portainer
3. Selecciona Upload y sube el archivo docker-compose.yml de la raíz
4. O usa Repository apuntando a la raíz del repositorio
5. Añade las variables de entorno del archivo .env
6. Haz clic en Deploy the stack

Nota: Esto reemplazará el despliegue inicial por puerto 9443 con acceso mediante dominio.

Paso 11: Desplegar Otros Stacks desde Portainer

Una vez la infraestructura base está funcionando, puedes desplegar el resto de stacks:

Método 1: Desde la UI de Portainer (Recomendado)

1. Ve a Stacks → Add stack
2. Selecciona Repository
3. Configura el repositorio Git:
   • URL: <tu-repositorio>
   • Reference: main (o tu rama)
   • Compose path: <stack-name>/docker-compose.yml
4. Añade variables de entorno si es necesario
5. Haz clic en Deploy the stack

Método 2: Desde línea de comandos

# Ejemplo: Desplegar Authentik
cd authentik
docker compose up -d
cd ..

# Ejemplo: Desplegar Gitea
cd gitea
docker compose up -d
cd ..

📦 Stacks Disponibles

Stack	Descripción	Carpeta	Documentación
Traefik	Reverse proxy con SSL automático	Traefik/	README
Portainer	Gestor visual de Docker	Raíz (docker-compose.yml)	-
Authentik	Sistema de autenticación SSO (Forward Auth)	authentik/	README
Gitea	Servidor Git autoalojado con Actions	gitea/	README
n8n	Plataforma de automatización de workflows	n8n/	README
AdGuard	Bloqueador de anuncios DNS con DoT	adguard/	README
Trilium	Aplicación de notas jerárquicas	trilium/	README
Wireguard	VPN rápida y segura	wireguard/	README
Ruleta	Aplicación Next.js personalizada	ruleta/	README

📖 Nota: Cada stack tiene su propio README con instrucciones detalladas de configuración, uso y troubleshooting.

⚙️ Configuración

Archivo .env Principal

El archivo .env en la raíz contiene las configuraciones globales:

# Imagen de Portainer
PORTAINER_IMAGE=portainer/portainer-ce:latest

# Rutas de almacenamiento
PORTAINER_SECRET_PATH=/opt/portainer/secrets/portainer
PORTAINER_DATA_PATH=/opt/portainer/data

# Configuración de red y proxy
TRAEFIK_DOCKER_NETWORK=proxy
TRAEFIK_ENTRYPOINT_SECURE=websecure
TRAEFIK_CERTRESOLVER=letsencrypt

# Dominios
PORTAINER_DOMAIN=portainer.example.com
PORTAINER_API_DOMAIN=portainer-api.example.com

# Seguridad
PORTAINER_API_IP_WHITELIST=10.8.0.0/24,172.18.0.1/32
TRAEFIK_AUTH_MIDDLEWARE=ths-authentik@docker

Configuraciones por Stack

Cada stack puede tener su propio archivo stack.env o .env en su carpeta correspondiente.

🎯 Uso

Ver Logs de Portainer

docker logs -f portainer

Ver Estado de Todos los Contenedores

docker ps -a

Actualizar Portainer

docker compose pull
docker compose up -d

Reiniciar un Stack

Desde Portainer UI o:

cd <stack-folder>
docker compose restart

Eliminar un Stack

cd <stack-folder>
docker compose down
# Para eliminar también volúmenes:
docker compose down -v

🔒 Seguridad

Acceso a Portainer UI

• Protegido por SSO: La UI principal está protegida mediante Authentik (configurable con TRAEFIK_AUTH_MIDDLEWARE)
• Dominio: Accesible solo mediante el dominio configurado con SSL

Acceso a API de Portainer

• Whitelist IP: La API está restringida a IPs específicas (VPN, localhost)
• Dominio separado: Usa un dominio diferente sin SSO para apps móviles
• SSL: Todo el tráfico está cifrado

Base de Datos Cifrada

Portainer utiliza una clave de cifrado para proteger su base de datos, montada en:

• /run/secrets/portainer
• /run/portainer/portainer

🛠️ Troubleshooting

Portainer no arranca

1. Verifica que la red proxy existe: docker network ls | grep proxy
2. Revisa los logs: docker logs portainer
3. Verifica que el archivo de secreto existe y tiene permisos correctos
4. Verifica que el puerto 9443 no esté ocupado: sudo netstat -tulpn | grep 9443

No puedo acceder mediante dominio

1. Verifica que el dominio apunta a tu servidor: nslookup tudominio.com
2. Verifica que los registros DNS están propagados
3. Verifica que Traefik esté corriendo: docker ps | grep traefik
4. Verifica la configuración de Traefik: docker logs traefik
5. Revisa las labels de Traefik en el docker-compose.yml
6. Verifica que los puertos 80 y 443 estén abiertos: sudo netstat -tulpn | grep -E ':(80|443)'
7. Como respaldo, siempre puedes acceder por https://tu-servidor:9443

Error de permisos con volúmenes (SELinux)

Si usas SELinux, los volúmenes ya tienen la opción :Z configurada. Si persisten problemas:

sudo chcon -Rt svirt_sandbox_file_t /opt/portainer/data

Authentik no protege los servicios

1. Verifica que el outpost esté corriendo y en estado Healthy
2. Revisa que las aplicaciones y providers estén correctamente configurados
3. Verifica que el authorization flow sea de tipo Implicit
4. Comprueba que el middleware de Traefik esté correctamente referenciado en las labels
5. Revisa los logs de Authentik: docker logs authentik-server
6. Verifica la conectividad entre Traefik y Authentik en la red proxy

📝 Notas Adicionales

• Orden de despliegue: Siempre desplegar Portainer (9443) → Traefik → Authentik → Resto de stacks
• Registros DNS: Configurar ANTES de desplegar Traefik para que Let's Encrypt funcione correctamente
• Puerto 9443: Mantén el acceso por puerto 9443 como respaldo en caso de problemas con Traefik
• Backups: Considera hacer backup regular de /opt/portainer/data y el archivo de secretos
• Actualizaciones: Actualiza las imágenes regularmente desde Portainer UI
• Monitoreo: Usa Portainer para monitorear recursos y logs de todos los contenedores

📄 Licencia

Consulta el archivo LICENSE en este repositorio.

🤝 Contribuciones

Las contribuciones son bienvenidas. Por favor, abre un issue o pull request para sugerencias o mejoras.