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__):
| Caminho | Uso |
|---|---|
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/Dockerfile | Imagem multi-estágio baseada em serversideup/php:<ver>-fpm-nginx. |
assets/dockerignore | Salve como .dockerignore. |
assets/docker-compose.prod.yml | app + worker + (scheduler) + mysql, arquivo que o Coolify aponta. |
assets/docker-compose.prod.local.yml | Override para workstation: expõe :8080, sem cookies seguros. |
assets/env.docker.example | Salve como .env.docker.example; modelo para env local e Coolify. |
assets/docker-build-push.sh | Salve como scripts/docker-build-push.sh; compila amd64 e envia latest + SHA do git. |
references/variants.md | Postgres/MariaDB, Redis, Horizon, Reverb, Octane, SSR, Wayfinder, pnpm/yarn/bun, Chromium, apenas SQLite. |
references/coolify.md | Autenticação GHCR no servidor, criação do recurso, domínio :8080, deploy/update/rollback. |
references/other-platforms.md | Dokploy, EasyPanel, CapRover, Docker simples + Caddy, notas sobre Kubernetes. |
references/troubleshooting.md | Tabela sintoma → causa → solução. Leia quando algo falhar. |
references/docs-template.md | Esboç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ó porquecomposer.jsondiz^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 eminstall-php-extensions.gmp/bcmathaparecem 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, vejareferences/variants.md.queues—needs_workereworker_queue_arg. O--queue=do worker deve listar todas as filas nomeadas (deonQueue,$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çoscheduler.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 queconfig_defaulté muitas vezessqlite: seDB_CONNECTIONnã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 quenpm cifalhará no Linux. Executerepair_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 umdocker-compose.ymlexistente (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-arquiteturalinux/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, passeDB_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 URLshttp://(conteúdo misto, assets Livewire/Filament quebrados, cookies inseguros, web push falha). Laravel 11+: embootstrap/app.phpLaravel ≤10: defina->withMiddleware(function (Middleware $middleware): void { $middleware->trustProxies(at: '*'); })protected $proxies = '*';emapp/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:
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.python3 <skill-dir>/scripts/repair_npm_lock.py <project-dir> .env.example: adicione chaves que o app lê mas o exemplo não tem (compare chamadasenv(emconfig/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
workerse nada estiver enfileirado; descomenteschedulerse 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-envcomo${VAR:-}; marque as verdadeiramente obrigatórias como${VAR:?msg}para que um valor faltando falhe alto em vez de iniciar meio configurado. - Defina
APP_TIMEZONEdefault como o padrão doconfig/app.phpdo 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-datana :8080, health checks/up,healthcheck-queue/healthcheck-schedule, eAUTORUN_ENABLEDque executastorage:link, espera o DB,migrate --force, ephp artisan optimize(incluifilament:optimizee hooks de otimização de outros pacotes). Apenas o serviçoappdefineAUTORUN_ENABLED=true, então as migrações rodam uma vez; worker/scheduler esperam oappficar 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/appcompartilhado 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:
- Todos os serviços
healthy; logs doappmostramstorage:link, migrações,optimizesem ❌. 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.- Proxy:
curl -s -H 'X-Forwarded-Proto: https' -H 'X-Forwarded-Host: x.example.com' localhost:8080/<pagina>' → URLs de assets começam comhttps://x.example.com`. php artisan db:seed --force(se o app tem seeders que o usuário espera na primeira instalação).- Fila: dispare uma classe real enfileirada (uma notificação/job do app) em cada fila nomeada e confirme que o worker loga
DONEe o efeito colateral aconteceu. Closures disparadas detinker --executefalham no worker (código eval não pode ser desserializado) — isso é artefato de teste, não bug. Também respeiteshouldSend/autorização própria do app ao escolher um destinatário de teste. - Storage: escreva um arquivo no disco
publica partir do worker, busque vialocalhost:8080/storage/...do app, depoisdown+upe confirme que arquivos e dados do DB persistem. - Cross-build para o servidor:
docker buildx build --platform linux/amd64 -t <nome>:amd64 --load .depoisdocker 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:
echo <PAT with write:packages> | docker login ghcr.io -u <usuario> --password-stdin- Commit, depois
scripts/docker-build-push.sh(recusa árvore suja;--loadpara builds locais). - Passos do Coolify de
references/coolify.md— especialmente que o servidor precisa de um login GHCR somente leitura para um pacote privado, feito comsudo docker login(Coolify puxa como root; um login não-root é invisível para ele), e o domínio é inserido comohttps://dominio:8080(:8080= porta do container). - Lembretes: reuse a
APP_KEYantiga (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.