docs: vollständige Dokumentation (Dokploy-Deployment, Auto-Deploy, Troubleshooting, Architektur)
This commit is contained in:
Hermes
@@ -0,0 +1,134 @@
|
||||
# Dokploy-Deployment
|
||||
|
||||
Diese Anleitung beschreibt **beide** Wege, die `techno-todo`-App auf Dokploy zu deployen:
|
||||
|
||||
1. **[Der native Dokploy-Weg](#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](#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:
|
||||
> ```bash
|
||||
> 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:** `techno-todo.192.168.0.184.sslip.io`
|
||||
- **Port:** `3000`
|
||||
- **HTTPS:** HTTP (für LAN-Test ausreichend)
|
||||
|
||||
Dokploy erzeugt automatisch die Traefik-Routing-Konfiguration unter
|
||||
`/etc/dokploy/traefik/dynamic/<app>.yml`.
|
||||
|
||||
### 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:
|
||||
```bash
|
||||
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/`.
|
||||
Reference in New Issue
Block a user