148 lines
4.9 KiB
Markdown
148 lines
4.9 KiB
Markdown
# 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:** `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`):
|
|
|
|
```bash
|
|
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:
|
|
```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/`.
|