Portainer/README.md

Compose Services Repository

Este repositorio contiene servicios autoalojados gestionados directamente con Docker Compose.

Portainer ya no es el gestor de despliegue de este repo. Los despliegues se hacen desde CLI con docker compose y variables en archivos .env locales. No uses stack.env como fuente de despliegue.

Contenido

• Arquitectura
• Prerequisitos
• Despliegue
• Servicios
• Configuracion
• Uso
• Troubleshooting
• Retirar un stack
• Anadir una nueva app

Arquitectura

La infraestructura base se levanta en este orden:

1. Traefik/: reverse proxy y certificados TLS.
2. authentik/: SSO y forward auth para apps privadas.
3. crowdsec/: proteccion colaborativa y bouncer para Traefik.
4. Resto de servicios: cada uno desde su propia carpeta.

Sablier permite arrancar y detener bajo demanda los servicios que tengan su middleware configurado. Un contenedor detenido no implica por sí solo una avería; consulta su configuración y sus logs antes de intervenir.

Los servicios publicados comparten la red Docker externa proxy, que Traefik usa para alcanzarlos.

Configura DNS antes de desplegar servicios expuestos. Los certificados de Let's Encrypt dependen de que los dominios resuelvan correctamente.

Prerequisitos

• Docker Engine
• Docker Compose con el comando docker compose
• Red Docker externa proxy
• Dominios apuntando al servidor o al Cloudflare Tunnel correspondiente
• Puertos 80/443 disponibles para Traefik si aplica

Crear la red compartida:

docker network create proxy

Si ya existe, Docker devolvera un error inofensivo.

Despliegue

Cada servicio se despliega desde su carpeta con su .env local:

cd Traefik
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d

Para actualizar un servicio:

cd <servicio>
docker compose --env-file .env pull
docker compose --env-file .env up -d

Para reiniciarlo:

cd <servicio>
docker compose --env-file .env restart

Para detenerlo:

cd <servicio>
docker compose --env-file .env down

Desde la raiz del repo, indica tanto el Compose como el .env del servicio:

docker compose --env-file <servicio>/.env -f <servicio>/docker-compose.yml up -d

Servicios

El inventario recoge las definiciones disponibles en el repositorio; no implica que todos los servicios estén desplegados o activos en el host.

Servicio	Descripcion	Carpeta	Documentacion
Traefik	Reverse proxy con TLS automatico	Traefik/	README
Authentik	SSO y Forward Auth	authentik/	README
CrowdSec	IPS/IDS y bouncer	crowdsec/	README
Homepage	Dashboard principal	homepage/	README
Gitea	Git autoalojado	gitea/	README
n8n	Automatizacion de workflows	n8n/	README
Mail Relay	Relay SMTP interno	mail-relay/	README
AdGuard	DNS y bloqueo de anuncios	adguard/	README
Trilium	Notas jerarquicas	trilium/	README
Wireguard	VPN	wireguard/	README
Open WebUI	UI para modelos locales/remotos	openwebui/	README
OpenCode	Entorno OpenCode servido por Traefik	opencode/	README
Cloudflare	Gestion DNS y definicion opcional de Cloudflare Tunnel	cloudflared/	README
FreshRSS	Lector y agregador de feeds RSS	freshrss/	README
Guacamole	Escritorio remoto desde el navegador	guacamole/	README
Karakeep	Archivo y busqueda de enlaces	karakeep/	README
LiteLLM	Pasarela central de APIs de modelos	litellm/	README
Media Server	Streaming y gestion de contenido multimedia	media-server/	README
Nextcloud	Archivos y colaboracion con OnlyOffice	nextcloud/	README
OpenGist	Fragmentos de codigo versionados con OIDC	opengist/	README
Paperless-ngx	Archivo documental con OCR y clasificacion IA	paperless/	README
PrivateBin	Pastebin con cifrado en el navegador	privatebin/	README
Sablier	Arranque y parada de servicios bajo demanda	sablier/	README
Kopia	Backups	backups/kopia/	README
n8n Observability	Scripts de monitorizacion del host invocados desde n8n	n8n-observability/	README

Kopia y n8n Observability tienen sus propios procedimientos documentados; no se despliegan siguiendo el flujo Compose de las carpetas de servicio.

Configuracion

Cada carpeta de servicio debe tener un .env con sus variables reales.

Reglas actuales:

• Despliega siempre con .env.
• No uses stack.env para desplegar.
• No documentes flujos nuevos basados en Portainer.
• Mantén secretos reales fuera de Git.
• Para apps expuestas por Traefik, el servicio publicado debe estar en la red proxy.
• Las bases de datos y dependencias internas deben quedarse en redes internas salvo que Traefik deba alcanzarlas.

Variables comunes de Traefik:

TRAEFIK_DOCKER_NETWORK=proxy
TRAEFIK_ENTRYPOINT_SECURE=websecure
TRAEFIK_CERTRESOLVER=letsencrypt
TRAEFIK_AUTH_MIDDLEWARE=ths-authentik@docker

Para crear una app nueva, sigue NUEVA-APP.md.

Uso

Ver proyectos Compose activos y todos los contenedores del host:

docker compose ls
docker ps -a

Ver logs de un servicio:

cd <servicio>
docker compose --env-file .env logs -f

Validar un compose:

cd <servicio>
docker compose --env-file .env config

Para validar sin imprimir la configuración expandida y sus posibles secretos, usa docker compose --env-file .env config --quiet.

Troubleshooting

Si Traefik no enruta:

1. Verifica DNS: dig <dominio>
2. Comprueba que Traefik esta corriendo: docker ps | grep traefik
3. Revisa logs: docker logs traefik
4. Valida labels del servicio publicado.
5. Comprueba que el contenedor esta en la red proxy.

Si Authentik redirige pero devuelve error:

1. Verifica que existe el Proxy Provider.
2. Verifica que existe la Application.
3. Comprueba que la app esta asociada al Embedded Outpost.
4. Revisa logs de authentik-server.

Si un .env no se aplica:

1. Ejecuta desde la carpeta del servicio o usa --env-file <servicio>/.env.
2. Valida con docker compose --env-file .env config.
3. Recuerda que Traefik no expande variables; Docker Compose las expande antes de crear labels.

Notas

• Orden recomendado: Traefik -> Authentik -> CrowdSec -> servicios.
• CrowdSec debe ir antes de Authentik en la cadena de middlewares cuando ambos se usen.
• Las instrucciones antiguas de Portainer se consideran obsoletas.

Retirar un stack

Los stacks descartados se borran del repo (el historial de git conserva la config). Antes de borrar:

1. docker compose --env-file .env down desde la carpeta del stack.
2. Backup en /opt/backups/removal-<fecha>-<stack>/ (chmod 600): datos de /opt/<stack>, la carpeta del repo con su .env y los ficheros de /opt/traefik/dynamic/ que se toquen.
3. Quitar su ruta en /opt/traefik/dynamic/ (renombrar a .bak-<ts>-removed) y su middleware en sablier.yml si lo tenía.
4. Quitar su entrada de Homepage (labels en el compose o services.yaml).
5. Borrar sus registros DNS con cloudflared/cloudflare_dns.py delete <nombre>.
6. Quitar referencias en backups/kopia/ y n8n-observability/scripts/ops-report.
7. Borrar los datos en /opt/<stack> y git rm -r <stack>.