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:

Traefik/: reverse proxy y certificados TLS.
authentik/: SSO y forward auth para apps privadas.
crowdsec/: proteccion colaborativa y bouncer para Traefik.
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:

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

Si Authentik redirige pero devuelve error:

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

Si un .env no se aplica:

Ejecuta desde la carpeta del servicio o usa --env-file <servicio>/.env.
Valida con docker compose --env-file .env config.
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:

docker compose --env-file .env down desde la carpeta del stack.
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.
Quitar su ruta en /opt/traefik/dynamic/ (renombrar a .bak-<ts>-removed) y su middleware en sablier.yml si lo tenía.
Quitar su entrada de Homepage (labels en el compose o services.yaml).
Borrar sus registros DNS con cloudflared/cloudflare_dns.py delete <nombre>.
Quitar referencias en backups/kopia/ y n8n-observability/scripts/ops-report.
Borrar los datos en /opt/<stack> y git rm -r <stack>.