====== 🧠 n8n + Caddy Runbook (real-world) ======

Dokumentacija temelji na realnih incidentih pri postavitvi
n8n + n8n-docs (workflow documentation engine)
na Ubuntu + Docker + Caddy + Let’s Encrypt.

Cilj:

stabilen HTTPS

jasen mentalni model

ponovljiv step-by-step postopek

troubleshooting brez ugibanja

===== 🧱 Arhitektura (končni model) =====

Internet
↓
Caddy (Docker, :80 / :443)
↓
Docker network (backend)
* n8n :5678
* n8n-docs :8000

Caddy je edini SSL entrypoint

Vse aplikacije tečejo HTTP only znotraj Dockerja

Reverse proxy vedno kaže na IME CONTAINERJA, ne IP

===== 🔍 Predhodni pregled (OBVEZNO) =====

==== OS + Docker ====

root@server# lsb_release -a
root@server# docker --version
root@server# docker compose version

==== Porti 80 / 443 ====

root@server# ss -lntp | grep -E ':80|:443'

✔ OK: docker-proxy
✘ Problem: nginx, apache, drug proces

==== DNS ====

docs.krofekhost.com → javni IP strežnika

root@server# nslookup docs.krofekhost.com

==== Docker network ====

root@server# docker network ls

Uporabljen network: backend

===== 💾 Backup (pred vsako spremembo) =====

==== Caddy konfiguracija ====

root@server# mkdir -p /opt/caddy-backup
root@server# docker cp caddy:/etc/caddy/Caddyfile /opt/caddy-backup/Caddyfile
root@server# docker cp caddy:/config /opt/caddy-backup/config || true

==== SSL certifikati (Caddy /data) ====

root@server# mkdir -p /opt/backup
root@server# tar -czf /opt/backup/caddy_data_$(date +%F).tar.gz
-C /var/lib/docker/volumes/caddy_caddy_data/_data .

==== n8n podatki ====

root@server# tar -czf /opt/backup/n8n_data_$(date +%F).tar.gz
-C /var/lib/docker/volumes/n8n_n8n_data/_data .

==== n8n-docs baza ====

root@server# tar -czf /opt/backup/n8n_docs_db_$(date +%F).tar.gz
-C /opt/n8n-docs/n8n-workflow-templates database

===== 🔥 Incidenti (resnični primeri) =====

[[incidents:ssl_protocol_error|ERR_SSL_PROTOCOL_ERROR – Caddy brez /data volume]]

[[incidents:caddy_autosave_trap|Caddy autosave.json povozi Caddyfile]]

[[incidents:acme_timeout|Let’s Encrypt timeout – ACME HTTP challenge]]

[[incidents:bad_gateway_502|502 Bad Gateway – app posluša na 127.0.0.1]]

[[incidents:docker_network_miss|Container ni v istem Docker networku]]

[[incidents:localhost_trap|127.0.0.1 ≠ Docker network]]

===== 🚨 Incident: 502 Bad Gateway (NAJPOGOSTEJŠI) =====

==== Simptom ====

https://docs.krofekhost.com
 → 502

Caddy log:
dial tcp …:8000: connect: connection refused

==== Vzrok ====

Aplikacija n8n-docs je poslušala na:

127.0.0.1:8000

To pomeni:

dosegljivo samo znotraj istega containerja

Caddy (drug container) nima dostopa

==== Rešitev ====

Sprememba bind naslova na 0.0.0.0

Datoteka:
/opt/n8n-docs/n8n-workflow-templates/run.py

Spremembe:

def start_server(host: str = "0.0.0.0", port: int = 8000, reload: bool = False):

parser.add_argument(
"--host",
default="0.0.0.0",
help="Host to bind to (default: 0.0.0.0)"
)

Nato:

root@server# docker compose down
root@server# docker compose build --no-cache
root@server# docker compose up -d

Preveri:

root@server# docker logs n8n-docs --tail=30

Mora pisati:

Uvicorn running on http://0.0.0.0:8000

===== 🔐 Incident: ERR_SSL_PROTOCOL_ERROR =====

==== Simptom ====

Browser:
ERR_SSL_PROTOCOL_ERROR

==== Vzrok ====

Caddy container brez persistent /data volume
→ certifikati izgubljeni ob restartu

==== Rešitev ====

Caddy mora imeti:

-v caddy_caddy_data:/data
-v caddy_caddy_config:/config

Certifikati so vedno v:

/var/lib/docker/volumes/caddy_caddy_data/_data

===== ⚠️ Incident: Caddy ignorira nove domene =====

==== Vzrok ====

Caddy uporablja autosave config:

/config/caddy/autosave.json

==== Rešitev ====

root@server# docker stop caddy
root@server# rm -f /var/lib/docker/volumes/caddy_caddy_config/_data/caddy/autosave.json
root@server# docker start caddy

⚠ Certifikati ostanejo nedotaknjeni (so v /data)

===== 🧩 Caddyfile (pravilen primer) =====

Datoteka:
/etc/caddy/Caddyfile

Primer:

docs.krofekhost.com {
reverse_proxy n8n-docs:8000
}

Reload:

root@server# docker exec -it caddy caddy reload --config /etc/caddy/Caddyfile

===== 🧪 Testiranje =====

==== ACME test ====

root@server# curl -I http://docs.krofekhost.com/.well-known/acme-challenge/test

Pričakovano:
HTTP/1.1 308
Server: Caddy

==== Test iz Caddy containerja ====

root@server# docker exec -it caddy sh -lc
'apk add --no-cache curl >/dev/null 2>&1 || true;
curl -I http://n8n-docs:8000/docs
 | head'

==== Končni test ====

https://docs.krofekhost.com

Če ne dela:

Incognito

pobriši site data (HSTS)

===== 🧠 Mentalni model (TL;DR) =====

Caddy = edini SSL

Docker DNS = container name

127.0.0.1 = samo jaz

0.0.0.0 = vsi containerji

Če ne dela → logs, ne ugibanje