From 9f7bcb3ecc03cbe9ac42448c558720350d761dad Mon Sep 17 00:00:00 2001
From: root <root@almasrv.thehomelesssherlock.com>
Date: Mon, 23 Mar 2026 02:02:16 +0000
Subject: [PATCH] docs: add operational gotchas to Coolify template

- Gotcha 1: dynamic config dir is /opt/traefik/dynamic, NOT /data/coolify/proxy/dynamic
- Gotcha 2: entrypoints are http/https (not web/websecure); coolify.yaml fix location
- Gotcha 3: env vars in bind mount paths become named volumes in Coolify
- Gotcha 4: SSH MaxSessions must be >= 10 for parallel deploy sessions

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 COOLIFY-TEMPLATE.md | 54 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)

diff --git a/COOLIFY-TEMPLATE.md b/COOLIFY-TEMPLATE.md
index 8a0fc9c..ccf7ef7 100644
--- a/COOLIFY-TEMPLATE.md
+++ b/COOLIFY-TEMPLATE.md
@@ -169,3 +169,57 @@ docker network create mail_internal
 2. **Domain**: set FQDN (e.g. `myapp.sherlockhomeless.net`)
 3. **Base Directory**: set to the subdirectory (e.g. `/gitea`, `/n8n`)
 4. **Environment Variables**: fill from `stack.env` template
+
+---
+
+## Gotchas del sistema — leer antes de tocar el proxy
+
+### Gotcha 1 — Directorio dynamic del proxy NO es el de Coolify
+
+El proxy `coolify-proxy` monta su directorio de configuración dinámica desde:
+```
+/opt/traefik/dynamic  →  /dynamic  (dentro del contenedor)
+```
+
+**NO** desde `/data/coolify/proxy/dynamic/` (ese directorio existe pero Traefik NO lo lee).
+
+Si necesitas añadir rutas manuales (por ejemplo, para el dashboard de Coolify), edita:
+```bash
+/opt/traefik/dynamic/coolify.yaml   # ← aquí es donde importa
+```
+
+### Gotcha 2 — Entrypoints del proxy: `http` y `https` (NO `web`/`websecure`)
+
+Coolify genera automáticamente labels de Traefik con:
+- `entryPoints=http` (puerto 80)
+- `entryPoints=https` (puerto 443)
+
+El proxy (`/data/coolify/proxy/docker-compose.yml`) está configurado con esos mismos nombres.
+El contenedor `coolify` propio tiene labels antiguas con `websecure` — no importa porque
+su routing está definido en `/opt/traefik/dynamic/coolify.yaml`.
+
+**Si el dashboard de Coolify da 404**, verificar:
+1. Que `/opt/traefik/dynamic/coolify.yaml` existe y tiene routers `http`/`https`
+2. Que `coolify-proxy` puede resolver `coolify:8080` (ambos en red `proxy`)
+
+### Gotcha 3 — Variables en bind mounts → Coolify las convierte en volúmenes nombrados
+
+```yaml
+# ❌ MAL: Coolify NO resuelve la variable → crea volumen Docker nombrado vacío
+volumes:
+  - ${MY_DATA_PATH}:/var/lib/postgresql/data:Z
+
+# ✅ BIEN: rutas hardcodeadas
+volumes:
+  - /opt/myapp/postgres:/var/lib/postgresql/data:Z
+```
+
+### Gotcha 4 — SSH MaxSessions
+
+`/etc/ssh/sshd_config` tiene `MaxSessions 20` (cambiado de 2).
+Coolify abre múltiples sesiones SSH en paralelo durante el deploy.
+Si vuelve a bajar a 2 (upgrade del OS, etc.), todos los deploys fallarán con exit code 255.
+
+```bash
+grep MaxSessions /etc/ssh/sshd_config   # debe ser >= 10
+```