Troubleshooting: Coolify-Verbindung debuggen

Wenn Deploir nicht wie erwartet mit deinem Coolify-Server spricht, hilft dieser Guide dir durch die typischen Ursachen. Arbeite von oben nach unten – jede Sektion ist eine Hypothese, die du in ein paar Minuten ausschließen kannst.

Schritt 0: Zustand erfassen

Bevor du irgendwas änderst, sammel drei Informationen:

1. Welche konkrete Fehlermeldung zeigt Deploir? Exakter Wortlaut notieren.
2. Seit wann tritt sie auf? Ging es vorher? Was wurde zwischendurch geändert (Coolify-Update, Token-Rotation, Netzwechsel, …)?
3. Betrifft es alle Server in Deploir oder nur einen?

Die letzte Frage ist die wichtigste: Ist's nur ein Server = Problem mit dieser Coolify-Instanz; sind alle betroffen = Problem mit deinem Gerät, Netz oder der Deploir-App selbst.

Problem 1: HTTP 401 – Unauthorized

Symptom: Deploir zeigt „Verbindung fehlgeschlagen (HTTP 401)" beim Hinzufügen oder beim periodischen Polling.

Ursachen und Fixes:

1. Token wurde in Coolify gelöscht oder ist abgelaufen. Im Coolify-Panel unter Keys & Tokens → API tokens prüfen. Falls weg oder inaktiv: neuen Token generieren und in Deploir einfügen (Server auswählen → Bearbeiten → Token überschreiben).
2. Token hat nicht den benötigten Scope. Read-Only reicht fürs Monitoring, aber wenn du aus Deploir heraus Redeploys triggern willst, brauchst du Read-Write.
3. Copy-Paste-Fehler. Häufig: ein Leerzeichen am Ende wurde mitkopiert, oder beim Einfügen wurde der Schlüssel abgeschnitten. Token frisch aus Coolify kopieren und in Deploir neu einfügen.

Problem 2: Zeitüberschreitung / Server nicht erreichbar

Symptom: Deploir hängt und meldet nach 10–15 Sekunden „Verbindung fehlgeschlagen: Zeitüberschreitung".

Ursachen und Fixes:

1. Coolify ist tatsächlich down. URL in Safari/Chrome aufrufen – kommt das Panel? Wenn nicht: Server-Problem, nicht Deploir.
2. VPN ist nicht aktiv und dein Coolify ist nur über VPN erreichbar. VPN einschalten und Verbindung erneut testen.
3. Firewall blockiert ausgehend. Besonders bei Office-Netzen mit strikten Outbound-Regeln. Versuch einmal mit mobilem Hotspot – klappt's da, liegt's am Firmennetz.
4. Coolify-Instanz auf IPv6-only. Deploir unterstützt aktuell nur IPv4-Verbindungen. Wenn dein Server IPv6-only ist, braucht es vor ihm einen Reverse-Proxy mit IPv4-Endpoint.

Problem 3: Ungültiges Zertifikat

Symptom: „Ungültiges Zertifikat" oder „Zertifikat nicht vertrauenswürdig".

Was Deploir macht: Die App verweigert bewusst Self-Signed-Zertifikate und Zertifikate, die nicht in der macOS/iOS-Trusted-CA-Liste landen. Ein kompromittiertes Zertifikat wäre das Eintrittstor, um deinen API-Token mitzulesen – das Risiko blockieren wir lieber als einen Komfort-Wert.

Fix-Optionen:

1. Let's Encrypt nutzen. Coolify kann das automatisch machen, wenn deine Domain im DNS korrekt auf die Server-IP zeigt und Port 80 für die Challenge erreichbar ist.
2. Kommerzielles Zertifikat von einer Public CA (DigiCert, Sectigo, etc.) einspielen.
3. Interne Firmen-PKI: Schreib uns über die Kontaktseite. Wir können auf Anfrage eine Root-CA-Importmöglichkeit nachbauen – aktuell nicht im Standardfunktionsumfang, weil das Risikomanagement komplexer wird.

Problem 4: Apps werden nicht oder unvollständig angezeigt

Symptom: In Coolify siehst du 15 Apps, in Deploir nur 7.

Ursachen:

1. Token hat Team-Scope-Beschränkungen. Bei Coolify v4 kann ein Token auf bestimmte Teams eingeschränkt sein. Prüf im Coolify-Panel, ob der Token Zugriff auf alle Teams hat, deren Apps du sehen willst.
2. Server hat mehrere Projekte und Deploir zeigt nur das Default-Projekt. In den Server-Einstellungen in Deploir → Projekte → alle relevanten aktivieren.
3. Filter ist versehentlich aktiv. In der Hauptansicht oben rechts auf Filter zurücksetzen.

Problem 5: Notifications kommen nicht an

Symptom: Deploir sagt „Deployment fehlgeschlagen" sollte gepingt haben, aber nichts erscheint.

Checks:

1. macOS/iOS Notification-Berechtigung: Systemeinstellungen → Mitteilungen → Deploir → erlaubt? Sound an? Banner aktiviert?
2. In-App-Toggle: Deploir → Einstellungen → Notifications → der Event-Type ist aktiviert?
3. Fokus-Modus aktiv? macOS und iOS unterdrücken Notifications bei aktiviertem Fokus. Für kritische Alerts in den Notifications-Einstellungen Critical-Alerts aktivieren.
4. Polling-Intervall zu hoch? Bei 5 min Polling kommt die Notification bis zu 5 min nach dem eigentlichen Event. Für zeitkritische Services auf 60 s runter.

Log-Export für Support-Anfragen

Wenn du uns eine Support-Anfrage schickst, hilft uns ein Deploir-Log-Export enorm. Unter Einstellungen → Über → Log exportieren erzeugst du eine .log-Datei mit den letzten 500 internen App-Events (API-Calls, Fehler, Retry-Versuche).

Die Datei enthält keine Token, keine Keychain-Inhalte, keine privaten Daten – wir schneiden sensibles vor dem Export raus. Safe to mail.

Häng sie an deine Nachricht auf der Kontaktseite an und beschreib kurz, was du erwartet hast und was tatsächlich passiert ist.

App zurücksetzen (letzter Ausweg)

Wenn wirklich nichts mehr greift: Einstellungen → App zurücksetzen. Entfernt alle Server-Konfigurationen, löscht Keychain-Einträge (Tokens), löscht den Lizenzschlüssel.

Danach musst du alles neu einrichten. Nutze das nur, wenn du vorher Log-Export gemacht und die Schritte oben durchprobiert hast – ein Reset vernichtet unter Umständen Debug-Informationen, die wir gebraucht hätten, um dir das Problem dauerhaft zu lösen.

Fragen?

Wenn die Tabelle oben dein Problem nicht abdeckt, wir das ernst nehmen. Log-Export anhängen, auf der Kontaktseite melden, wir antworten typischerweise am selben Arbeitstag.