docs: vollständige Dokumentation (Dokploy-Deployment, Auto-Deploy, Troubleshooting, Architektur)

2026-08-12 20:20:27 +00:00
parent 32c29b1594
commit 5c481d7031
5 changed files with 540 additions and 0 deletions
@@ -0,0 +1,130 @@
+# Troubleshooting — alle POC-Fehler und Lösungen
+
+Chronologische Liste aller Probleme, die beim Dokploy-POC aufgetreten sind.
+
+---
+
+## 1. App crasht: `ECONNREFUSED ::1:5432` / `127.0.0.1:5432`
+
+**Symptom:** Docker-Container startet und stirbt sofort, Log zeigt
+`Failed to init DB: AggregateError [ECONNREFUSED]`.
+
+**Ursache:** Die App (PostgreSQL-Version) nutzte `localhost` als DB-Host, aber die DB
+läuft als separater Docker-Service, nicht im selben Container.
+
+**Lösung:** `DATABASE_URL` auf den Service-Namen zeigen lassen, **oder** (POC-Entscheidung)
+auf SQLite umsteigen — keine externe DB nötig.
+
+---
+
+## 2. App crasht: `ENOTFOUND techno-db-8u3yoi`
+
+**Symptom:** DNS-Lookup des DB-Hostnames schlägt fehl.
+
+**Ursache:** Der `techno-db` Docker-Service existierte gar nicht — Dokploy hat ihn nie
+erstellt, obwohl die API-Provisionierung „OK" meldete.
+
+**Lösung:** SQLite-Umstellung (siehe oben).
+
+---
+
+## 3. `Bad Gateway` trotz laufender App
+
+**Symptom:** Intern läuft die App, aber über die Domain kommt `Bad Gateway`.
+
+**Ursache:** Traefik routete auf Port `:3000`, die App (bzw. `nginx:alpine`) lauscht aber
+auf `:80`. Dokploy setzt standardmäßig `:3000`.
+
+**Diagnose:**
+```bash
+docker exec dokploy-traefik wget -qO- http://<service>:80/    # funktioniert
+docker exec dokploy-traefik wget -qO- http://<service>:3000/  # connection refused
+```
+
+**Lösung:** Traefik-Config korrigieren:
+```bash
+# Config liegt auf dem Host (Bind-Mount)
+sed -i 's|http://<service>:3000|http://<service>:80|' /etc/dokploy/traefik/dynamic/<app>.yml
+docker kill -s HUP dokploy-traefik   # reload
+```
+
+---
+
+## 4. Dokploy-API: `Unauthorized` / `Invalid API key`
+
+**Symptom:** Alle API-Calls geben 401, Deploy-Worker loggt `Error verifying API key`.
+
+**Ursache:** Der gespeicherte API-Key war abgelaufen/ungültig.
+
+**Diagnose + Lösung:** Key direkt aus der Dokploy-Postgres-DB lesen:
+```bash
+docker exec dokploy-postgres.1.<id> psql -U dokploy -d dokploy \
+  -c "SELECT name, key, start FROM apikey;"
+```
+
+**Hinweis:** Der `key`-Wert in der DB ist gehasht (BetterAuth). Für neue Keys: über die
+Dokploy-UI unter **Settings → API Keys** neu erzeugen.
+
+---
+
+## 5. Deploy-Worker startet keine Container
+
+**Symptom:** Deployment wird angenommen, aber kein Container wird gebaut/gestartet.
+Worker-Logs zeigen `service <name> not found`.
+
+**Ursache:** Services wurden manuell umbenannt/gelöscht → Dokploy ist **out-of-sync** mit
+dem tatsächlichen Docker-Zustand.
+
+**Lösung:** Manuell bauen + deployen (später durch die Auto-Deploy-Pipeline ersetzt):
+```bash
+cd /opt/repos/techno-todo
+docker build -t techno-todo:<commit> .
+docker service update --force --image techno-todo:<commit> <service-name>
+```
+
+---
+
+## 6. Gitea-Webhook löst nicht zuverlässig aus
+
+**Symptom:** Manche Pushes triggern den Deploy, andere nicht.
+
+**Ursache:** Gitea läuft in einem **K8s/Talos-Cluster** — ausgehende Verbindungen zu
+internen `192.168.0.x`-Adressen sind unzuverlässig (CNI/NAT).
+
+**Lösung:** Cron-Polling-Fallback (idempotentes Deploy-Skript alle 2 Min). Siehe
+`AUTODEPLOY.md`.
+
+---
+
+## 7. Race-Condition: alter Commit wird deployed
+
+**Symptom:** Webhook feuert, aber das Deploy holt noch den alten Commit.
+
+**Ursache:** `git fetch` läuft, bevor Gitea den Push vollständig ins Git-Backend
+integriert hat.
+
+**Lösung:** Entweder `sleep 3` vor `git fetch`, oder (besser) idempotentes Skript — der
+nächste Cron-Lauf holt den verpassten Commit automatisch nach.
+
+---
+
+## Nützliche Diagnose-Befehle
+
+```bash
+# Docker-Swarm-Services
+docker service ls
+docker service logs --tail 50 <service>
+
+# Traefik-Routing
+docker exec dokploy-traefik wget -qO- http://localhost:8080/api/http/routers
+
+# Dokploy-Logs (Deploy-Worker)
+docker service logs --tail 50 dokploy 2>&1 | grep -iE 'worker|error|deploy'
+
+# Dokploy-DB direkt abfragen
+docker exec dokploy-postgres.1.<id> psql -U dokploy -d dokploy -c "\dt"
+
+# Token aus DB extrahieren (Gitea)
+docker exec dokploy-postgres.1.<id> psql -U dokploy -d dokploy \
+  -c "SELECT access_token FROM gitea;"
+```