laravel-coolify-docker

Containerize uma aplicação Laravel para produção e implante com Coolify — construa a imagem na sua própria máquina (incluindo cross-build Apple Silicon → amd64), envie para GitHub Container Registry (ghcr.io) e execute como stack Docker Compose (web + worker de fila + agendador + banco de dados).

O que é laravel-coolify-docker?

Esta skill automatiza a conteinerização e implantação de projetos Laravel (ou Filament) em produção usando Docker, Coolify e GitHub Container Registry (ghcr.io). Ela gera um Dockerfile baseado na imagem serversideup/php (NGINX + FPM, non-root, health checks, AUTORUN para migrations/otimizações), um docker-compose.prod.yml com serviços de app, worker de fila, agendador opcional e banco de dados (MySQL por padrão, com suporte a Postgres, MariaDB, Redis), e um script de build e push. A skill também lida com cross-build para linux/amd64 a partir de máquinas Apple Silicon, corrige o lockfile npm para binários nativos Linux, configura confiança de proxy (TrustProxies) para evitar URLs http:// atrás de proxies, e produz documentação de implantação detalhada. É compatível com Coolify, Dokploy, EasyPanel, CapRover, VPS simples com Docker e Kubernetes. Útil para diagnosticar problemas comuns: fallback para SQLite, falha ao conectar MySQL, jobs de fila não processados, assets quebrados atrás de proxy ou erro de build npm por falta de binários Linux.

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

Installed? Explore more Programação e Desenvolvimento skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Laravel → Docker → GHCR → Coolify

A configuração alvo: a imagem é construída na máquina do desenvolvedor, enviada para ghcr.io, e o servidor (Coolify) apenas puxa e executa via um arquivo compose. Sem construção no servidor, sem segredos na imagem, toda configuração via variáveis de ambiente.

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

Arquivos inclusos (copie e adapte; placeholders têm formato __IMAGE__):

CaminhoUso
scripts/inspect_laravel.py <dir>Varredura somente leitura do projeto → fatos JSON. Execute primeiro.
scripts/repair_npm_lock.py <dir>Corrige um package-lock.json sem binários nativos Linux (precisa Docker).
assets/DockerfileImagem multi-estágio baseada em serversideup/php:<ver>-fpm-nginx.
assets/dockerignoreSalve como .dockerignore.
assets/docker-compose.prod.ymlapp + worker + (scheduler) + mysql, arquivo que o Coolify aponta.
assets/docker-compose.prod.local.ymlOverride para workstation: expõe :8080, sem cookies seguros.
assets/env.docker.exampleSalve como .env.docker.example; modelo para env local e Coolify.
assets/docker-build-push.shSalve como scripts/docker-build-push.sh; compila amd64 e envia latest + SHA do git.
references/variants.mdPostgres/MariaDB, Redis, Horizon, Reverb, Octane, SSR, Wayfinder, pnpm/yarn/bun, Chromium, apenas SQLite.
references/coolify.mdAutenticação GHCR no servidor, criação do recurso, domínio :8080, deploy/update/rollback.
references/other-platforms.mdDokploy, EasyPanel, CapRover, Docker simples + Caddy, notas sobre Kubernetes.
references/troubleshooting.mdTabela sintoma → causa → solução. Leia quando algo falhar.
references/docs-template.mdEsboço para o docs/DOCKER_DEPLOYMENT.md que você escreverá para o projeto.

Se o usuário tiver apenas uma dúvida ou falha (não uma configuração completa), vá direto para references/troubleshooting.md ou a referência relevante em vez de executar todo o fluxo.

Fluxo de Trabalho

1. Inspecione o projeto

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

Ele reporta os fatos que decidem a imagem e a stack. Leia atentamente — cada campo mapeia uma decisão:

  • php.allowed — PHP minors que cada pacote travado aceita. Escolha o mais alto permitido para a tag da imagem base. Se estiver vazio, o lock é insatisfatório em qualquer versão única; informe ao usuário quais pacotes bloqueiam (php.blocked_by). Não escolha uma versão só porque composer.json diz ^8.2: pacotes transitivos (ex.: openspout ~8.2||~8.3||~8.4, Symfony 8 >=8.4.1) restringem, e o build falha tarde se você chutar errado.
  • extensions.install_on_serversideup — exatamente o que vai em install-php-extensions. gmp/bcmath aparecem juntos para web push; instalar ambos é ok.
  • extensions.system_binaries — pacotes que precisam de binários do SO (Chromium, wkhtmltopdf, ffmpeg). Verifique se o código realmente os usa antes de inchar a imagem (grep pela classe); se usado, veja references/variants.md.
  • queues — needs_worker e worker_queue_arg. O --queue= do worker deve listar todas as filas nomeadas (de onQueue, $queue, viaQueues()), ou esses jobs ficam na tabela para sempre enquanto o worker da fila padrão parece saudável.
  • scheduler.has_scheduled_tasks → adicione o serviço scheduler.
  • packages.key_packages → Horizon substitui o worker; Reverb adiciona um serviço websocket; Octane muda a imagem base (veja variantes).
  • database — o driver para o serviço compose do banco. Note que config_default é muitas vezes sqlite: se DB_CONNECTION não for definido no container, Laravel usa SQLite silenciosamente. O arquivo compose define explicitamente por isso.
  • frontend.npm_lock_missing_linux_binaries — não vazio significa que npm ci falhará no Linux. Execute repair_npm_lock.py (passo 3).
  • frontend.vite_needs_php_at_build — Wayfinder etc. precisam de PHP durante o build Vite; veja variantes.
  • proxy.bootstrap_trustProxies / legacy_TrustProxies_middleware — se a correção de proxy do passo 3 é necessária.
  • git.ghcr_image — nome da imagem (GHCR requer minúsculas).
  • existing_files — não sobrescreva um docker-compose.yml existente (muitas vezes Sail para dev); o arquivo de produção é docker-compose.prod.yml.

