CommunityCodierung & Entwicklunggithub.com

Laravel Coolify Docker

Containerisiere eine Laravel-App für die Produktion und stelle sie mit Coolify bereit – erstelle das Image auf deinem eigenen Rechner (inklusive Apple Silicon → amd64 Cross-Builds), schiebe es in die GitHub Container Registry (ghcr.io) und führe es als Docker Compose Stack aus (Web + Queue Worker + Scheduler + Datenbank).

Was ist Laravel Coolify Docker?

Diese Skill-Anleitung automatisiert die Containerisierung von Laravel-Projekten für den produktiven Einsatz mit Coolify (und ähnlichen Plattformen wie Dokploy, EasyPanel oder CapRover). Sie erzeugt ein Dockerfile auf Basis von 'serversideup/php', eine produktionsreife docker-compose.prod.yml, ein Build- und Push-Skript sowie eine umfassende Dokumentation. Der Workflow umfasst die Analyse des Projekts (PHP-Version, Erweiterungen, Queues, Scheduler, Datenbanktreiber), die Reparatur von npm-Lock-Dateien für Linux-Binärpakete, die Konfiguration des Vertrauensproxys für HTTPS und die lokale Verifikation des Stacks vor der Bereitstellung. Das Besondere: Das Image wird auf dem Entwicklungsrechner erstellt (auch als Cross-Build für amd64) und in ghcr.io gepusht – der Server zieht es nur noch und führt es aus. So werden Build-Artefakte und Secrets vermieden, und die Konfiguration erfolgt ausschließlich über Umgebungsvariablen. Die Anleitung enthält zudem Referenzen für Varianten (Postgres, Redis, Horizon, Octane, SSR, Chromium), Fehlerbehebung und andere Plattformen.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/uluumbch/laravel-coolify-docker/tree/HEAD/skills/laravel-coolify-docker

Installed? Explore more Codierung & Entwicklung skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Laravel → Docker → GHCR → Coolify

Das Zielsetup: Das Image wird auf dem Entwicklerrechner erstellt, in ghcr.io gepusht, und der Server (Coolify) zieht es nur und führt es aus über eine Compose-Datei. Kein Bauen auf dem Server, keine Secrets im Image, die gesamte Konfiguration erfolgt über Umgebungsvariablen.

workstation ── docker buildx (linux/amd64) ──push──▶ ghcr.io/<owner>/<repo>:latest,:<sha>
                                                          │ pull
server (Coolify) ── docker-compose.prod.yml ──▶ app (nginx+php-fpm :8080) · worker · [scheduler] · db

Mitgelieferte Dateien (kopieren und anpassen; Platzhalter sehen aus wie __IMAGE__):

PfadVerwendung
scripts/inspect_laravel.py <verz>Nur-Lese-Projekt-Scan → JSON-Fakten. Zuerst ausführen.
scripts/repair_npm_lock.py <verz>Repariert eine package-lock.json, der native Linux-Binärpakete fehlen (benötigt Docker).
assets/DockerfileMehrstufiges Image auf Basis von serversideup/php:<ver>-fpm-nginx.
assets/dockerignoreAls .dockerignore speichern.
assets/docker-compose.prod.ymlapp + worker + (scheduler) + mysql, die Datei, auf die Coolify verweist.
assets/docker-compose.prod.local.ymlWorkstation-Override: veröffentlicht :8080, keine Secure-Cookies.
assets/env.docker.exampleAls .env.docker.example speichern; Vorlage für lokale und Coolify-Umgebungen.
assets/docker-build-push.shAls scripts/docker-build-push.sh speichern; baut amd64 und pusht latest + Git-SHA.
references/variants.mdPostgres/MariaDB, Redis, Horizon, Reverb, Octane, SSR, Wayfinder, pnpm/yarn/bun, Chromium, SQLite-only.
references/coolify.mdGHCR-Authentifizierung auf dem Server, Erstellen der Ressource, Domain :8080, Bereitstellen/Aktualisieren/Rollback.
references/other-platforms.mdDokploy, EasyPanel, CapRover, reines Docker + Caddy, Kubernetes-Notizen.
references/troubleshooting.mdSymptom → Ursache → Lösungstabelle. Lesen, wenn etwas fehlschlägt.
references/docs-template.mdGliederung für die docs/DOCKER_DEPLOYMENT.md, die du für das Projekt schreibst.

