techno-todo/docs/DEPLOYMENT.md

Dokploy-Deployment

Diese Anleitung beschreibt beide Wege, die techno-todo-App auf Dokploy zu deployen:

1. Der native Dokploy-Weg — wie man es „richtig" über die Dokploy-UI/API macht (für zukünftige Apps empfohlen).
2. Was tatsächlich gemacht wurde — der POC-Verlauf inkl. aller Workarounds, die wegen kaputter Dokploy-Zustände nötig waren.

---

Voraussetzungen

• Dokploy-Instanz: https://dokploy.kgessner.de (intern 192.168.0.184)
• Gitea: https://git.kgessner.de (läuft in einem K8s/Talos-Cluster auf Proxmox)
• Docker-Swarm auf dem Dokploy-Host aktiv

---

Der native Dokploy-Weg

1. Git-Provider (Gitea) verbinden

In der Dokploy-UI unter Settings → Git Providers → Gitea:

• Gitea URL: https://git.kgessner.de
• Access Token: ein Gitea-PAT mit Scope repo, repo:status, read:user, read:org

Alternativ per API:

curl -X POST "https://dokploy.kgessner.de/api/git.provider.gitea.create" \
  -H "x-api-key: $DOKPLOY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"giteaUrl":"https://git.kgessner.de","accessToken":"<GITEA_TOKEN>"}'

2. Projekt anlegen

Projects → Create Project → Name techno-todo.

3. Application anlegen (Git-Source)

New Application mit diesen Einstellungen:

Feld	Wert
Application Name	techno-todo
Build Type	Dockerfile
Provider	Gitea
Repository	LuiiCode/techno-todo
Branch	main
Dockerfile Path	./Dockerfile
Port	3000

4. (Optional) Datenbank provisionieren

Falls du die PostgreSQL-Variante nutzt (Branch v1-postgres), provisioniere eine DB:

New Database → PostgreSQL → Name techno-db. Dokploy erzeugt automatisch einen Docker-Service und stellt die Verbindungsdaten als Env-Variablen bereit.

Achtung (POC-Lesson): Die App braucht dann DATABASE_URL, die auf den DB-Service-Namen zeigt (z.B. techno-db-xxxx), nicht localhost.

5. Domain konfigurieren

Unter Application → Domains:

• Host: todo.kgessner.de (öffentlich) oder techno-todo.192.168.0.184.sslip.io (LAN)
• Port: 3000
• HTTPS: HTTP (für LAN-Test ausreichend)

Dokploy erzeugt automatisch die Traefik-Routing-Konfiguration unter /etc/dokploy/traefik/dynamic/<app>.yml.

Per API (mit gültigem API-Key, Header x-api-key):

curl -X POST "https://dokploy.kgessner.de/api/domain.create" \
  -H "x-api-key: $DOKPLOY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"host":"todo.kgessner.de","https":false,"port":3000,"applicationId":"<app-id>"}'

Der API-Key lässt sich über die Dokploy-UI (Settings → API Keys) erzeugen. Ist der Key abgelaufen, kann man einen neuen direkt in der DB anlegen — der Hash ist base64url(SHA-256(key)) ohne Padding (BetterAuth-Mechanismus).

6. Auto-Deploy aktivieren

Dokploy hat einen nativen Auto-Deploy: In den Application-Einstellungen unter Deployments den Schalter für Automatic Deployments aktivieren und den Webhook-URL aus der UI kopieren. Diesen URL in Gitea als Webhook eintragen:

Gitea → Repo → Settings → Webhooks → Add Webhook (Gitea):

• URL: <dokploy-webhook-url> (aus Dokploy-UI)
• Content Type: application/json
• Secret: (optional)
• Events: Push

Wichtig: Der native Webhook braucht einen gültigen Dokploy-API-Key. Ist der Key abgelaufen, funktioniert der Auto-Deploy nicht (genau das ist beim POC passiert).

---

Was tatsächlich gemacht wurde

Der POC lief nicht sauber über den nativen Weg, weil mehrere Dokploy-Zustände kaputt waren. Hier der tatsächliche Verlauf:

Problem 1: DB-Service existierte nicht

Die App (PostgreSQL-Version) crashte im Loop:

• v1: ECONNREFUSED ::1:5432 (zeigte fälschlich auf localhost)
• v2: ENOTFOUND techno-db-8u3yoi (falscher Service-Name)

Lösung: App auf SQLite umgebaut (kein externer DB-Service nötig).

Problem 2: Traefik-Port falsch

Traefik routete auf :3000, aber Nginx (Test-App) hört auf :80 → Bad Gateway.

Lösung: Port in /etc/dokploy/traefik/dynamic/<app>.yml korrigiert + Traefik reload:

sed -i 's|:3000|:80|' /etc/dokploy/traefik/dynamic/<app>.yml
docker kill -s HUP dokploy-traefik

Problem 3: Dokploy-API-Key abgelaufen

Alle API-Aufrufe gaben Unauthorized / Invalid API key. Der Deploy-Worker loggte Error verifying API key.

Lösung: Neuen Key aus der Dokploy-DB extrahiert (siehe TROUBLESHOOTING).

Problem 4: Deploy-Worker startete keine Container

Deployments wurden angenommen, aber Container wurden nie gebaut/gestartet.

Lösung: Manuell per Docker gebaut + deployed (später durch die Auto-Deploy-Pipeline ersetzt — siehe AUTODEPLOY.md).

Finaler Zustand

Der Service läuft als Docker-Swarm-Service techno-todo-v2-mzs9mj mit dem SQLite-Image, erreichbar unter http://techno-todo.192.168.0.184.sslip.io/.