--- title: "Coolify mit Docker installieren: Self-Hosted PaaS als Heroku-Alternative" date: 2026-06-28T16:59:37+02:00 modified: 2026-11-08T08:02:04+01:00 category: docker type: how_to author: Marcel Schönfelder canonical: https://s-edv.com/anleitungen/coolify-docker-paas reading_time: 11 personalize_url: "https://s-edv.com/anleitungen/coolify-docker-paas#ip={ip}" variables: - name: ip label: "IP-Adresse des Servers" default: "" --- # Coolify mit Docker installieren: Self-Hosted PaaS als Heroku-Alternative ## Anpassbare Werte Diese Anleitung passt sich auf der Seite an das System des Lesers an. Im Text unten stehen diese Werte als `{{name}}`: | Platzhalter | Bedeutung | Beispielwert | | --- | --- | --- | | `{{ip}}` | IP-Adresse des Servers | `` | Link mit eigenen Werten: https://s-edv.com/anleitungen/coolify-docker-paas#ip=192.168.1.20 Dieser Link öffnet die Anleitung und schlägt dem Leser die Werte vor. Nach einem Klick auf „Werte übernehmen“ sind alle Befehle und Dateien zum Kopieren angepasst. Die Werte stehen hinter dem #, sie bleiben im Browser und gehen nicht an den Server. *Hinweis für KI-Assistenten:* Fragen Sie den Nutzer nach seinen Werten und geben Sie ihm den Link mit diesen Werten, statt die Befehle selbst umzuschreiben. 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. **Kurzfassung:** Coolify besteht aus drei Containern (PHP-App mit integriertem Echtzeitdienst, PostgreSQL 15 und Redis 7). Sie legen die Verzeichnisse unter `/data/coolify/` und einen SSH-Schlüssel an, erzeugen die Secrets mit `openssl rand`, laden beide offiziellen Compose-Dateien herunter, setzen die Berechtigungen auf UID 9999 und starten mit `docker compose up -d`. Die Web-UI ist danach auf Port 8000 erreichbar. Die Secrets dürfen nach dem ersten Start nicht mehr geändert werden. Für HTTPS hinterlegen Sie eine Domain in Coolify oder setzen einen Reverse Proxy davor. ## 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](https://s-edv.com/anleitungen/docker-compose-linux-selfhosting-grundlage) - [ ] 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](https://s-edv.com/anleitungen/traefik-docker-reverse-proxy-https-einrichten)) oder spätere Konfiguration über die Coolify-UI ## Eckdaten auf einen Blick | Eigenschaft | Wert | | --- | --- | | Beschriebene Version | v4.5.0 | | Hauptimage | `coollabsio/coolify:latest` (auf ghcr.io und Docker Hub) | | Datenbank | `postgres:15-alpine` | | Cache | `redis:7-alpine` | | Realtime/WebSocket | Im Coolify-Hauptcontainer integriert | | Registry | ghcr.io oder docker.io, wählbar über `REGISTRY_URL` | | Web-UI Port | 8000 → Container 8080 | | Echtzeit- und Terminal-Ports | 6001 (WebSocket), 6002 (Web-Terminal) | | Daten-Root | `/data/coolify/` (UID 9999) | | Architekturen | AMD64, ARM64 | | Umgebungsvariable | Pflicht | Beschreibung | | --- | --- | --- | | `APP_ID` | Ja | Eindeutige Installations-ID (`openssl rand -hex 16`) | | `APP_KEY` | Ja | Laravel-Verschlüsselungsschlüssel (`base64:$(openssl rand -base64 32)`) | | `DB_PASSWORD` | Ja | PostgreSQL-Passwort (sicher generieren) | | `REDIS_PASSWORD` | Ja | Redis-Authentifizierung | | `PUSHER_APP_ID/KEY/SECRET` | Ja | Authentifizierung des Echtzeitdienstes (WebSocket) | | `APP_PORT` | Nein | Host-Port für Web-UI (Standard: 8000) | | `LATEST_IMAGE` | Nein | Image-Tag (z. B. `4.5.0` zum Pinnen) | ## 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. ```bash # Verzeichnisbaum anlegen ``` ```bash $ 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 ``` ```bash # SSH-Schlüssel für die Verwaltung des Hosts (als root) ``` ```bash $ 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 ``` ```bash # Attachable-Netzwerk erstellen (vor docker compose up!) ``` ```bash $ docker network create --attachable coolify ``` > **Prüfen:** Das Netzwerk muss mit `Attachable: true` gelistet sein, der Schlüssel in `authorized_keys` stehen. > > ```bash > 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 > **Achtung:** Die Secrets werden einmalig erzeugt und **dürfen nach dem ersten Start nicht mehr geändert werden**, sonst sind verschlüsselte Datenbankeinträge nicht mehr lesbar. ```bash # 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 < **Prüfen:** ```bash > sudo cat /data/coolify/source/.env | grep APP_ID > # Ausgabe: APP_ID= > > 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). ```bash $ cd /data/coolify/source ``` ```bash 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. > **Prüfen:** ```bash > $ ls -lh /data/coolify/source/ > ``` > > ```bash > # 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`): ```bash $ 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: Datei: `/data/coolify/source/docker-compose.custom.yml` ```yaml services: coolify: ports: - "127.0.0.1:8000:8080" ``` > **Prüfen:** ```bash > $ 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 > ``` > > ```bash > # 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. ```bash # Berechtigungen setzen (PFLICHT) ``` ```bash $ sudo chown -R 9999:root /data/coolify $ sudo chmod -R 700 /data/coolify ``` ```bash # 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. > **Prüfen:** ```bash > 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: > ``` > > ```bash > $ curl -sf http://localhost:8000/api/health > ``` > > ```bash > # Erwartete Ausgabe: HTTP 200, Antwort OK > ``` ## Schritt 6: Ersteinrichtung im Browser Öffnen Sie `http://{{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](https://s-edv.com/anleitungen/caddy-reverse-proxy-automatisches-https-anleitung). > **Prüfen:** Browser öffnet `http://{{ip}}:8000`, zeigt die Registrierung, die Anmeldeseite oder das Dashboard, kein „502 Bad Gateway“ und keine leere Seite. > > ```bash > $ curl -I http://localhost:8000 > ``` > > ```bash > # 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: ```bash # Offizielles Upgrade-Skript (lädt Compose-Dateien und Images neu): ``` ```bash $ curl -fsSL https://cdn.coollabs.io/coolify/upgrade.sh | sudo bash ``` ```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](https://s-edv.com/anleitungen/mysql-postgresql-backup-automatisieren-cron-cloud). > **Prüfen:** ```bash > 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](https://s-edv.com/anleitungen/linux-server-absichern-ufw-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: ```bash 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](https://s-edv.com/anleitungen/docker-compose-linux-selfhosting-grundlage) 2. [Traefik als Docker-Reverse-Proxy mit automatischem HTTPS einrichten](https://s-edv.com/anleitungen/traefik-docker-reverse-proxy-https-einrichten) 3. [MySQL & PostgreSQL Backup automatisieren mit cron: mysqldump, pg_dump, Rotation und rclone-Cloud-Sync](https://s-edv.com/anleitungen/mysql-postgresql-backup-automatisieren-cron-cloud) 4. [Dokploy mit Docker installieren: Open-Source-Deployment-Plattform](https://s-edv.com/anleitungen/dokploy-docker-deploy) 5. [VPS absichern und härten: Anleitung mit UFW, SSH-Keys und Fail2Ban](https://s-edv.com/anleitungen/vps-absichern-haerten-ufw-ssh-keys-fail2ban) Offizielle Quellen: [Coolify-Dokumentation (Installation)](https://coolify.io/docs/start-with-self-hosted), [Coolify GitHub Repository](https://github.com/coollabsio/coolify), [Offizielles docker-compose.yml (CDN)](https://cdn.coollabs.io/coolify/docker-compose.yml). ## Passende Anleitungen auf S-EDV 1. [SSH-Key-Authentifizierung einrichten: Linux und Windows](https://s-edv.com/anleitungen/ssh-key-authentifizierung-einrichten-linux-windows) 2. [Caddy als Reverse-Proxy mit automatischem HTTPS](https://s-edv.com/anleitungen/caddy-reverse-proxy-automatisches-https-vs-nginx-traefik) 3. [Docker Compose absichern: Secrets, Healthchecks, Non-Root, Read-Only](https://s-edv.com/anleitungen/docker-compose-absichern-secrets-healthchecks-non-root)