Wenn der Benutzer nur eine Frage oder einen Fehler hat (keine vollständige Einrichtung), gehe direkt zu references/troubleshooting.md oder der entsprechenden Referenz, anstatt den gesamten Workflow durchzuführen.

Workflow

1. Projekt inspizieren

python3 <skill-verz>/scripts/inspect_laravel.py <projekt-verz>

Es meldet die Fakten, die das Image und den Stack bestimmen. Lies sie genau – jedes Feld führt zu einer Entscheidung:

  • php.allowed – PHP-Minor-Versionen, die jedes gesperrte Paket akzeptiert. Wähle die höchste erlaubte für den Basis-Image-Tag. Wenn leer, ist der Lock auf keiner einzelnen Version erfüllbar; teile dem Benutzer mit, welche Pakete blockieren (php.blocked_by). Wähle keine Version nur, weil composer.json ^8.2 sagt: transitive Pakete (z. B. openspout ~8.2||~8.3||~8.4, Symfony 8 >=8.4.1) schränken ein, und der Build schlägt spät fehl, wenn du falsch liegst.
  • extensions.install_on_serversideup – genau das, was in install-php-extensions kommt. gmp/bcmath erscheinen zusammen bei Web-Push; beide zu installieren ist in Ordnung.
  • extensions.system_binaries – Pakete, die Betriebssystem-Binärdateien benötigen (Chromium, wkhtmltopdf, ffmpeg). Überprüfe, ob der Code sie tatsächlich verwendet, bevor du das Image aufblähst (grep nach der Klasse); falls verwendet, siehe references/variants.md.
  • queues – needs_worker und worker_queue_arg. Der --queue= des Workers muss jede benannte Warteschlange auflisten (von onQueue, $queue, viaQueues()), sonst bleiben diese Jobs für immer in der Tabelle, während der Default-Queue-Worker gesund aussieht.
  • scheduler.has_scheduled_tasks → den scheduler-Service hinzufügen.
  • packages.key_packages – Horizon ersetzt den Worker; Reverb fügt einen WebSocket-Service hinzu; Octane ändert das Basis-Image (siehe Varianten).
  • database – der Treiber für den Compose-DB-Service. Beachte config_default ist oft sqlite: wenn DB_CONNECTION im Container nicht gesetzt ist, verwendet Laravel stillschweigend SQLite. Die Compose-Datei setzt es aus diesem Grund explizit.
  • frontend.npm_lock_missing_linux_binaries – nicht leer bedeutet, dass npm ci in Linux fehlschlägt. Führe repair_npm_lock.py aus (Schritt 3).
  • frontend.vite_needs_php_at_build – Wayfinder etc. benötigen PHP während des Vite-Builds; siehe Varianten.
  • proxy.bootstrap_trustProxies / legacy_TrustProxies_middleware – ob der Proxy-Fix aus Schritt 3 benötigt wird.
  • git.ghcr_image – Imagename (GHCR erfordert Kleinbuchstaben).
  • existing_files – Überschreibe keine vorhandene docker-compose.yml (oft Sail für die Entwicklung); die Produktionsdatei ist docker-compose.prod.yml.

Überfliege auch den Code auf Dinge, die der Scan nicht beurteilen kann: Provider, die beim Booten auf die DB zugreifen (bricht composer dump-autoload / optimize während des Builds), Code, der file_get_contents(asset(...)) seiner eigenen URL verwendet, hartcodierte storage_path-Annahmen.

2. Die wenigen Dinge bestätigen, die nur der Benutzer weiß

Frage kurz (eine Runde) mit sinnvollen Standardwerten, wenn es dem Benutzer egal ist:

  • Server-CPU-Architektur – normalerweise linux/amd64 (die meisten VPS). ARM-Server (Hetzner CAX, Oracle Ampere, Graviton) → linux/arm64. Unbekannt → Multi-Arch linux/amd64,linux/arm64 (langsamerer Build). Das ist wichtig, weil ein auf einem Mac erstelltes arm64-Image auf einem amd64-Server nicht startet (exec format error).
  • Datenbank: im Compose-Stack ausführen (am einfachsten, empfohlen) oder eine vorhandene/managed DB verwenden (den mysql-Service entfernen, DB_HOST übergeben).
  • Alles, was unberührt bleiben soll (alte Deploy-Workflows, Sail-Compose-Datei).

