# 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;"
```