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__):
| Pfad | Verwendung |
|---|---|
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/Dockerfile | Mehrstufiges Image auf Basis von serversideup/php:<ver>-fpm-nginx. |
assets/dockerignore | Als .dockerignore speichern. |
assets/docker-compose.prod.yml | app + worker + (scheduler) + mysql, die Datei, auf die Coolify verweist. |
assets/docker-compose.prod.local.yml | Workstation-Override: veröffentlicht :8080, keine Secure-Cookies. |
assets/env.docker.example | Als .env.docker.example speichern; Vorlage für lokale und Coolify-Umgebungen. |
assets/docker-build-push.sh | Als scripts/docker-build-push.sh speichern; baut amd64 und pusht latest + Git-SHA. |
references/variants.md | Postgres/MariaDB, Redis, Horizon, Reverb, Octane, SSR, Wayfinder, pnpm/yarn/bun, Chromium, SQLite-only. |
references/coolify.md | GHCR-Authentifizierung auf dem Server, Erstellen der Ressource, Domain :8080, Bereitstellen/Aktualisieren/Rollback. |
references/other-platforms.md | Dokploy, EasyPanel, CapRover, reines Docker + Caddy, Kubernetes-Notizen. |
references/troubleshooting.md | Symptom → Ursache → Lösungstabelle. Lesen, wenn etwas fehlschlägt. |
references/docs-template.md | Gliederung 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, weilcomposer.json^8.2sagt: 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 ininstall-php-extensionskommt.gmp/bcmatherscheinen 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, siehereferences/variants.md.queues–needs_workerundworker_queue_arg. Der--queue=des Workers muss jede benannte Warteschlange auflisten (vononQueue,$queue,viaQueues()), sonst bleiben diese Jobs für immer in der Tabelle, während der Default-Queue-Worker gesund aussieht.scheduler.has_scheduled_tasks→ denscheduler-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. Beachteconfig_defaultist oftsqlite: wennDB_CONNECTIONim 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, dassnpm ciin Linux fehlschlägt. Führerepair_npm_lock.pyaus (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 vorhandenedocker-compose.yml(oft Sail für die Entwicklung); die Produktionsdatei istdocker-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-Archlinux/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 Laravelhttp://-URLs (Mixed Content, kaputte Livewire/Filament-Assets, unsichere Cookies, Web-Push schlägt fehl). Laravel 11+: inbootstrap/app.php:Laravel ≤10: setze->withMiddleware(function (Middleware $middleware): void { $middleware->trustProxies(at: '*'); })protected $proxies = '*';inapp/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:
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.python3 <skill-verz>/scripts/repair_npm_lock.py <projekt-verz> .env.example: Schlüssel hinzufügen, die die App liest, die das Beispiel aber nicht hat (vergleicheenv(-Aufrufe inconfig/mit der Datei), damit die Deploy-Dokumentation vollständig ist..gitignore:.env.dockerhinzufü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;schedulerauskommentieren, wenn es geplante Aufgaben gibt. - DB-Service / env für Postgres, MariaDB oder Redis gemäß
references/variants.mdumstellen. - 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 derconfig/app.phpder 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-dataauf :8080,/up-Healthchecks,healthcheck-queue/healthcheck-scheduleundAUTORUN_ENABLED, dasstorage:linkausführt, auf die DB wartet,migrate --forceundphp artisan optimizeausführt (dies beinhaltetfilament:optimizeund andere Optimierungs-Hooks von Paketen). Nur derapp-Service setztAUTORUN_ENABLED=true, sodass Migrationen einmal laufen; Worker/Scheduler warten, bisappgesund 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:
- Alle Services
healthy;app-Logs zeigenstorage:link, Migrationen,optimizeohne ❌. curl -s -o /dev/null -w '%{http_code}' localhost:8080/up→ 200; die Login/Startseite → 200 und ihre CSS/JS-URLs liefern 200.- Proxy:
curl -s -H 'X-Forwarded-Proto: https' -H 'X-Forwarded-Host: x.example.com' localhost:8080/<seite>→ Asset-URLs beginnen mithttps://x.example.com. php artisan db:seed --force(wenn die App Seeders hat, die der Benutzer bei der ersten Installation erwartet).- Queue: Dispatche eine echte queued-Klasse (eine Benachrichtigung/einen Job aus der App) in jede benannte Warteschlange und bestätige, dass der Worker
DONElogged und der Nebeneffekt eingetreten ist. Closures, die vontinker --executedispatched werden, schlagen im Worker fehl (eval-Code kann nicht deserialisiert werden) – das ist ein Testartefakt, kein Fehler. Respektiere auch dieshouldSend/Autorisierung der App bei der Auswahl eines Testempfängers. - Speicher: Schreibe eine Datei auf dem
public-Disk vom Worker aus, rufe sie überlocalhost:8080/storage/...von der App ab, danndown+upund bestätige, dass Dateien und DB-Zeilen bestehen bleiben. - Cross-Build für den Server:
docker buildx build --platform linux/amd64 -t <name>:amd64 --load .danndocker 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:
echo <PAT mit write:packages> | docker login ghcr.io -u <benutzer> --password-stdin- Commit, dann
scripts/docker-build-push.sh(lehnt einen unreinen Baum ab;--loadfür reine lokale Builds). - Coolify-Schritte aus
references/coolify.md– insbesondere, dass der Server einen schreibgeschützten GHCR-Login für ein privates Paket benötigt, durchgeführt mitsudo docker login(Coolify zieht als root; ein Nicht-Root-Login ist für ihn unsichtbar), und die Domain wird alshttps://domain:8080eingegeben (:8080= Container-Port). - 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.