Também examine o código para coisas que a varredura não pode julgar: providers que acessam o banco na inicialização (quebra composer dump-autoload / optimize durante o build), código que faz file_get_contents(asset(...)) da própria URL, suposições de storage_path hard-coded.

2. Confirme as poucas coisas que só o usuário sabe

Pergunte brevemente (uma rodada), com defaults sensatos se não se importarem:

  • Arquitetura da CPU do servidor — geralmente linux/amd64 (maioria dos VPS). Servidores ARM (Hetzner CAX, Oracle Ampere, Graviton) → linux/arm64. Desconhecida → multi-arquitetura linux/amd64,linux/arm64 (build mais lento). Isso importa porque uma imagem arm64 construída num Mac não iniciará num servidor amd64 (exec format error).
  • Banco de dados: execute na stack compose (mais simples, recomendado) ou use um banco existente/gerenciado (remova o serviço mysql, passe DB_HOST).
  • Qualquer coisa que deva permanecer intocada (workflows de deploy antigos, arquivo compose Sail).

3. Prepare o código para container

  • Confie no proxy. O Traefik do Coolify termina TLS e encaminha HTTP. Sem confiar em X-Forwarded-*, Laravel gera URLs http:// (conteúdo misto, assets Livewire/Filament quebrados, cookies inseguros, web push falha). Laravel 11+: em bootstrap/app.php
    ->withMiddleware(function (Middleware $middleware): void {
        $middleware->trustProxies(at: '*');
    })
    
    Laravel ≤10: defina protected $proxies = '*'; em app/Http/Middleware/TrustProxies.php. '*' é seguro apenas porque a porta 8080 nunca é exposta à internet — diga isso na documentação.
  • Repare o lockfile npm se a varredura sinalizou:
    python3 <skill-dir>/scripts/repair_npm_lock.py <project-dir>
    
    Ele apenas re-resolve pacotes de binários nativos (rollup, esbuild, lightningcss, Tailwind oxide, swc, sass-embedded); reporte os bumps de versão que imprimir.
  • .env.example: adicione chaves que o app lê mas o exemplo não tem (compare chamadas env( em config/ com o arquivo) para que a documentação de deploy seja completa.
  • .gitignore: adicione .env.docker.

4. Gere os arquivos Docker

Copie de assets/ para o projeto e preencha placeholders: __IMAGE__, __REPO_URL__ (URL GitHub https, vincula o pacote GHCR ao repositório), __APP_NAME__, __PHP_VERSION__, __PHP_EXTENSIONS__, __QUEUES__. Depois adapte:

  • Remova o serviço worker se nada estiver enfileirado; descomente scheduler se houver tarefas agendadas.
  • Troque o serviço/env do banco para Postgres, MariaDB ou Redis conforme references/variants.md.
  • Adicione chaves env específicas do app (API keys, VAPID, S3) ao anchor x-app-env como ${VAR:-}; marque as verdadeiramente obrigatórias como ${VAR:?msg} para que um valor faltando falhe alto em vez de iniciar meio configurado.
  • Defina APP_TIMEZONE default como o padrão do config/app.php do app.
  • Gerenciador de pacotes ≠ npm, sem package.json, SSR, Chromium → references/variants.md.

Decisões de design embutidas nos templates (mantenha-as a menos que haja um motivo):

  • serversideup/php fornece NGINX+FPM como non-root www-data na :8080, health checks /up, healthcheck-queue/healthcheck-schedule, e AUTORUN_ENABLED que executa storage:link, espera o DB, migrate --force, e php artisan optimize (inclui filament:optimize e hooks de otimização de outros pacotes). Apenas o serviço app define AUTORUN_ENABLED=true, então as migrações rodam uma vez; worker/scheduler esperam o app ficar saudável.
  • Estágio de assets em $BUILDPLATFORM — roda nativamente no Mac enquanto estágios PHP são emulados para amd64; a saída é independente de arquitetura.
  • Composer install antes de copiar o código fonte — camada de dependências fica em cache; rebuilds só de código são rápidos mesmo sob emulação.
  • Um volume storage/app compartilhado para app + worker (+ scheduler) — arquivos que um job escreve devem ser visíveis ao container web.
  • Logs para stderr para que o visualizador de logs da plataforma os mostre.

5. Verifique localmente antes de enviar qualquer coisa

Faça isso de verdade — não pare em "o Dockerfile parece correto". Use um nome de projeto compose para não colidir com containers de dev.

docker buildx build --load -t <nome>:test .                       # arquitetura nativa, rápido
docker run --rm --entrypoint php <nome>:test -m                  # extensões presentes?
docker run --rm --entrypoint php <nome>:test artisan key:generate --show
cp .env.docker.example .env.docker   # APP_IMAGE=<nome>, IMAGE_TAG=test, PULL_POLICY=never, key, senhas
docker compose -p <nome>test --env-file .env.docker -f docker-compose.prod.yml -f docker-compose.prod.local.yml up -d --wait

(--entrypoint php pula o banner/automações do serversideup para comandos avulsos imprimirem limpo.)

Verifique e reporte cada resultado:

  1. Todos os serviços healthy; logs do app mostram storage:link, migrações, optimize sem ❌.
  2. curl -s -o /dev/null -w '%{http_code}' localhost:8080/up → 200; a página de login/home → 200 e seus URLs CSS/JS retornam 200.
  3. Proxy: curl -s -H 'X-Forwarded-Proto: https' -H 'X-Forwarded-Host: x.example.com' localhost:8080/<pagina>' → URLs de assets começam com https://x.example.com`.
  4. php artisan db:seed --force (se o app tem seeders que o usuário espera na primeira instalação).
  5. Fila: dispare uma classe real enfileirada (uma notificação/job do app) em cada fila nomeada e confirme que o worker loga DONE e o efeito colateral aconteceu. Closures disparadas de tinker --execute falham no worker (código eval não pode ser desserializado) — isso é artefato de teste, não bug. Também respeite shouldSend/autorização própria do app ao escolher um destinatário de teste.
  6. Storage: escreva um arquivo no disco public a partir do worker, busque via localhost:8080/storage/... do app, depois down + up e confirme que arquivos e dados do DB persistem.
  7. Cross-build para o servidor: docker buildx build --platform linux/amd64 -t <nome>:amd64 --load . depois docker image inspect <nome>:amd64 --format '{{.Architecture}}'. Execute em background — builds QEMU levam minutos.

Finalize com docker compose -p <nome>test down -v quando terminar.

6. Escreva a documentação de deploy

Crie docs/DOCKER_DEPLOYMENT.md seguindo references/docs-template.md, no idioma que a documentação existente do projeto usa, e linke-a a partir do README.md. A documentação deve explicar o que mudou e porquê para cada arquivo (o usuário pediu isso quando esta skill foi criada, e futuros mantenedores precisam), a arquitetura, configuração única, build/push, teste local, passos no Coolify, atualização/rollback, operações, migração de dados do host antigo, e caveats específicos do projeto que você encontrou no passo 1.

7. Entregue — confirme antes de qualquer ação externa

Enviar para GHCR publica a imagem, e implantar altera a produção, então pare e deixe o usuário decidir. Dê a eles:

  1. echo <PAT with write:packages> | docker login ghcr.io -u <usuario> --password-stdin
  2. Commit, depois scripts/docker-build-push.sh (recusa árvore suja; --load para builds locais).
  3. Passos do Coolify de references/coolify.md — especialmente que o servidor precisa de um login GHCR somente leitura para um pacote privado, feito com sudo docker login (Coolify puxa como root; um login não-root é invisível para ele), e o domínio é inserido como https://dominio:8080 (:8080 = porta do container).
  4. Lembretes: reuse a APP_KEY antiga (e VAPID ou outras chaves de longa duração) ao migrar; desative qualquer workflow de deploy SSH/FTP antigo assim que o novo deploy estiver ativo.

Ofereça-se para executar o push para eles após o login.

Confusão comum do usuário a antecipar

Usuários frequentemente tentam docker run <imagem> ou o botão ▶ do Docker Desktop na imagem isolada. Isso inicia apenas o container web: nenhum serviço de DB existe, autorun está desligado, e Laravel cai de volta para sqlite (Database file at path [...] does not exist) ou falha resolvendo mysql. A resposta é sempre a stack compose. Diga isso na seção de teste local da documentação.

Habilidades Relacionadas