Coolify mit Docker installieren: Self-Hosted PaaS als Heroku-Alternative

Heroku, Render oder Vercel binden Sie an einen Anbieter und laufende Kosten. Coolify ist eine quelloffene Plattform (PHP/Laravel), die als Docker-Compose-Stack auf einem 64-Bit-Linux-Server läuft. Über die Web-UI deployen Sie Apps aus Git-Repositories, starten Datenbanken und installieren über 280 vorkonfigurierte Services. Coolify verwaltet Server per SSH und bringt einen Traefik-Proxy mit Let's-Encrypt-Zertifikaten mit. Diese Anleitung beschreibt die manuelle Installation nach der offiziellen Doku.

Voraussetzungen

• 64-Bit-Linux-Host (Ubuntu 22.04/24.04, Debian 12, CentOS 9, Fedora 40, Alpine, Raspberry Pi OS 64-Bit; kein Windows, kein 32-Bit)
• Docker Engine >= 24.0 und Docker Compose Plugin >= 2.20, siehe Docker und Docker Compose auf Linux installieren
• Mindestens 2 CPU-Kerne, 2 GB RAM, 10 GB freier Speicher (offizielle Mindestwerte; mit Builds auf demselben Server 4 GB RAM und ab 30 GB)
• Root- oder sudo-Zugang, curl und openssl vorhanden
• Ports 8000 (Web-UI), 6001 (Echtzeit-Updates) und 6002 (Web-Terminal) frei, für den Coolify-Proxy zusätzlich 80 und 443
• SSH-Zugang zum Server: Coolify verwaltet auch den eigenen Host per SSH
• Für HTTPS im Produktivbetrieb: Reverse Proxy (z. B. Traefik als Docker-Reverse-Proxy) oder spätere Konfiguration über die Coolify-UI

Eckdaten auf einen Blick

Schritt 1: Verzeichnisstruktur anlegen und Netzwerk erstellen

Coolify speichert alle Daten unter /data/coolify/. Für die Verwaltung des eigenen Hosts braucht Coolify einen SSH-Schlüssel, dessen öffentlicher Teil in authorized_keys von root steht. Das Docker-Netzwerk coolify muss vor dem Start mit --attachable entstehen, damit deployte App-Container beitreten können.

# Verzeichnisbaum anlegen

$ sudo mkdir -p /data/coolify/source
$ sudo mkdir -p /data/coolify/ssh/keys
$ sudo mkdir -p /data/coolify/ssh/mux
$ sudo mkdir -p /data/coolify/applications
$ sudo mkdir -p /data/coolify/databases
$ sudo mkdir -p /data/coolify/services
$ sudo mkdir -p /data/coolify/backups
$ sudo mkdir -p /data/coolify/webhooks-during-maintenance
$ sudo mkdir -p /data/coolify/proxy/dynamic

# SSH-Schlüssel für die Verwaltung des Hosts (als root)

$ sudo ssh-keygen -f /data/coolify/ssh/keys/id.root@host.docker.internal -t ed25519 -N '' -C root@coolify
$ sudo sh -c 'cat /data/coolify/ssh/keys/id.root@host.docker.internal.pub >> /root/.ssh/authorized_keys'
$ sudo chmod 600 /root/.ssh/authorized_keys

# Attachable-Netzwerk erstellen (vor docker compose up!)

$ docker network create --attachable coolify

docker network inspect coolify | grep -A2 '"Attachable"'
# Erwartete Ausgabe:
# "Attachable": true,
sudo grep -c root@coolify /root/.ssh/authorized_keys
# Erwartete Ausgabe: 1

Schritt 2: Secrets generieren und .env anlegen

# Secrets in Variablen erfassen (einmalig ausführen!)
APP_ID=$(openssl rand -hex 16)
APP_KEY="base64:$(openssl rand -base64 32)"
DB_PASSWORD=$(openssl rand -base64 32)
REDIS_PASSWORD=$(openssl rand -base64 32)
PUSHER_APP_ID=$(openssl rand -hex 32)
PUSHER_APP_KEY=$(openssl rand -hex 32)
PUSHER_APP_SECRET=$(openssl rand -hex 32)

