laravel-coolify-docker

Conteneurisez une application Laravel pour la production et déployez-la avec Coolify : construisez l'image sur votre propre machine (y compris les cross-builds Apple Silicon → amd64), poussez-la sur GitHub Container Registry (ghcr.io) et exécutez-la en tant que stack Docker Compose (web + worker de file d'attente + planificateur + base de données). Produit un Dockerfile basé sur serversideup/php, docker-compose.prod.yml, un script de build-and-push, un correctif de proxy de confiance, une configuration de test local et une documentation de déploiement.

Qu'est-ce que laravel-coolify-docker ?

Cette compétence automatise la conteneurisation et le déploiement des applications Laravel (y compris Filament) sur Coolify, Dokploy, EasyPanel, CapRover ou un VPS Docker via GitHub Container Registry (ghcr.io). Elle fournit un workflow complet : inspection du projet, génération de Dockerfile multi-architecture (linux/amd64 et arm64), script de build et push, configuration Docker Compose (app, worker, scheduler, base de données), et documentation de déploiement. Le workflow inclut des vérifications de sécurité (proxy de confiance), de compatibilité NPM (réparation des binaires natifs manquants) et des tests locaux avant le déploiement. Utilisez-la pour conteneuriser un projet Laravel existant, résoudre les problèmes courants (SQLite de repli, jobs non traités, assets HTTP derrière un proxy), ou migrer depuis Forge/cPanel vers des conteneurs. Les décisions techniques sont documentées : image serversideup/php, volume partagé storage/app, logs sur stderr, et exécution des migrations via AUTORUN_ENABLED.

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

Installed? Explore more Développement et programmation skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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__) :

CheminUtilisation
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/DockerfileImage multi-étapes basée sur serversideup/php:<ver>-fpm-nginx.
assets/dockerignoreEnregistrer sous .dockerignore.
assets/docker-compose.prod.ymlapp + worker + (scheduler) + mysql, le fichier pointé par Coolify.
assets/docker-compose.prod.local.ymlSurcharge pour la station de travail : publie :8080, pas de cookies sécurisés.
assets/env.docker.exampleEnregistrer sous .env.docker.example ; modèle pour l'environnement local et Coolify.
assets/docker-build-push.shEnregistrer sous scripts/docker-build-push.sh ; construit amd64 et pousse latest + le SHA Git.
references/variants.mdPostgres/MariaDB, Redis, Horizon, Reverb, Octane, SSR, Wayfinder, pnpm/yarn/bun, Chromium, SQLite uniquement.
references/coolify.mdAuthentification GHCR sur le serveur, création de la ressource, domaine :8080, déploiement/mise à jour/retour arrière.
references/other-platforms.mdDokploy, EasyPanel, CapRover, Docker simple + Caddy, notes Kubernetes.
references/troubleshooting.mdTableau symptôme → cause → solution. À lire en cas d'échec.
references/docs-template.mdPlan 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 que composer.json dit ^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 dans install-php-extensions. gmp/bcmath apparaissent 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, voir references/variants.md.
  • queues — needs_worker et worker_queue_arg. Le --queue= du worker doit lister chaque file nommée (de onQueue, $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 service scheduler.
  • 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 que config_default est souvent sqlite : si DB_CONNECTION n'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 que npm ci échouera sous Linux. Exécutez repair_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 fichier docker-compose.yml existant (souvent Sail pour le développement) ; le fichier de production est docker-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-arch linux/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, passez DB_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 URLs http:// (contenu mixte, assets Livewire/Filament cassés, cookies non sécurisés, échec des notifications web). Laravel 11+ : dans bootstrap/app.php
    ->withMiddleware(function (Middleware $middleware): void {
        $middleware->trustProxies(at: '*');
    })
    
    Laravel ≤10 : définissez protected $proxies = '*'; dans app/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é :
    python3 <skill-dir>/scripts/repair_npm_lock.py <project-dir>
    
    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.
  • .env.example : ajoutez les clés que l'application lit mais que l'exemple ne contient pas (comparez les appels env( dans config/ 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 worker si rien n'est mis en file d'attente ; décommentez scheduler s'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-env comme ${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_TIMEZONE sur celle du config/app.php de 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-data sur :8080, des vérifications de santé /up, healthcheck-queue/healthcheck-schedule, et AUTORUN_ENABLED qui exécute storage:link, attend la DB, migrate --force, et php artisan optimize (cela inclut filament:optimize et les hooks d'optimisation d'autres paquets). Seul le service app définit AUTORUN_ENABLED=true, donc les migrations s'exécutent une fois ; le worker/scheduler attendent que app soit 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/app pour 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 :

  1. Tous les services healthy ; les logs de app montrent storage:link, migrations, optimize sans ❌.
  2. 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.
  3. Proxy : curl -s -H 'X-Forwarded-Proto: https' -H 'X-Forwarded-Host: x.example.com' localhost:8080/<page> → les URLs des assets commencent par https://x.example.com.
  4. php artisan db:seed --force (si l'application a des seeders que l'utilisateur attend lors de la première installation).
  5. 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 DONE et que l'effet secondaire a eu lieu. Les fermetures dispatchées depuis tinker --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 le shouldSend/autorisation de l'application lorsque vous choisissez un destinataire de test.
  6. Stockage : écrivez un fichier sur le disque public depuis le worker, récupérez-le via localhost:8080/storage/... depuis l'app, puis down + up et confirmez que les fichiers et les données DB persistent.
  7. Cross-build pour le serveur : docker buildx build --platform linux/amd64 -t <name>:amd64 --load . puis docker 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 :

  1. echo <PAT avec write:packages> | docker login ghcr.io -u <user> --password-stdin
  2. Commitez, puis scripts/docker-build-push.sh (refuse un arbre non commité ; --load pour les builds locaux uniquement).
  3. É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 avec sudo docker login (Coolify tire en tant que root ; une connexion non-root lui est invisible), et que le domaine est saisi comme https://domain:8080 (:8080 = port du conteneur).
  4. 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.

Skills associés