3. Den Code container-bereit machen

  • Dem Proxy vertrauen. Coolifys Traefik beendet TLS und leitet HTTP weiter. Ohne Vertrauen in X-Forwarded-* generiert Laravel http://-URLs (Mixed Content, kaputte Livewire/Filament-Assets, unsichere Cookies, Web-Push schlägt fehl). Laravel 11+: in bootstrap/app.php:
    ->withMiddleware(function (Middleware $middleware): void {
        $middleware->trustProxies(at: '*');
    })
    
    Laravel ≤10: setze protected $proxies = '*'; in app/Http/Middleware/TrustProxies.php. '*' ist nur sicher, weil Port 8080 nie im Internet veröffentlicht wird – sag das in der Dokumentation.
  • Die npm-Lockdatei reparieren, wenn der Scan sie markiert hat:
    python3 <skill-verz>/scripts/repair_npm_lock.py <projekt-verz>
    
    Es löst nur native Binärpakete neu auf (rollup, esbuild, lightningcss, Tailwind oxide, swc, sass-embedded); melde die Versionssprünge, die es dem Benutzer ausgibt.
  • .env.example: Schlüssel hinzufügen, die die App liest, die das Beispiel aber nicht hat (vergleiche env(-Aufrufe in config/ mit der Datei), damit die Deploy-Dokumentation vollständig ist.
  • .gitignore: .env.docker hinzufügen.

4. Die Docker-Dateien generieren

Aus assets/ in das Projekt kopieren und Platzhalter ausfüllen: __IMAGE__, __REPO_URL__ (https GitHub-URL, verknüpft das GHCR-Paket mit dem Repository), __APP_NAME__, __PHP_VERSION__, __PHP_EXTENSIONS__, __QUEUES__. Dann anpassen:

  • Den worker-Service entfernen, wenn nichts in der Warteschlange ist; scheduler auskommentieren, wenn es geplante Aufgaben gibt.
  • DB-Service / env für Postgres, MariaDB oder Redis gemäß references/variants.md umstellen.
  • App-spezifische Env-Keys (API-Keys, VAPID, S3) zum x-app-env-Anker als ${VAR:-} hinzufügen; wirklich erforderliche als ${VAR:?msg} markieren, damit ein fehlender Wert laut fehlschlägt, anstatt halb konfiguriert zu booten.
  • APP_TIMEZONE-Standard auf den Standard der config/app.php der App setzen.
  • Paketmanager ≠ npm, kein package.json, SSR, Chromium → references/variants.md.

In die Vorlagen eingebaute Designentscheidungen (beibehalten, es sei denn, es gibt einen Grund):

  • serversideup/php liefert NGINX+FPM als Nicht-Root www-data auf :8080, /up-Healthchecks, healthcheck-queue/healthcheck-schedule und AUTORUN_ENABLED, das storage:link ausführt, auf die DB wartet, migrate --force und php artisan optimize ausführt (dies beinhaltet filament:optimize und andere Optimierungs-Hooks von Paketen). Nur der app-Service setzt AUTORUN_ENABLED=true, sodass Migrationen einmal laufen; Worker/Scheduler warten, bis app gesund ist.
  • Assets-Stufe auf $BUILDPLATFORM – läuft nativ auf dem Mac, während PHP-Stufen für amd64 emuliert werden; Ausgabe ist architekturunabhängig.
  • Composer install vor dem Kopieren des Quellcodes – die Abhängigkeitsebene bleibt zwischengespeichert; reine Code-Neuerstellungen sind selbst unter Emulation schnell.
  • Ein gemeinsames storage/app-Volume für App + Worker (+ Scheduler) – Dateien, die ein Job schreibt, müssen für den Web-Container sichtbar sein.
  • Logs auf stderr – damit der Log-Viewer der Plattform sie anzeigt.

5. Lokal verifizieren, bevor etwas gepusht wird

Mach das richtig – hör nicht bei "das Dockerfile sieht richtig aus" auf. Verwende einen Compose-Projektnamen, damit es nicht mit Entwicklungscontainern kollidiert.

docker buildx build --load -t <name>:test .                       # native Architektur, schnell
docker run --rm --entrypoint php <name>:test -m                  # Erweiterungen vorhanden?
docker run --rm --entrypoint php <name>:test artisan key:generate --show
cp .env.docker.example .env.docker   # APP_IMAGE=<name>, IMAGE_TAG=test, PULL_POLICY=never, key, Passwörter
docker compose -p <name>test --env-file .env.docker -f docker-compose.prod.yml -f docker-compose.prod.local.yml up -d --wait

(--entrypoint php überspringt serversideups Banner/Automatisierungen, sodass einmalige Befehle saubere Ausgabe liefern.)

Überprüfe und melde jedes Ergebnis:

  1. Alle Services healthy; app-Logs zeigen storage:link, Migrationen, optimize ohne ❌.
  2. curl -s -o /dev/null -w '%{http_code}' localhost:8080/up → 200; die Login/Startseite → 200 und ihre CSS/JS-URLs liefern 200.
  3. Proxy: curl -s -H 'X-Forwarded-Proto: https' -H 'X-Forwarded-Host: x.example.com' localhost:8080/<seite> → Asset-URLs beginnen mit https://x.example.com.
  4. php artisan db:seed --force (wenn die App Seeders hat, die der Benutzer bei der ersten Installation erwartet).
  5. Queue: Dispatche eine echte queued-Klasse (eine Benachrichtigung/einen Job aus der App) in jede benannte Warteschlange und bestätige, dass der Worker DONE logged und der Nebeneffekt eingetreten ist. Closures, die von tinker --execute dispatched werden, schlagen im Worker fehl (eval-Code kann nicht deserialisiert werden) – das ist ein Testartefakt, kein Fehler. Respektiere auch die shouldSend/Autorisierung der App bei der Auswahl eines Testempfängers.
  6. Speicher: Schreibe eine Datei auf dem public-Disk vom Worker aus, rufe sie über localhost:8080/storage/... von der App ab, dann down + up und bestätige, dass Dateien und DB-Zeilen bestehen bleiben.
  7. Cross-Build für den Server: docker buildx build --platform linux/amd64 -t <name>:amd64 --load . dann docker image inspect <name>:amd64 --format '{{.Architecture}}'. Im Hintergrund ausführen – QEMU-Builds dauern Minuten.

Mach mit docker compose -p <name>test down -v sauber, wenn fertig.

6. Die Deploy-Dokumentation schreiben

Erstelle docs/DOCKER_DEPLOYMENT.md nach references/docs-template.md in der Sprache der vorhandenen Projektdokumentation und verlinke sie von README.md. Die Dokumentation muss erklären, was sich geändert hat und warum für jede Datei (der Benutzer hat danach gefragt, als diese Skill erstellt wurde, und zukünftige Betreuer benötigen es), die Architektur, die einmalige Einrichtung, Build/Push, lokales Testen, Coolify-Schritte, Aktualisierung/Rollback, Betrieb, Migration von Daten vom alten Host und projektspezifische Besonderheiten, die du in Schritt 1 gefunden hast.

7. Übergabe – bestätigen, bevor etwas nach außen geht

Das Pushen nach GHCR veröffentlicht das Image, und das Bereitstellen verändert die Produktion, also halte an und lass den Benutzer entscheiden. Gib ihnen:

  1. echo <PAT mit write:packages> | docker login ghcr.io -u <benutzer> --password-stdin
  2. Commit, dann scripts/docker-build-push.sh (lehnt einen unreinen Baum ab; --load für reine lokale Builds).
  3. Coolify-Schritte aus references/coolify.md – insbesondere, dass der Server einen schreibgeschützten GHCR-Login für ein privates Paket benötigt, durchgeführt mit sudo docker login (Coolify zieht als root; ein Nicht-Root-Login ist für ihn unsichtbar), und die Domain wird als https://domain:8080 eingegeben (:8080 = Container-Port).
  4. Erinnerungen: den alten APP_KEY (und VAPID oder andere langlebige Keys) bei der Migration wiederverwenden; den alten SSH/FTP-Deploy-Workflow deaktivieren, sobald der neue Deploy live ist.

Biete an, den Push für sie auszuführen, sobald sie eingeloggt sind.

Häufige Benutzerverwirrung vorwegnehmen

Benutzer versuchen oft docker run <image> oder den ▶-Button von Docker Desktop auf dem Image allein. Das startet nur den Web-Container: kein DB-Service existiert, Autorun ist aus, und Laravel fällt auf sqlite zurück (Database file at path [...] does not exist) oder schlägt beim Auflösen von mysql fehl. Die Antwort ist immer der Compose-Stack. Sag das im Abschnitt zum lokalen Testen der Dokumentation.

Verwandte Skills