# .env-Datei schreiben
sudo tee /data/coolify/source/.env > /dev/null <<EOF
APP_ID=${APP_ID}
APP_KEY=${APP_KEY}
APP_NAME=Coolify
APP_ENV=production
APP_PORT=8000
DB_USERNAME=coolify
DB_PASSWORD=${DB_PASSWORD}
DB_DATABASE=coolify
REDIS_PASSWORD=${REDIS_PASSWORD}
PUSHER_APP_ID=${PUSHER_APP_ID}
PUSHER_APP_KEY=${PUSHER_APP_KEY}
PUSHER_APP_SECRET=${PUSHER_APP_SECRET}
REGISTRY_URL=ghcr.io
LATEST_IMAGE=latest
PHP_MEMORY_LIMIT=256M
EOF

sudo chmod 600 /data/coolify/source/.env

Für eine feste Version setzen Sie LATEST_IMAGE=4.5.0. Wer die Registrierung nie offenlegen will, ergänzt ROOT_USERNAME, ROOT_USER_EMAIL und ROOT_USER_PASSWORD, dann legt Coolify das Admin-Konto beim ersten Start an. Die E-Mail-Adresse prüft Coolify dabei samt DNS-Eintrag der Domain; eine Adresse mit einer Domain ohne Mailserver-Eintrag (etwa example.com) lehnt der Start mit Invalid Root User Environment Variables ab, und es entsteht kein Konto. Mit gültiger Domain meldet das Log Root user created successfully., und /register leitet danach auf die Anmeldung um. Sichern Sie die .env getrennt vom Server, etwa in einem Passwortmanager: Ohne APP_KEY lässt sich ein Backup nicht wiederherstellen.

sudo cat /data/coolify/source/.env | grep APP_ID
# Ausgabe: APP_ID=<generierter Hex-Wert>

ls -la /data/coolify/source/.env
# Berechtigungen: -rw------- (600)

Schritt 3: Offizielle Compose-Dateien herunterladen

Coolify benötigt zwingend zwei Compose-Dateien. Ohne docker-compose.prod.yml fehlt die Produktionskonfiguration (siehe Troubleshooting).

$ cd /data/coolify/source

sudo curl -fsSL https://cdn.coollabs.io/coolify/docker-compose.yml \
  -o docker-compose.yml

sudo curl -fsSL https://cdn.coollabs.io/coolify/docker-compose.prod.yml \
  -o docker-compose.prod.yml

Ist der Download erfolgreich, können Sie Schritt 4 überspringen.

$ ls -lh /data/coolify/source/

# Erwartete Ausgabe: docker-compose.yml, docker-compose.prod.yml, .env

Schritt 4: Eigene Anpassungen und CDN-Probleme (optional)

Das Upgrade-Skript lädt die offiziellen Dateien bei jedem Update neu, eine selbst gebaute Compose-Datei ist daher ungeeignet. Ist cdn.coollabs.io nicht erreichbar, laden Sie dieselben Dateien aus dem GitHub-Repository (Zweig v4.x):

$ cd /data/coolify/source
$ sudo curl -fsSL https://raw.githubusercontent.com/coollabsio/coolify/v4.x/docker-compose.yml -o docker-compose.yml
$ sudo curl -fsSL https://raw.githubusercontent.com/coollabsio/coolify/v4.x/docker-compose.prod.yml -o docker-compose.prod.yml

Eigene Anpassungen (Ports, Speicherlimits, Labels) gehören laut Coolify-Doku in eine zusätzliche Datei /data/coolify/source/docker-compose.custom.yml, die das Upgrade-Skript berücksichtigt. Beispiel: Dashboard nur an localhost binden, wenn ein Reverse Proxy davor sitzt:

services:
  coolify:
    ports:
      - "127.0.0.1:8000:8080"

$ cd /data/coolify/source
$ sudo docker compose --env-file .env -f docker-compose.yml -f docker-compose.prod.yml -f docker-compose.custom.yml config --quiet

# Keine Ausgabe = Syntax korrekt

