CommunityCoding & Developmentgithub.com

laravel-coolify-docker

Containerize a Laravel app for production and deploy it with Coolify — build the image on your own machine (including Apple Silicon → amd64 cross-builds), push it to GitHub Container Registry (ghcr.io), and run it as a Docker Compose stack (web + queue worker + scheduler + database). Produces a Dockerfile on serversideup/php, docker-compose.prod.yml, a build-and-push script, trusted-proxy fix, local test setup, and deployment docs. Use this whenever someone wants to dockerize / containerize a Laravel or Filament project, deploy Laravel to Coolify (or Dokploy, EasyPanel, CapRover, a plain VPS with Docker), push a Laravel image to ghcr.io, move off cPanel/shared hosting/Forge to containers, or troubleshoot a Laravel container that falls back to SQLite, can't reach MySQL, never processes queued jobs, serves http:// assets behind a proxy, or fails `npm ci` with missing @rollup/rollup-linux binaries.

What is laravel-coolify-docker?

laravel-coolify-docker is a Claude Code agent skill that containerize a Laravel app for production and deploy it with Coolify — build the image on your own machine (including Apple Silicon → amd64 cross-builds), push it to GitHub Container Registry (ghcr.io), and run it as a Docker Compose stack (web + queue worker + scheduler + database). Produces a Dockerfile on serversideup/php, docker-compose.prod.yml, a build-and-push script, trusted-proxy fix, local test setup, and deployment docs. Use this whenever someone wants to dockerize / containerize a Laravel or Filament project, deploy Laravel to Coolify (or Dokploy, EasyPanel, CapRover, a plain VPS with Docker), push a Laravel image to ghcr.io, move off cPanel/shared hosting/Forge to containers, or troubleshoot a Laravel container that falls back to SQLite, can't reach MySQL, never processes queued jobs, serves http:// assets behind a proxy, or fails `npm ci` with missing @rollup/rollup-linux binaries.

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

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

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

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

PathUse
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/DockerfileMulti-stage image on serversideup/php:<ver>-fpm-nginx.
assets/dockerignoreSave as .dockerignore.
assets/docker-compose.prod.ymlapp + worker + (scheduler) + mysql, the file Coolify points at.
assets/docker-compose.prod.local.ymlWorkstation override: publishes :8080, no secure cookies.
assets/env.docker.exampleSave as .env.docker.example; template for local and Coolify env.
assets/docker-build-push.shSave as scripts/docker-build-push.sh; builds amd64 and pushes latest + git SHA.
references/variants.mdPostgres/MariaDB, Redis, Horizon, Reverb, Octane, SSR, Wayfinder, pnpm/yarn/bun, Chromium, SQLite-only.
references/coolify.mdGHCR auth on the server, creating the resource, domain :8080, deploy/update/rollback.
references/other-platforms.mdDokploy, EasyPanel, CapRover, plain Docker + Caddy, Kubernetes notes.
references/troubleshooting.mdSymptom → cause → fix table. Read when something fails.
references/docs-template.mdOutline 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 because composer.json says ^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 into install-php-extensions. gmp/bcmath appear 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, see references/variants.md.
  • queues — needs_worker and worker_queue_arg. The worker's --queue= must list every named queue (from onQueue, $queue, viaQueues()), or those jobs sit in the table forever while the default-queue worker looks healthy.
  • scheduler.has_scheduled_tasks → add the scheduler service.
  • 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. Note config_default is often sqlite: if DB_CONNECTION isn'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 means npm ci will fail in Linux. Run repair_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 existing docker-compose.yml (often Sail for dev); the production file is docker-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-arch linux/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 mysql service, pass DB_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 generates http:// URLs (mixed content, broken Livewire/Filament assets, insecure cookies, web push fails). Laravel 11+: in bootstrap/app.php
    ->withMiddleware(function (Middleware $middleware): void {
        $middleware->trustProxies(at: '*');
    })
    
    Laravel ≤10: set protected $proxies = '*'; in app/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:
    python3 <skill-dir>/scripts/repair_npm_lock.py <project-dir>
    
    It only re-resolves native-binary packages (rollup, esbuild, lightningcss, Tailwind oxide, swc, sass-embedded); report the version bumps it prints to the user.
  • .env.example: add keys the app reads but the example lacks (compare env( calls in config/ 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 worker service if nothing is queued; uncomment scheduler if 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-env anchor as ${VAR:-}; mark truly required ones ${VAR:?msg} so a missing value fails loudly instead of booting half-configured.
  • Set APP_TIMEZONE default to the app's config/app.php default.
  • 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-data on :8080, /up health checks, healthcheck-queue/healthcheck-schedule, and AUTORUN_ENABLED which runs storage:link, waits for the DB, migrate --force, and php artisan optimize (this includes filament:optimize and other packages' optimize hooks). Only the app service sets AUTORUN_ENABLED=true, so migrations run once; worker/scheduler wait for app to 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/app volume 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:

  1. All services healthy; app logs show storage:link, migrations, optimize with no ❌.
  2. curl -s -o /dev/null -w '%{http_code}' localhost:8080/up → 200; the login/home page → 200 and its CSS/JS URLs return 200.
  3. Proxy: curl -s -H 'X-Forwarded-Proto: https' -H 'X-Forwarded-Host: x.example.com' localhost:8080/<page> → asset URLs start with https://x.example.com.
  4. php artisan db:seed --force (if the app has seeders the user expects on first install).
  5. Queue: dispatch a real queued class (a notification/job from the app) onto each named queue and confirm the worker logs DONE and the side effect happened. Closures dispatched from tinker --execute fail in the worker (eval'd code can't be unserialized) — that's a test artifact, not a bug. Also respect the app's own shouldSend/authorization when picking a test recipient.
  6. Storage: write a file on the public disk from the worker, fetch it via localhost:8080/storage/... from app, then down + up and confirm files and DB rows persist.
  7. Cross-build for the server: docker buildx build --platform linux/amd64 -t <name>:amd64 --load . then docker 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:

  1. echo <PAT with write:packages> | docker login ghcr.io -u <user> --password-stdin
  2. Commit, then scripts/docker-build-push.sh (refuses a dirty tree; --load for local-only builds).
  3. Coolify steps from references/coolify.md — especially that the server needs a read-only GHCR login for a private package, done with sudo docker login (Coolify pulls as root; a non-root login is invisible to it), and the domain is entered as https://domain:8080 (:8080 = container port).
  4. 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.

Related Skills