Laravel → Docker → GHCR → Coolify
La configuration cible : l'image est construite sur la machine du développeur, poussée sur ghcr.io, et le serveur (Coolify) ne fait que la tirer et l'exécuter via un fichier compose. Pas de construction sur le serveur, pas de secrets dans l'image, toute la configuration via les variables d'environnement.
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
Fichiers fournis (à copier et adapter ; les espaces réservés ressemblent à __IMAGE__) :
| Chemin | Utilisation |
|---|---|
scripts/inspect_laravel.py <dir> | Analyse en lecture seule du projet → faits JSON. Exécutez ceci d'abord. |
scripts/repair_npm_lock.py <dir> | Corrige un package-lock.json qui manque de binaires natifs Linux (nécessite Docker). |
assets/Dockerfile | Image multi-étapes basée sur serversideup/php:<ver>-fpm-nginx. |
assets/dockerignore | Enregistrer sous .dockerignore. |
assets/docker-compose.prod.yml | app + worker + (scheduler) + mysql, le fichier pointé par Coolify. |
assets/docker-compose.prod.local.yml | Surcharge pour la station de travail : publie :8080, pas de cookies sécurisés. |
assets/env.docker.example | Enregistrer sous .env.docker.example ; modèle pour l'environnement local et Coolify. |
assets/docker-build-push.sh | Enregistrer sous scripts/docker-build-push.sh ; construit amd64 et pousse latest + le SHA Git. |
references/variants.md | Postgres/MariaDB, Redis, Horizon, Reverb, Octane, SSR, Wayfinder, pnpm/yarn/bun, Chromium, SQLite uniquement. |
references/coolify.md | Authentification GHCR sur le serveur, création de la ressource, domaine :8080, déploiement/mise à jour/retour arrière. |
references/other-platforms.md | Dokploy, EasyPanel, CapRover, Docker simple + Caddy, notes Kubernetes. |
references/troubleshooting.md | Tableau symptôme → cause → solution. À lire en cas d'échec. |
references/docs-template.md | Plan pour le fichier docs/DOCKER_DEPLOYMENT.md à écrire pour le projet. |
Si l'utilisateur a seulement une question ou un échec (pas une configuration complète), allez directement à references/troubleshooting.md ou à la référence pertinente au lieu d'exécuter tout le workflow.
Workflow
1. Inspecter le projet
python3 <skill-dir>/scripts/inspect_laravel.py <project-dir>
Il rapporte les faits qui déterminent l'image et la stack. Lisez-le attentivement — chaque champ correspond à une décision :
php.allowed— les versions mineures PHP que tous les paquets verrouillés acceptent. Choisissez la plus élevée autorisée pour le tag de l'image de base. Si elle est vide, le verrou n'est satisfaisable sur aucune version unique ; dites à l'utilisateur quels paquets bloquent (php.blocked_by). Ne choisissez pas une version juste parce quecomposer.jsondit^8.2: les paquets transitifs (par ex. openspout~8.2||~8.3||~8.4, Symfony 8>=8.4.1) la réduisent, et la construction échoue tard si vous devinez mal.extensions.install_on_serversideup— exactement ce qui va dansinstall-php-extensions.gmp/bcmathapparaissent ensemble pour les notifications web ; installer les deux est correct.extensions.system_binaries— paquets qui nécessitent des binaires OS (Chromium, wkhtmltopdf, ffmpeg). Vérifiez si le code les utilise réellement avant de gonfler l'image (grep pour la classe) ; si utilisés, voirreferences/variants.md.queues—needs_workeretworker_queue_arg. Le--queue=du worker doit lister chaque file nommée (deonQueue,$queue,viaQueues()), sinon ces jobs restent dans la table pour toujours pendant que le worker de la file par défaut semble sain.scheduler.has_scheduled_tasks→ ajoutez le servicescheduler.packages.key_packages→ Horizon remplace le worker ; Reverb ajoute un service websocket ; Octane change l'image de base (voir les variantes).database— le pilote pour le service DB du compose. Notez queconfig_defaultest souventsqlite: siDB_CONNECTIONn'est pas défini dans le conteneur, Laravel utilise silencieusement SQLite. Le fichier compose le définit explicitement pour cette raison.frontend.npm_lock_missing_linux_binaries— non vide signifie quenpm ciéchouera sous Linux. Exécutezrepair_npm_lock.py(étape 3).frontend.vite_needs_php_at_build— Wayfinder etc. nécessitent PHP pendant la construction Vite ; voir les variantes.proxy.bootstrap_trustProxies/legacy_TrustProxies_middleware— indique si la correction du proxy de l'étape 3 est nécessaire.git.ghcr_image— nom de l'image (GHCR nécessite des minuscules).existing_files— ne pas écraser un fichierdocker-compose.ymlexistant (souvent Sail pour le développement) ; le fichier de production estdocker-compose.prod.yml.
Parcourez aussi le code pour des choses que l'analyse ne peut pas juger : des providers qui accèdent à la DB au démarrage (casse composer dump-autoload / optimize pendant la construction), du code qui fait file_get_contents(asset(...)) sa propre URL, des hypothèses dures de storage_path.
2. Confirmer les quelques éléments que seul l'utilisateur connaît
Demandez brièvement (un seul tour), en fixant des valeurs par défaut sensées s'ils ne s'en soucient pas :
- Architecture CPU du serveur — généralement
linux/amd64(la plupart des VPS). Serveurs ARM (Hetzner CAX, Oracle Ampere, Graviton) →linux/arm64. Inconnu → multi-archlinux/amd64,linux/arm64(construction plus lente). Cela compte car une image arm64 construite sur un Mac ne démarrera pas sur un serveur amd64 (exec format error). - Base de données : l'exécuter dans la stack compose (le plus simple, recommandé) ou utiliser une DB existante/gérée (supprimez le service
mysql, passezDB_HOST). - Tout ce qui doit rester intact (anciens workflows de déploiement, fichier compose Sail).
3. Préparer le code pour les conteneurs
- Faire confiance au proxy. Le Traefik de Coolify termine le TLS et transmet HTTP. Sans faire confiance à
X-Forwarded-*, Laravel génère des URLshttp://(contenu mixte, assets Livewire/Filament cassés, cookies non sécurisés, échec des notifications web). Laravel 11+ : dansbootstrap/app.phpLaravel ≤10 : définissez->withMiddleware(function (Middleware $middleware): void { $middleware->trustProxies(at: '*'); })protected $proxies = '*';dansapp/Http/Middleware/TrustProxies.php.'*'est sûr uniquement parce que le port 8080 n'est jamais publié sur Internet — mentionnez-le dans la documentation. - Réparer le fichier npm lock si l'analyse l'a signalé :
Il ne re-résout que les paquets de binaires natifs (rollup, esbuild, lightningcss, Tailwind oxide, swc, sass-embedded) ; rapportez les changements de version qu'il imprime à l'utilisateur.python3 <skill-dir>/scripts/repair_npm_lock.py <project-dir> .env.example: ajoutez les clés que l'application lit mais que l'exemple ne contient pas (comparez les appelsenv(dansconfig/avec le fichier) pour que la documentation de déploiement soit complète..gitignore: ajoutez.env.docker.
4. Générer les fichiers Docker
Copiez depuis assets/ dans le projet et remplissez les espaces réservés : __IMAGE__, __REPO_URL__ (URL GitHub https, lie le paquet GHCR au dépôt), __APP_NAME__, __PHP_VERSION__, __PHP_EXTENSIONS__, __QUEUES__. Ensuite adaptez :
- Supprimez le service
workersi rien n'est mis en file d'attente ; décommentezschedulers'il y a des tâches planifiées. - Remplacez le service DB / les variables d'environnement pour Postgres, MariaDB ou Redis selon
references/variants.md. - Ajoutez les clés d'environnement spécifiques à l'application (clés API, VAPID, S3) à l'ancre
x-app-envcomme${VAR:-}; marquez celles vraiment requises comme${VAR:?msg}pour qu'une valeur manquante échoue bruyamment au lieu de démarrer à moitié configuré. - Définissez la valeur par défaut de
APP_TIMEZONEsur celle duconfig/app.phpde l'application. - Gestionnaire de paquets ≠ npm, pas de
package.json, SSR, Chromium →references/variants.md.
Décisions de conception intégrées dans les modèles (gardez-les sauf s'il y a une raison) :
- serversideup/php fournit NGINX+FPM en tant qu'utilisateur non-root
www-datasur :8080, des vérifications de santé/up,healthcheck-queue/healthcheck-schedule, etAUTORUN_ENABLEDqui exécutestorage:link, attend la DB,migrate --force, etphp artisan optimize(cela inclutfilament:optimizeet les hooks d'optimisation d'autres paquets). Seul le serviceappdéfinitAUTORUN_ENABLED=true, donc les migrations s'exécutent une fois ; le worker/scheduler attendent queappsoit sain. - Étape des assets sur
$BUILDPLATFORM— s'exécute nativement sur Mac tandis que les étapes PHP sont émulées pour amd64 ; la sortie est indépendante de l'architecture. - Installation de Composer avant la copie du source — la couche des dépendances reste en cache ; les reconstructions de code uniquement sont rapides même sous émulation.
- Un seul volume partagé
storage/apppour app + worker (+ scheduler) — les fichiers qu'un job écrit doivent être visibles par le conteneur web. - Logs sur stderr pour que le visualisateur de logs de la plateforme les affiche.
5. Vérifier localement avant de pousser quoi que ce soit
Faites-le pour de vrai — ne vous arrêtez pas à "le Dockerfile a l'air correct". Utilisez un nom de projet compose pour ne pas entrer en conflit avec les conteneurs de développement.
docker buildx build --load -t <name>:test . # architecture native, rapide
docker run --rm --entrypoint php <name>:test -m # extensions présentes ?
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, mots de passe
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 ignore la bannière/automatisations de serversideup pour que les commandes ponctuelles affichent une sortie propre.)
Vérifiez et rapportez chaque résultat :
- Tous les services
healthy; les logs deappmontrentstorage:link, migrations,optimizesans ❌. curl -s -o /dev/null -w '%{http_code}' localhost:8080/up→ 200 ; la page de connexion/accueil → 200 et ses URLs CSS/JS renvoient 200.- Proxy :
curl -s -H 'X-Forwarded-Proto: https' -H 'X-Forwarded-Host: x.example.com' localhost:8080/<page>→ les URLs des assets commencent parhttps://x.example.com. php artisan db:seed --force(si l'application a des seeders que l'utilisateur attend lors de la première installation).- File d'attente : dispatchez une vraie classe mise en file d'attente (une notification/job de l'application) sur chaque file nommée et confirmez que le worker logue
DONEet que l'effet secondaire a eu lieu. Les fermetures dispatchées depuistinker --executeéchouent dans le worker (le code évalué ne peut pas être désérialisé) — c'est un artefact de test, pas un bug. Respectez aussi leshouldSend/autorisation de l'application lorsque vous choisissez un destinataire de test. - Stockage : écrivez un fichier sur le disque
publicdepuis le worker, récupérez-le vialocalhost:8080/storage/...depuis l'app, puisdown+upet confirmez que les fichiers et les données DB persistent. - Cross-build pour le serveur :
docker buildx build --platform linux/amd64 -t <name>:amd64 --load .puisdocker image inspect <name>:amd64 --format '{{.Architecture}}'. Exécutez-le en arrière-plan — les constructions QEMU prennent des minutes.
Nettoyez avec docker compose -p <name>test down -v une fois terminé.
6. Écrire la documentation de déploiement
Créez docs/DOCKER_DEPLOYMENT.md en suivant references/docs-template.md, dans la langue qu'utilisent les docs existantes du projet, et liez-la depuis README.md. Les docs doivent expliquer ce qui a changé et pourquoi pour chaque fichier (l'utilisateur l'a demandé quand cette compétence a été créée, et les futurs mainteneurs en ont besoin), l'architecture, la configuration unique, la construction/push, les tests locaux, les étapes Coolify, la mise à jour/retour arrière, les opérations, la migration des données depuis l'ancien hôte, et les particularités du projet que vous avez trouvées à l'étape 1.
7. Passer le relais — confirmer avant toute action vers l'extérieur
Pousser vers GHCR publie l'image, et déployer modifie la production, alors arrêtez-vous et laissez l'utilisateur décider. Donnez-leur :
echo <PAT avec write:packages> | docker login ghcr.io -u <user> --password-stdin- Commitez, puis
scripts/docker-build-push.sh(refuse un arbre non commité ;--loadpour les builds locaux uniquement). - Étapes Coolify depuis
references/coolify.md— en particulier que le serveur a besoin d'une connexion GHCR en lecture seule pour un paquet privé, faite avecsudo docker login(Coolify tire en tant que root ; une connexion non-root lui est invisible), et que le domaine est saisi commehttps://domain:8080(:8080= port du conteneur). - Rappels : réutilisez l'ancienne
APP_KEY(et VAPID ou autres clés de longue durée) lors de la migration ; désactivez tout ancien workflow de déploiement SSH/FTP une fois le nouveau déploiement en ligne.
Proposez d'exécuter le push pour eux une fois qu'ils se sont connectés.
Confusions courantes des utilisateurs à anticiper
Les utilisateurs essaient souvent docker run <image> ou le bouton ▶ de Docker Desktop sur l'image seule. Cela démarre seulement le conteneur web : aucun service DB n'existe, l'exécution automatique est désactivée, et Laravel tombe sur sqlite (Database file at path [...] does not exist) ou échoue à résoudre mysql. La réponse est toujours la stack compose. Dites-le dans la section des tests locaux de la documentation.