Schritt 5: Berechtigungen setzen und Stack starten

Alle Verzeichnisse unter /data/coolify/ müssen UID 9999 (dem Benutzer im Coolify-Container) gehören. Sonst meldet der Container „Permission denied“ beim Lesen der .env oder der SSH-Schlüssel.

# Berechtigungen setzen (PFLICHT)

$ sudo chown -R 9999:root /data/coolify
$ sudo chmod -R 700 /data/coolify

# Stack mit den offiziellen CDN-Dateien starten:
sudo docker compose \
  --env-file /data/coolify/source/.env \
  -f /data/coolify/source/docker-compose.yml \
  -f /data/coolify/source/docker-compose.prod.yml \
  up -d --pull always --remove-orphans --force-recreate
# Mit docker-compose.custom.yml (Schritt 4) diese Datei als drittes -f anhängen

Der erste Start dauert 1 bis 3 Minuten (Image-Download, Datenbank-Initialisierung). Der Coolify-Container wartet auf healthy PostgreSQL und Redis.

docker compose \
  --env-file /data/coolify/source/.env \
  -f /data/coolify/source/docker-compose.yml \
  -f /data/coolify/source/docker-compose.prod.yml \
  ps

# Erwartete Ausgabe (alle drei Container):
# NAME                 STATUS              PORTS
# coolify              Up (healthy)        0.0.0.0:8000->8080/tcp
# coolify-db           Up (healthy)        5432/tcp
# coolify-redis        Up (healthy)        6379/tcp
# Echtzeitdienst läuft im Container coolify

# Health-API direkt prüfen:

$ curl -sf http://localhost:8000/api/health

# Erwartete Ausgabe: HTTP 200, Antwort OK

Schritt 6: Ersteinrichtung im Browser

Öffnen Sie http://<server-ip>:8000, Coolify zeigt die Registrierung für das Admin-Konto. Legen Sie das Admin-Konto sofort an: Wer die Seite zuerst erreicht, wird Administrator und erhält damit Root-Zugriff auf den Server.

Nach dem Login führt Coolify durch den Einrichtungsassistenten:

1. Localhost verbinden: Unter „Servers“ den voreingestellten Localhost-Server bestätigen. Coolify kommuniziert intern über host.docker.internal.
2. Erstes Projekt anlegen: Über „Projects → New Project“ ein Projekt erstellen.
3. Resource deployen: „New Resource → Application“ Git-Repository verbinden, Buildpack oder Dockerfile wählen und deployen, oder einen One-Click-Service starten.

Für deployte Apps holt der integrierte Coolify-Proxy (Traefik) Let's-Encrypt-Zertifikate, sobald Sie eine Domain eintragen. Für das Dashboard hinterlegen Sie unter Settings eine eigene Domain; danach können Sie die Ports 8000, 6001 und 6002 in der Firewall schließen. Alternativ setzen Sie einen eigenen Reverse Proxy davor, siehe Caddy als Reverse Proxy einrichten.

$ curl -I http://localhost:8000

# Erwartete Ausgabe:
# HTTP/1.1 200 OK  (oder 302 Redirect zum Login)

Umstieg von 4.3 auf 4.4

Sichern Sie vor dem Update Datenbank, /data/coolify/ und insbesondere die .env mit unverändertem APP_KEY. Laden Sie beide offiziellen Compose-Dateien passend zur Zielversion neu. Ab 4.4 läuft der Echtzeitdienst im Coolify-Container; der bisherige separate Container coolify-realtime entfällt. Stoppen und entfernen Sie ihn vor dem Neuerstellen des Hauptcontainers, sonst kann Port 6001 blockiert bleiben. Prüfen Sie eigene Overrides für den alten Dienst soketi und die Reverse-Proxy-Ziele. Der Hauptcontainer übernimmt jetzt auch Port 6001; die offizielle Konfiguration erhält den Netzwerk-Alias coolify-realtime. Entfernen Sie keine Datenbank-Volumes.

