Laravel → Docker → GHCR → Coolify
The target setup: the image is built on the developer's machine, pushed to ghcr.io, and the server (Coolify) only pulls and runs it via a compose file. No building on the server, no secrets in the image, all config from environment variables.
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
Bundled files (copy and adapt; placeholders look like __IMAGE__):
| Path | Use |
|---|---|
scripts/inspect_laravel.py <dir> | Read-only project scan → JSON facts. Run this first. |
scripts/repair_npm_lock.py <dir> | Fixes a package-lock.json that lacks Linux native binaries (needs Docker). |
assets/Dockerfile | Multi-stage image on serversideup/php:<ver>-fpm-nginx. |
assets/dockerignore | Save as .dockerignore. |
assets/docker-compose.prod.yml | app + worker + (scheduler) + mysql, the file Coolify points at. |
assets/docker-compose.prod.local.yml | Workstation override: publishes :8080, no secure cookies. |
assets/env.docker.example | Save as .env.docker.example; template for local and Coolify env. |
assets/docker-build-push.sh | Save as scripts/docker-build-push.sh; builds amd64 and pushes latest + git SHA. |
references/variants.md | Postgres/MariaDB, Redis, Horizon, Reverb, Octane, SSR, Wayfinder, pnpm/yarn/bun, Chromium, SQLite-only. |
references/coolify.md | GHCR auth on the server, creating the resource, domain :8080, deploy/update/rollback. |
references/other-platforms.md | Dokploy, EasyPanel, CapRover, plain Docker + Caddy, Kubernetes notes. |
references/troubleshooting.md | Symptom → cause → fix table. Read when something fails. |
references/docs-template.md | Outline for the docs/DOCKER_DEPLOYMENT.md you write for the project. |
If the user only has a question or a failure (not a full setup), go straight to references/troubleshooting.md or the relevant reference instead of running the whole workflow.
Workflow
1. Inspect the project
python3 <skill-dir>/scripts/inspect_laravel.py <project-dir>
It reports the facts that decide the image and stack. Read it closely — each field maps to a decision:
php.allowed— PHP minors every locked package accepts. Pick the highest allowed for the base image tag. If it's empty, the lock is unsatisfiable on any single version; tell the user which packages block (php.blocked_by). Don't pick a version just becausecomposer.jsonsays^8.2: transitive packages (e.g. openspout~8.2||~8.3||~8.4, Symfony 8>=8.4.1) narrow it, and the build fails late if you guess wrong.extensions.install_on_serversideup— exactly what goes intoinstall-php-extensions.gmp/bcmathappear together for web push; installing both is fine.extensions.system_binaries— packages that need OS binaries (Chromium, wkhtmltopdf, ffmpeg). Check whether the code actually uses them before bloating the image (grep for the class); if used, seereferences/variants.md.queues—needs_workerandworker_queue_arg. The worker's--queue=must list every named queue (fromonQueue,$queue,viaQueues()), or those jobs sit in the table forever while the default-queue worker looks healthy.scheduler.has_scheduled_tasks→ add theschedulerservice.packages.key_packages→ Horizon replaces the worker; Reverb adds a websocket service; Octane changes the base image (see variants).database— the driver for the compose DB service. Noteconfig_defaultis oftensqlite: ifDB_CONNECTIONisn't set in the container, Laravel silently uses SQLite. The compose file sets it explicitly for that reason.frontend.npm_lock_missing_linux_binaries— non-empty meansnpm ciwill fail in Linux. Runrepair_npm_lock.py(step 3).frontend.vite_needs_php_at_build— Wayfinder etc. need PHP during the Vite build; see variants.proxy.bootstrap_trustProxies/legacy_TrustProxies_middleware— whether step 3's proxy fix is needed.git.ghcr_image— image name (GHCR requires lowercase).existing_files— don't clobber an existingdocker-compose.yml(often Sail for dev); the production file isdocker-compose.prod.yml.
Also skim the code for things the scan can't judge: providers that hit the DB at boot (breaks composer dump-autoload / optimize during build), code that file_get_contents(asset(...)) its own URL, hard-coded storage_path assumptions.
2. Confirm the few things only the user knows
Ask briefly (one round), defaulting sensibly if they don't care:
- Server CPU architecture — usually
linux/amd64(most VPS). ARM servers (Hetzner CAX, Oracle Ampere, Graviton) →linux/arm64. Unknown → multi-archlinux/amd64,linux/arm64(slower build). This matters because an arm64 image built on a Mac will not start on an amd64 server (exec format error). - Database: run it in the compose stack (simplest, recommended) or use an existing/managed DB (drop the
mysqlservice, passDB_HOST). - Anything that should stay untouched (old deploy workflows, Sail compose file).
3. Make the code container-ready
- Trust the proxy. Coolify's Traefik terminates TLS and forwards HTTP. Without trusting
X-Forwarded-*, Laravel generateshttp://URLs (mixed content, broken Livewire/Filament assets, insecure cookies, web push fails). Laravel 11+: inbootstrap/app.phpLaravel ≤10: set->withMiddleware(function (Middleware $middleware): void { $middleware->trustProxies(at: '*'); })protected $proxies = '*';inapp/Http/Middleware/TrustProxies.php.'*'is safe only because port 8080 is never published to the internet — say so in the docs. - Repair the npm lockfile if the scan flagged it:
It only re-resolves native-binary packages (rollup, esbuild, lightningcss, Tailwind oxide, swc, sass-embedded); report the version bumps it prints to the user.python3 <skill-dir>/scripts/repair_npm_lock.py <project-dir> .env.example: add keys the app reads but the example lacks (compareenv(calls inconfig/with the file) so the deploy docs are complete..gitignore: add.env.docker.
4. Generate the Docker files
Copy from assets/ into the project and fill placeholders: __IMAGE__, __REPO_URL__ (https GitHub URL, links the GHCR package to the repo), __APP_NAME__, __PHP_VERSION__, __PHP_EXTENSIONS__, __QUEUES__. Then adapt:
- Remove the
workerservice if nothing is queued; uncommentschedulerif there are scheduled tasks. - Swap DB service / env for Postgres, MariaDB or Redis per
references/variants.md. - Add app-specific env keys (API keys, VAPID, S3) to the
x-app-envanchor as${VAR:-}; mark truly required ones${VAR:?msg}so a missing value fails loudly instead of booting half-configured. - Set
APP_TIMEZONEdefault to the app'sconfig/app.phpdefault. - Package manager ≠ npm, no
package.json, SSR, Chromium →references/variants.md.
Design decisions baked into the templates (keep them unless there's a reason):
- serversideup/php gives NGINX+FPM as non-root
www-dataon :8080,/uphealth checks,healthcheck-queue/healthcheck-schedule, andAUTORUN_ENABLEDwhich runsstorage:link, waits for the DB,migrate --force, andphp artisan optimize(this includesfilament:optimizeand other packages' optimize hooks). Only theappservice setsAUTORUN_ENABLED=true, so migrations run once; worker/scheduler wait forappto be healthy. - Assets stage on
$BUILDPLATFORM— runs natively on the Mac while PHP stages are emulated for amd64; output is architecture-independent. - Composer install before copying source — dependency layer stays cached; code-only rebuilds are fast even under emulation.
- One shared
storage/appvolume for app + worker (+ scheduler) — files a job writes must be visible to the web container. - Logs to stderr so the platform's log viewer shows them.
5. Verify locally before anything is pushed
Do this for real — don't stop at "the Dockerfile looks right". Use a compose project name so it doesn't collide with dev containers.
docker buildx build --load -t <name>:test . # native arch, fast
docker run --rm --entrypoint php <name>:test -m # extensions present?
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, passwords
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 skips serversideup's banner/automations so one-off commands print clean output.)
Check, and report each result:
- All services
healthy;applogs showstorage:link, migrations,optimizewith no ❌. curl -s -o /dev/null -w '%{http_code}' localhost:8080/up→ 200; the login/home page → 200 and its CSS/JS URLs return 200.- Proxy:
curl -s -H 'X-Forwarded-Proto: https' -H 'X-Forwarded-Host: x.example.com' localhost:8080/<page>→ asset URLs start withhttps://x.example.com. php artisan db:seed --force(if the app has seeders the user expects on first install).- Queue: dispatch a real queued class (a notification/job from the app) onto each named queue and confirm the worker logs
DONEand the side effect happened. Closures dispatched fromtinker --executefail in the worker (eval'd code can't be unserialized) — that's a test artifact, not a bug. Also respect the app's ownshouldSend/authorization when picking a test recipient. - Storage: write a file on the
publicdisk from the worker, fetch it vialocalhost:8080/storage/...from app, thendown+upand confirm files and DB rows persist. - Cross-build for the server:
docker buildx build --platform linux/amd64 -t <name>:amd64 --load .thendocker image inspect <name>:amd64 --format '{{.Architecture}}'. Run it in the background — QEMU builds take minutes.
Tear down with docker compose -p <name>test down -v when done.
6. Write the deployment docs
Create docs/DOCKER_DEPLOYMENT.md following references/docs-template.md, in the language the project's existing docs use, and link it from README.md. The docs must explain what changed and why for each file (the user asked for that when this skill was created, and future maintainers need it), the architecture, one-time setup, build/push, local testing, Coolify steps, updating/rollback, operations, migrating data from the old host, and project-specific caveats you found in step 1.
7. Hand off — confirm before anything outward-facing
Pushing to GHCR publishes the image, and deploying changes production, so stop and let the user decide. Give them:
echo <PAT with write:packages> | docker login ghcr.io -u <user> --password-stdin- Commit, then
scripts/docker-build-push.sh(refuses a dirty tree;--loadfor local-only builds). - Coolify steps from
references/coolify.md— especially that the server needs a read-only GHCR login for a private package, done withsudo docker login(Coolify pulls as root; a non-root login is invisible to it), and the domain is entered ashttps://domain:8080(:8080= container port). - Reminders: reuse the old
APP_KEY(and VAPID or other long-lived keys) when migrating; disable any old SSH/FTP deploy workflow once the new deploy is live.
Offer to run the push for them once they've logged in.
Common user confusion to pre-empt
Users often try docker run <image> or Docker Desktop's ▶ button on the image alone. That starts only the web container: no DB service exists, autorun is off, and Laravel falls back to sqlite (Database file at path [...] does not exist) or fails resolving mysql. The answer is always the compose stack. Say this in the docs' local-testing section.