CommunityProgramación y desarrollogithub.com

laravel-coolify-docker

Contenedoriza una aplicación Laravel para producción y despliégala con Coolify: construye la imagen en tu máquina (incluyendo compilaciones cruzadas Apple Silicon → amd64), súbela a ghcr.io y ejecútala como un stack de Docker Compose (web + worker de cola + scheduler + base de datos).

¿Qué es laravel-coolify-docker?

Este skill automatiza el proceso completo de contenedorización de proyectos Laravel o Filament para su despliegue en producción con Coolify (también compatible con Dokploy, EasyPanel, CapRover o un VPS con Docker). Escanea el proyecto para detectar la versión de PHP, extensiones, sistema de colas, scheduler, base de datos y dependencias frontend. Genera un Dockerfile optimizado basado en serversideup/php, un docker-compose.prod.yml con servicios de web, worker, scheduler y base de datos, un script de build y push a ghcr.io, y corrige problemas comunes como la confianza de proxy, el lockfile de npm que falla en Linux, o la configuración por defecto SQLite. Incluye verificación local completa y documentación de despliegue. Soporta variantes como Postgres, Redis, Horizon, Octane, Reverb, SSR, pnpm/yarn/bun y Chromium.

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

Installed? Explore more Programación y desarrollo skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Laravel → Docker → GHCR → Coolify

La configuración objetivo: la imagen se construye en la máquina del desarrollador, se sube a ghcr.io y el servidor (Coolify) solo la descarga y ejecuta mediante un archivo compose. Sin construir en el servidor, sin secretos en la imagen, toda la configuración desde variables de entorno.

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

Archivos incluidos (copia y adapta; los placeholders tienen el formato __IMAGE__):

RutaUso
scripts/inspect_laravel.py <dir>Escaneo de solo lectura del proyecto → hechos en JSON. Ejecútalo primero.
scripts/repair_npm_lock.py <dir>Corrige un package-lock.json que carece de binarios nativos de Linux (necesita Docker).
assets/DockerfileImagen multi-etapa basada en serversideup/php:<ver>-fpm-nginx.
assets/dockerignoreGuárdalo como .dockerignore.
assets/docker-compose.prod.ymlapp + worker + (scheduler) + mysql, el archivo al que apunta Coolify.
assets/docker-compose.prod.local.ymlSobreescritura para la estación de trabajo: publica :8080, sin cookies seguras.
assets/env.docker.exampleGuárdalo como .env.docker.example; plantilla para el entorno local y de Coolify.
assets/docker-build-push.shGuárdalo como scripts/docker-build-push.sh; construye amd64 y sube latest + el SHA de git.
references/variants.mdPostgres/MariaDB, Redis, Horizon, Reverb, Octane, SSR, Wayfinder, pnpm/yarn/bun, Chromium, solo SQLite.
references/coolify.mdAutenticación GHCR en el servidor, creación del recurso, dominio :8080, despliegue/actualización/rollback.
references/other-platforms.mdDokploy, EasyPanel, CapRover, Docker simple + Caddy, notas sobre Kubernetes.
references/troubleshooting.mdTabla de síntoma → causa → solución. Léela cuando algo falle.
references/docs-template.mdEsquema para el docs/DOCKER_DEPLOYMENT.md que escribirás para el proyecto.

Si el usuario solo tiene una pregunta o un fallo (no una configuración completa), ve directamente a references/troubleshooting.md o a la referencia correspondiente en lugar de ejecutar todo el flujo.

Flujo de trabajo

1. Inspeccionar el proyecto

python3 <skill-dir>/scripts/inspect_laravel.py <project-dir>

Informa de los hechos que determinan la imagen y el stack. Léelo con atención: cada campo se asigna a una decisión:

  • php.allowed: versiones menores de PHP que acepta cada paquete bloqueado. Elige la más alta permitida para la etiqueta de la imagen base. Si está vacío, el bloqueo no es satisfacible en ninguna versión única; dile al usuario qué paquetes lo bloquean (php.blocked_by). No elijas una versión solo porque composer.json diga ^8.2: los paquetes transitivos (p. ej., openspout ~8.2||~8.3||~8.4, Symfony 8 >=8.4.1) lo restringen, y la construcción falla tarde si aciertas mal.
  • extensions.install_on_serversideup: exactamente lo que va en install-php-extensions. gmp/bcmath aparecen juntos para web push; instalar ambos está bien.
  • extensions.system_binaries: paquetes que necesitan binarios del sistema (Chromium, wkhtmltopdf, ffmpeg). Verifica si el código realmente los usa antes de inflar la imagen (busca la clase con grep); si se usan, consulta references/variants.md.
  • queues: needs_worker y worker_queue_arg. El --queue= del worker debe listar cada cola nombrada (de onQueue, $queue, viaQueues()), o esos trabajos se quedan en la tabla para siempre mientras el worker de la cola por defecto parece saludable.
  • scheduler.has_scheduled_tasks → añade el servicio scheduler.
  • packages.key_packages: Horizon reemplaza al worker; Reverb añade un servicio websocket; Octane cambia la imagen base (consulta variantes).
  • database: el driver para el servicio de base de datos del compose. Nota que config_default suele ser sqlite: si DB_CONNECTION no se establece en el contenedor, Laravel usa SQLite silenciosamente. El archivo compose lo establece explícitamente por esa razón.
  • frontend.npm_lock_missing_linux_binaries: si no está vacío, npm ci fallará en Linux. Ejecuta repair_npm_lock.py (paso 3).
  • frontend.vite_needs_php_at_build: Wayfinder, etc. necesitan PHP durante la compilación de Vite; consulta variantes.
  • proxy.bootstrap_trustProxies / legacy_TrustProxies_middleware: indica si se necesita la corrección de proxy del paso 3.
  • git.ghcr_image: nombre de la imagen (GHCR requiere minúsculas).
  • existing_files: no sobrescribas un docker-compose.yml existente (a menudo Sail para desarrollo); el archivo de producción es docker-compose.prod.yml.