Nach dem Update müssen /api/health auf Port 8000 und /up auf Port 6001 erfolgreich antworten. 4.4 verschärft außerdem OAuth-Anmeldung, Teamrechte und Geheimnisredaktion. Bestehende OAuth-Verknüpfungen benötigen verifizierte E-Mail-Adressen; prüfen Sie die Claim-Zuordnung Ihres Anbieters. Lesen Sie die Release Notes, bevor Sie bestehende Deployments erneut ausrollen.

Umstieg von 4.4 auf 4.5

Version 4.5.0 bringt laut Release Notes unter anderem Anmeldung per Passkey, einen Dateibrowser für Anwendungen und Datenbanken, eine Metrik-Übersicht für alle Server, Server-Patching (Beta) und eine automatische Sicherung der Coolify-Datenbank vor jedem Update. Klartext-Geheimnisse speichert Coolify jetzt verschlüsselt; der neue Befehl app-key:reencrypt verschlüsselt sie nach einem Wechsel des APP_KEY neu. Neue Pflichtvariablen gibt es nicht, die Compose-Dateien sind gegenüber 4.4.6 unverändert. Sichern Sie trotzdem vorher /data/coolify/ und die .env, und aktualisieren Sie wie in Schritt 7. Wer LATEST_IMAGE fest gesetzt hat, ändert den Wert auf 4.5.0.

Beim manuellen Update aus Schritt 7 von 4.4.6 auf 4.5.0 laufen die Datenbankmigrationen beim Start durch, /api/health und /up auf Port 6001 antworten mit 200, und der Container ist nach wenigen Sekunden healthy. Bestehende Projekte und Konten bleiben erhalten, die Anmeldung funktioniert wie vorher, und ein falsches Passwort führt zurück auf die Anmeldeseite.

Schritt 7: Updates und Backups

Coolify aktualisiert sich über Settings → Configuration → Updates im Dashboard (auch automatisch) oder über das offizielle Upgrade-Skript, das neue Compose-Dateien und Images lädt und die Container neu startet:

# Offizielles Upgrade-Skript (lädt Compose-Dateien und Images neu):

$ curl -fsSL https://cdn.coollabs.io/coolify/upgrade.sh | sudo bash

# Alternativ manuell (nur neue Images ziehen):
docker compose \
  --env-file /data/coolify/source/.env \
  -f /data/coolify/source/docker-compose.yml \
  -f /data/coolify/source/docker-compose.prod.yml \
  pull

docker compose \
  --env-file /data/coolify/source/.env \
  -f /data/coolify/source/docker-compose.yml \
  -f /data/coolify/source/docker-compose.prod.yml \
  up -d --remove-orphans --force-recreate

Sichern Sie die Coolify-Datenbank und die .env regelmäßig, etwa per pg_dump-Cronjob gegen den Container coolify-db. Anleitung: MySQL & PostgreSQL Backup automatisieren mit cron.

docker compose \
  --env-file /data/coolify/source/.env \
  -f /data/coolify/source/docker-compose.yml \
  -f /data/coolify/source/docker-compose.prod.yml \
  ps
# Nach Update: alle Container "Up (healthy)"

docker compose \
  --env-file /data/coolify/source/.env \
  -f /data/coolify/source/docker-compose.yml \
  -f /data/coolify/source/docker-compose.prod.yml \
  logs --tail=20 coolify
# Keine Fehler im App-Log

Grundlagen zum Betrieb finden Sie in Linux-Server absichern mit UFW und Fail2ban.

Troubleshooting / Typische Fehler

„Permission denied“ beim Containerstart

Die Bind-Mount-Verzeichnisse gehören nicht UID 9999. Lösung: sudo chown -R 9999:root /data/coolify und Container neu starten.

UI nicht erreichbar, Datenbankverbindung schlägt fehl

Meist fehlt die zweite Compose-Datei. Beide Dateien (docker-compose.yml und docker-compose.prod.yml) mit -f angeben.

„Port already in use“ / Port 8000 belegt

Lösung: APP_PORT=8080 (oder einen anderen freien Port) in /data/coolify/source/.env setzen, bevor der Stack das erste Mal gestartet wird.

