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,88 @@
+# Architektur & Infrastruktur
+
+Übersicht der beteiligten Systeme und Netzwerk-Topologie.
+
+## Komponenten
+
+| System | Rolle | Adresse |
+|--------|-------|---------|
+| **Hermes-Server** | Assistent + Webhook-Receiver + Download-Hub | `192.168.0.80` |
+| **Dokploy-Host** | PaaS (Docker Swarm) | `192.168.0.184` |
+| **Gitea** | Git-Server | `git.kgessner.de` (K8s/Talos) |
+| **Proxmox** | Hypervisor (Dokploy-VM + K8s-Cluster) | — |
+| **Netcup-Gateway** | Reverse-Proxy (öffentliche IP) | `192.168.0.222` |
+
+## Netzwerk-Topologie
+
+```
+                          Internet
+                             │
+                    152.53.197.186 (öffentliche IP)
+                             │
+                    ┌────────┴────────┐
+                    │  Netcup-Gateway  │  (192.168.0.222)
+                    │  Reverse-Proxy   │
+                    └────────┬────────┘
+                             │
+        ┌────────────────────┼────────────────────┐
+        │                    │                    │
+  git.kgessner.de    dokploy.kgessner.de    (weitere Dienste)
+        │                    │
+        ▼                    ▼
+  K8s/Talos-Cluster    Docker-Swarm-Host
+  (auf Proxmox)        (192.168.0.184)
+  - Gitea              - Dokploy UI (:3000)
+                       - Traefik (:80/443)
+                       - App-Services
+```
+
+### Wichtige Erkenntnisse
+
+1. **`git.kgessner.de` und `dokploy.kgessner.de` teilen sich die öffentliche IP**
+   `152.53.197.186`. Ein Reverse-Proxy routet anhand des Host-Headers.
+
+2. **Gitea läuft in Kubernetes (Talos)**, Dokploy in **Docker Swarm** — zwei
+   unterschiedliche Orchestrierungswelten auf demselben Proxmox-Host.
+
+3. **Netzwerk-Isolation:** Der K8s-Cluster (Gitea) kann interne `192.168.0.x`-Adressen
+   (Hermes, Dokploy) nicht zuverlässig erreichen. Das ist der Grund, warum der
+   Gitea-Webhook unzuverlässig ist und ein Cron-Polling-Fallback nötig wurde.
+
+4. **Öffentliche IP routet nicht zu Dokploy:** `techno-todo.152.53.197.186.sslip.io`
+   funktioniert **nicht**, weil Port 80/443 der öffentlichen IP nicht auf den
+   Dokploy-Host (`192.168.0.184`) weitergeleitet wird. Für LAN-Tests wird deshalb
+   `techno-todo.192.168.0.184.sslip.io` genutzt.
+
+## Docker-Swarm auf Dokploy
+
+```
+docker service ls
+# dokploy              (PaaS-UI)
+# dokploy-postgres     (interne DB)
+# dokploy-traefik      (Reverse-Proxy, Ports 80/443)
+# techno-todo-v2-...   (diese App)
+```
+
+### Traefik-Konfiguration
+
+Dokploy schreibt die Routing-Regeln nach `/etc/dokploy/traefik/dynamic/<app>.yml`
+(Bind-Mount in den Traefik-Container).
+
+```bash
+# Reload nach Config-Änderung
+docker kill -s HUP dokploy-traefik
+```
+
+### Dokploy-interne DB
+
+PostgreSQL im Container `dokploy-postgres`. Nützliche Tabellen: `application`, `gitea`,
+`apikey`, `project`, `domain`, `deployment`.
+
+```bash
+docker exec dokploy-postgres.1.<id> psql -U dokploy -d dokploy -c "\dt"
+```
+
+## sslip.io — der Magic-DNS-Trick
+
+`<name>.192.168.0.184.sslip.io` löst automatisch zu `192.168.0.184` auf. So braucht jede
+App keine eigene DNS-Config — einfach Subdomain vor die IP setzen.