También revisa el código en busca de cosas que el escaneo no puede juzgar: proveedores que acceden a la base de datos al arrancar (rompe composer dump-autoload / optimize durante la construcción), código que hace file_get_contents(asset(...)) a su propia URL, suposiciones hardcodeadas de storage_path.

2. Confirmar las pocas cosas que solo el usuario sabe

Pregunta brevemente (una ronda), con valores predeterminados sensatos si no les importa:

  • Arquitectura de CPU del servidor: normalmente linux/amd64 (la mayoría de VPS). Servidores ARM (Hetzner CAX, Oracle Ampere, Graviton) → linux/arm64. Desconocida → multi-arquitectura linux/amd64,linux/arm64 (construcción más lenta). Esto importa porque una imagen arm64 construida en un Mac no arrancará en un servidor amd64 (exec format error).
  • Base de datos: ejecutarla en el stack compose (lo más simple, recomendado) o usar una existente/gestionada (elimina el servicio mysql, pasa DB_HOST).
  • Cualquier cosa que deba permanecer intacta (flujos de despliegue antiguos, archivo compose de Sail).

3. Preparar el código para contenedores

  • Confiar en el proxy. El Traefik de Coolify termina TLS y reenvía HTTP. Sin confiar en X-Forwarded-*, Laravel genera URLs http:// (contenido mixto, activos Livewire/Filament rotos, cookies inseguras, fallo en web push). Laravel 11+: en bootstrap/app.php
    ->withMiddleware(function (Middleware $middleware): void {
        $middleware->trustProxies(at: '*');
    })
    
    Laravel ≤10: establece protected $proxies = '*'; en app/Http/Middleware/TrustProxies.php. '*' es seguro solo porque el puerto 8080 nunca se publica en internet — indícalo en la documentación.
  • Reparar el lockfile de npm si el escaneo lo marcó:
    python3 <skill-dir>/scripts/repair_npm_lock.py <project-dir>
    
    Solo resuelve de nuevo los paquetes con binarios nativos (rollup, esbuild, lightningcss, Tailwind oxide, swc, sass-embedded); informa de los saltos de versión que imprime al usuario.
  • .env.example: añade las claves que la aplicación lee pero que faltan en el ejemplo (compara las llamadas env( en config/ con el archivo) para que la documentación de despliegue esté completa.
  • .gitignore: añade .env.docker.

4. Generar los archivos Docker

Copia desde assets/ al proyecto y rellena los placeholders: __IMAGE__, __REPO_URL__ (URL de GitHub HTTPS, enlaza el paquete GHCR al repositorio), __APP_NAME__, __PHP_VERSION__, __PHP_EXTENSIONS__, __QUEUES__. Luego adapta:

  • Elimina el servicio worker si no hay colas; descomenta scheduler si hay tareas programadas.
  • Cambia el servicio DB y las variables de entorno para Postgres, MariaDB o Redis según references/variants.md.
  • Añade claves de entorno específicas de la aplicación (API keys, VAPID, S3) al ancla x-app-env como ${VAR:-}; marca las realmente obligatorias como ${VAR:?msg} para que un valor faltante falle de forma ruidosa en lugar de arrancar medio configurado.
  • Establece APP_TIMEZONE por defecto al valor por defecto de config/app.php de la aplicación.
  • Gestor de paquetes ≠ npm, sin package.json, SSR, Chromium → references/variants.md.

Decisiones de diseño integradas en las plantillas (mantenlas a menos que haya una razón para cambiarlas):

  • serversideup/php proporciona NGINX+FPM como no-root www-data en :8080, health checks /up, healthcheck-queue/healthcheck-schedule, y AUTORUN_ENABLED que ejecuta storage:link, espera a la base de datos, migrate --force y php artisan optimize (esto incluye filament:optimize y otros hooks de optimización de paquetes). Solo el servicio app establece AUTORUN_ENABLED=true, por lo que las migraciones se ejecutan una vez; worker/scheduler esperan a que app esté saludable.
  • Etapa de assets en $BUILDPLATFORM: se ejecuta de forma nativa en el Mac mientras que las etapas PHP se emulan para amd64; la salida es independiente de la arquitectura.
  • Composer install antes de copiar el código fuente: la capa de dependencias se mantiene en caché; las reconstrucciones solo de código son rápidas incluso bajo emulación.
  • Un volumen storage/app compartido para app + worker (+ scheduler): los archivos que un trabajo escribe deben ser visibles para el contenedor web.
  • Logs a stderr para que el visor de logs de la plataforma los muestre.

5. Verificar localmente antes de subir nada

Haz esto de verdad — no te detengas en "el Dockerfile tiene buena pinta". Usa un nombre de proyecto de compose para que no colisione con contenedores de desarrollo.

docker buildx build --load -t <nombre>:test .                       # arquitectura nativa, rápido
docker run --rm --entrypoint php <nombre>:test -m                  # ¿extensiones presentes?
docker run --rm --entrypoint php <nombre>:test artisan key:generate --show
cp .env.docker.example .env.docker   # APP_IMAGE=<nombre>, IMAGE_TAG=test, PULL_POLICY=never, key, contraseñas
docker compose -p <nombre>test --env-file .env.docker -f docker-compose.prod.yml -f docker-compose.prod.local.yml up -d --wait

(--entrypoint php omite el banner/automatizaciones de serversideup para que los comandos únicos impriman una salida limpia.)

Comprueba e informa de cada resultado:

  1. Todos los servicios healthy; los logs de app muestran storage:link, migraciones, optimize sin ❌.
  2. curl -s -o /dev/null -w '%{http_code}' localhost:8080/up → 200; la página de inicio/login → 200 y sus URLs de CSS/JS devuelven 200.
  3. Proxy: curl -s -H 'X-Forwarded-Proto: https' -H 'X-Forwarded-Host: x.example.com' localhost:8080/<pagina> → las URLs de los assets comienzan con https://x.example.com.
  4. php artisan db:seed --force (si la aplicación tiene seeders que el usuario espera en la primera instalación).
  5. Cola: despacha una clase de cola real (una notificación/trabajo de la aplicación) en cada cola nombrada y confirma que el worker registra DONE y que el efecto secundario ocurrió. Los closures despachados desde tinker --execute fallan en el worker (el código evaluado no puede deserializarse) — eso es un artefacto de prueba, no un error. Respeta también la autorización/shouldSend de la aplicación al elegir un destinatario de prueba.
  6. Almacenamiento: escribe un archivo en el disco public desde el worker, recupéralo vía localhost:8080/storage/... desde la app, luego haz down + up y confirma que los archivos y los registros de la base de datos persisten.
  7. Compilación cruzada para el servidor: docker buildx build --platform linux/amd64 -t <nombre>:amd64 --load . luego docker image inspect <nombre>:amd64 --format '{{.Architecture}}'. Ejecútalo en segundo plano — las compilaciones con QEMU toman minutos.

Destruye con docker compose -p <nombre>test down -v cuando termines.

6. Escribir la documentación de despliegue

Crea docs/DOCKER_DEPLOYMENT.md siguiendo references/docs-template.md, en el idioma que usan los documentos existentes del proyecto, y enlázalo desde README.md. La documentación debe explicar qué cambió y por qué para cada archivo (el usuario lo pidió cuando se creó este skill, y los futuros mantenedores lo necesitan), la arquitectura, la configuración única, construcción/subida, pruebas locales, pasos en Coolify, actualización/rollback, operaciones, migración de datos desde el host antiguo, y advertencias específicas del proyecto que encontraste en el paso 1.

7. Entregar — confirmar antes de cualquier acción externa

Subir a GHCR publica la imagen, y desplegar cambia producción, así que detente y deja que el usuario decida. Entrégales:

  1. echo <PAT con write:packages> | docker login ghcr.io -u <usuario> --password-stdin
  2. Commit, luego scripts/docker-build-push.sh (rechaza un árbol sucio; --load para compilaciones solo locales).
  3. Pasos de Coolify desde references/coolify.md — especialmente que el servidor necesita un inicio de sesión de solo lectura en GHCR para un paquete privado, hecho con sudo docker login (Coolify extrae como root; un inicio de sesión no root es invisible para él), y el dominio se ingresa como https://dominio:8080 (:8080 = puerto del contenedor).
  4. Recordatorios: reutiliza la antigua APP_KEY (y VAPID u otras claves de larga duración) al migrar; deshabilita cualquier flujo de despliegue SSH/FTP antiguo una vez que el nuevo despliegue esté activo.

Ofrécete a ejecutar la subida por ellos una vez que hayan iniciado sesión.

Confusión común del usuario que anticipar

Los usuarios a menudo intentan docker run <imagen> o el botón ▶ de Docker Desktop sobre la imagen sola. Eso inicia solo el contenedor web: no existe el servicio de base de datos, la ejecución automática está desactivada y Laravel recurre a sqlite ("Database file at path [...] does not exist") o falla al resolver mysql. La respuesta es siempre el stack compose. Dilo en la sección de pruebas locales de la documentación.

Skills relacionados