Echtzeitdienst startet nicht (Port 6001 belegt)

Lösung: REVERB_PORT=6011 in .env eintragen und Stack neu starten.

Docker-Version zu alt

Coolify setzt Docker Engine 24 oder neuer voraus. Prüfen mit docker version, bei Bedarf Docker aus den offiziellen Paketquellen aktualisieren.

ARM64 / Raspberry Pi: Container startet nicht

Prüfen Sie, ob ein 64-Bit-OS läuft (uname -m → aarch64). 32-Bit-Raspberry-Pi-OS wird nicht unterstützt.

Server „localhost“ nicht erreichbar

Der öffentliche Schlüssel fehlt in /root/.ssh/authorized_keys oder der SSH-Dienst lehnt root-Anmeldung mit Schlüssel ab. Schritt 1 prüfen, in /etc/ssh/sshd_config muss PermitRootLogin prohibit-password oder yes stehen.

Netzwerk nicht attachable

Wurde docker network create coolify ohne --attachable angelegt, können deployte Apps später nicht ins Netzwerk eingehängt werden. Lösung: docker network rm coolify (erst wenn keine Container laufen), dann docker network create --attachable coolify.

Logs prüfen:

docker logs -f coolify           # App-Log
docker logs -f coolify-db        # PostgreSQL

Häufige Fragen

Kann ich Coolify auf einem Windows-Host betreiben?

Nein, nur auf 64-Bit-Linux, unter Windows also nur in einer Linux-VM.

Was passiert, wenn ich eines der Secrets nachträglich ändere?

Die Installation wird unbrauchbar, siehe Schritt 2. Die Passwörter für PostgreSQL und Redis müssen zu den bestehenden Daten passen.

Wie deploye ich meine erste eigene App?

Wie in Schritt 6: Repository (GitHub, GitLab, Gitea, Forgejo, Bitbucket) verbinden und „Deploy“ klicken. Automatisches Re-Deployment per Webhook aktivieren Sie in denselben Einstellungen.

Wie aktualisiere ich Coolify auf eine neue Version?

Siehe Schritt 7. Vorher Backup anlegen und die Release Notes lesen.

Wie richte ich HTTPS für die Coolify-UI ein?

Entweder per Domain in den Coolify-Einstellungen (Schritt 6) oder mit einem Reverse Proxy (Traefik, Caddy, Nginx) vor Port 8000. Bei einem eigenen Proxy müssen WebSockets (Port 6001) und das Web-Terminal (Port 6002) durchgereicht werden (Upgrade-Header, längere Timeouts).

Kann ich Coolify auf einem Raspberry Pi betreiben?

Ja, auf ARM64 (Raspberry Pi 4/5 mit 64-Bit-OS). Planen Sie 4 GB RAM ein, wenn dort auch Apps laufen.

Fazit

Die manuelle Installation folgt den offiziellen Compose-Dateien, eigene Änderungen gehören in docker-compose.custom.yml. Entscheidend sind drei Punkte: Admin-Konto sofort anlegen, die Secrets in der .env nur einmal erzeugen und sicher aufbewahren, Datenbank und .env regelmäßig sichern.

Weiterführende Anleitungen und Quellen

1. Docker und Docker Compose auf Linux installieren: die Self-Hosting-Grundlage
2. Traefik als Docker-Reverse-Proxy mit automatischem HTTPS einrichten
3. MySQL & PostgreSQL Backup automatisieren mit cron: mysqldump, pg_dump, Rotation und rclone-Cloud-Sync
4. Dokploy mit Docker installieren: Open-Source-Deployment-Plattform
5. VPS absichern und härten: Anleitung mit UFW, SSH-Keys und Fail2Ban

Offizielle Quellen: Coolify-Dokumentation (Installation), Coolify GitHub Repository, Offizielles docker-compose.yml (CDN).

Passende Anleitungen auf S-EDV

1. SSH-Key-Authentifizierung einrichten: Linux und Windows
2. Caddy als Reverse-Proxy mit automatischem HTTPS
3. Docker Compose absichern: Secrets, Healthchecks, Non-Root, Read-Only