Erste Schritte: Deploir mit Coolify verbinden

Dieser Guide führt dich durch die fünf Minuten nach der Deploir-Installation. Am Ende siehst du deinen Coolify-Server live in der Menu Bar, mit Status-Dot und allen Applikationen auflistbar.

Voraussetzungen

Wenn eines davon fehlt, bleib dort hängen, bevor du weiterliest:

• Coolify v4 läuft auf einem erreichbaren Server (self-hosted). Die v3-API wird nicht unterstützt.
• Admin-Rechte in deinem Coolify-Panel, sodass du im Team-Settings-Bereich landen darfst.
• Deploir ab v1.0 ist auf dem Mac installiert. Falls nicht: von der Deploir-Produktseite laden.
• Deine Coolify-URL ist per HTTPS erreichbar. HTTP lehnt Deploir direkt beim Anlegen ab – ein API-Token über Klartext ist ein offenes Scheunentor.

Schritt 1: API-Token in Coolify erstellen

Im Coolify-Panel links in der Sidebar auf Keys & Tokens → Tab API tokens → oben rechts New Token.

Im Formular:

• Description — Vergib einen wiedererkennbaren Namen, z. B. „Deploir – MacBook Dominik". Wenn du mehrere Geräte hast, hilft dir das später beim Rotation-Management.
• Scope — Für reines Monitoring reicht Read. Willst du aus Deploir heraus redeployen oder rollbacken können, wähl Read-Write. Zwei getrennte Tokens sind legitim: einer für Mac zum Admin-Use, einer Read-Only fürs iPhone.

Klick Continue. Coolify zeigt den Token genau einmal an – kopier ihn direkt in die Zwischenablage. Nach dem Verlassen der Seite ist er weg und du müsstest neu generieren.

Das ist der einzige Moment, in dem der Token außerhalb deines Keychains existiert. Füg ihn direkt in Deploir ein und leere anschließend deine Zwischenablage.

Schritt 2: Server in Deploir hinzufügen

Deploir-App öffnen. In der Menu Bar taucht oben rechts das Deploir-Icon auf. Klick drauf → Server hinzufügen (im Leer-Zustand erscheint der Button direkt im Panel).

Im Onboarding-Dialog:

• Server-Name — Frei wählbar, nur zur Anzeige in der App. Sowas wie „Production" oder „Staging-EU" reicht.
• Coolify-URL — Die komplette URL, unter der dein Panel läuft. Inklusive https:// und ohne abschließenden Slash. Beispiel: https://coolify.example.com. Häufiger Fehler: Leute geben nur die Domain ohne Schema ein und die Validierung beißt. Mit Protokoll, dann klappt's.
• API-Token — Den Token aus Schritt 1 einfügen.

Klick Verbinden. Deploir macht einen Test-Call gegen die Coolify-API. Bei Erfolg erscheint ein Häkchen, und die Haupt-Ansicht zeigt deinen Server mit Status-Dot und Applikationen.

Wenn's fehlschlägt: spring zum Troubleshooting-Block.

Schritt 3: Verifizieren, was du siehst

Mit stehender Verbindung zeigt das Panel:

1. Server-Eintrag oben — grüner Status-Dot (alles healthy) oder gelber (Server erreichbar, mindestens eine App im Warnzustand).
2. Applikationen-Liste darunter, gruppiert nach Projekt aus Coolify. Jede App zeigt Status, letzten Deployment-Timestamp und – wenn aktiv – einen laufenden Deploy-Indikator.
3. Server-Metriken beim Klick auf den Server-Eintrag: CPU, RAM, Disk-Usage in Echtzeit, live gestreamt.

Taucht eine App nicht auf, die in Coolify sichtbar ist: Check den Token-Scope. Read-Only-Tokens haben gelegentlich keinen Zugriff auf bestimmte Team-Namespaces, je nach Coolify-Version. Regenerier ihn notfalls mit Read-Write.

Schritt 4: Notifications aktivieren

Standardmäßig feuert Deploir keine Notifications. Das ist Absicht – wir wollen dich nicht zuschütten, wenn du nur mal reinschaust.

In den Einstellungen → Notifications:

• Server-Status-Änderungen – Aktivieren bei Ausfall-Pings. Polling-Intervall steht standardmäßig auf 60 Sekunden; einstellbar zwischen 30 s (aggressiv) und 5 min (entspannt).
• Deployment-Start/-Ende – Aktivieren bei regulären Deploys. Für Production-Pipelines mit CI/CD-getriggerten Deploys Gold wert, für Staging eher Lärm.
• Deployment-Fehler – Immer auf „an" stellen. Stille fehlgeschlagene Deploys sind das Schlimmste.

macOS zeigt die Notifications im Notification Center + als Banner rechts oben. Per „Critical" setzen sie sich auch durch den Focus-Mode durch – relevant bei On-Call-Bereitschaft.

Troubleshooting

„Verbindung fehlgeschlagen (HTTP 401)"

Der API-Token stimmt nicht oder hat keinen ausreichenden Scope. Gegencheck in Coolify:

1. Token im „API tokens"-Tab auflisten – noch aktiv?
2. Scope korrekt? Read reicht nur fürs Monitoring, nicht für Redeploy-Calls.
3. Falls ja und trotzdem 401: In Deploir auf den Server → Bearbeiten → Token frisch einfügen. Copy-Paste schneidet gern mal ein Leerzeichen ab.

„Zeitüberschreitung" / „Server nicht erreichbar"

Entweder ist der Server down, oder du sitzt hinter einem Netz, das deine Coolify-Instanz nicht sieht.

• Rufe die URL in Safari auf. Kommt das Coolify-Panel? Wenn nein: Server ist das Problem, nicht Deploir.
• VPN an? Manche Self-Hosted-Coolify-Instanzen sind nur über VPN erreichbar. Deploir spricht direkt den Server an, ohne VPN geht's dann nicht.
• Firewall-Regel? Besonders bei Office-Netzen: Admin hat Port 443 ausgehend vielleicht geblockt für Non-Whitelisted-Domains.

„Ungültiges Zertifikat"

Deploir verweigert Self-Signed-Zertifikate bewusst – ein kompromittiertes Cert wäre das Eintrittstor, um den API-Token mitzulesen.

Fix: Let's Encrypt nutzen (Coolify macht das automatisch, wenn die Domain korrekt gesetzt ist), oder ein gültiges CA-Zertifikat. Bei interner Firmen-PKI ohne Public-CA: Schreib uns über die Kontaktseite – wir können eine Root-CA-Importmöglichkeit nachbauen, falls Bedarf entsteht.

Nächste Schritte

Wenn die Verbindung steht: iOS-App installieren, falls du ein iPhone nutzt. Gleiche iCloud-ID auf Mac und iPhone? Dann synchronisieren deine Server-Konfigurationen automatisch – du musst auf dem iPhone nichts mehr eintippen.

Danach: Widget auf den Home Screen legen, Live Activities aktivieren, Siri-Shortcut „Status von " einrichten. Das sind die drei Features, die iOS über die Mac-Version hinaus einzigartig machen.