Deploy automático e rollback no Coolify

Resposta rápida

Para publicar a cada push no Coolify, deixe Auto deploy em Deploy on push (webhooks), nas opções Advanced da aplicação. Com o GitHub App, o webhook já vem pronto. Com repositório público ou deploy key, copie o endereço e o segredo da página Webhooks e cadastre no seu Git. Para voltar a uma versão anterior, abra Rollback e clique em Rollback ao lado da imagem desejada. O rollback volta só a imagem e o código: banco, volumes e variáveis ficam como estão.

O painel do Coolify é em inglês. Neste manual, os botões aparecem como estão na tela, em negrito, com a tradução ao lado. Dúvida com algum termo? Veja o glossário do Coolify em português.

Você vai aprender

Ligar o deploy a cada push e entender a fila de deploys
Cadastrar o webhook manual com segredo no GitHub, GitLab, Bitbucket ou Gitea
Chamar o deploy pela API a partir de uma esteira de CI
Voltar para uma versão anterior com o rollback, sabendo o que ele não desfaz
Ligar prévias de pull request com segurança

Antes de começar

Uma aplicação publicada pelo Git (publicar pelo Git)
O painel no seu domínio, com HTTPS, para o Git conseguir chamar o webhook (domínio do painel)

Neste guia

Três jeitos de publicar sem clicar em Deploy
Ligue o deploy a cada push
Volte para uma versão anterior
Prévias de pull request
Problemas comuns

Três jeitos de publicar sem clicar em Deploy

GitHub AppRepositório ligado pela integração do GitHub: o deploy a cada push já vem configurado.
Webhook manualRepositório público ou com deploy key: você cadastra no Git o endereço e o segredo que o Coolify mostra.
Deploy pela APIUma esteira de CI chama o endereço de deploy depois dos testes, com um token da API.

Nos três casos, o serviço de Git precisa alcançar o painel pela internet. Painel acessado só pelo IP e pela porta 8000, ou atrás do firewall, não recebe o aviso do push. Para o GitHub App, veja repositório privado.

Ligue o deploy a cada push

Confira o Auto deploy
No painel: site-da-lojaAdvanced(a sua aplicação › Avançado)
Na seção Deployment (deploy), deixe Auto deploy em Deploy on push (webhooks) (publicar a cada push). Salve, se mudou algo.
Dica Ao lado, Queued webhook deployments vem em Cancel when a newer push arrives: um push novo cancela o deploy de webhook mais antigo que ainda está na fila. O deploy que já está em build termina (Let the build finish).
Copie o endereço e o segredo do webhook
No painel: site-da-lojaWebhooks(a sua aplicação › Webhooks)
Em Manual Git webhooks, cada Git tem o seu Webhook URL (endereço) e o Webhook secret (segredo). Clique em Generate (gerar) para criar o segredo, com no mínimo 16 caracteres.
1. Deploy webhook: o endereço de deploy pela API. Só funciona com a API ligada e um token com permissão deploy.
2. Manual Git webhooks: endereço e segredo para GitHub, GitLab, Bitbucket e Gitea.
Cadastre o webhook no Git
No GitHub, em Settings > Webhooks do repositório, crie um webhook com o Webhook URL e o mesmo segredo, para o evento push. GitLab, Bitbucket e Gitea têm telas parecidas.

Para chamar o deploy de uma esteira de CI, use o endereço da seção Deploy webhook. A API vem desligada: o painel avisa API access is turned off. Ligue a API e crie um token com permissão deploy, como em segurança do Coolify, e guarde o token como segredo da esteira, nunca no código.

curl -X POST "https://painel.example.com/api/v1/deploy?uuid=UUID-DA-APLICACAO&force=false" \
  -H "Authorization: Bearer TOKEN-DE-EXEMPLO"

Deploy pela API. Use POST: uma chamada GET responde com erro 405.

Volte para uma versão anterior

Escolha a versão e clique em Rollback
No painel: site-da-lojaRollback(a sua aplicação › Voltar versão)
A lista mostra as imagens das versões anteriores guardadas na VPS, e a atual aparece como Running image. Clique em Rollback ao lado da versão que deve voltar ao ar.
Dica Images to keep (imagens a guardar) define quantas versões ficam guardadas. Cada uma ocupa espaço no disco da VPS.

O rollback volta só a imagem e o código

Banco, migrations, volumes e variáveis ficam como estão. Se a versão nova mudou a estrutura do banco, a antiga pode não funcionar com ele. A limpeza automática do Docker também pode apagar imagens antigas, e elas somem da lista.

Prévias de pull request

Ligue as prévias
No painel: site-da-lojaPreview Deployments(a sua aplicação › Prévias)
Clique em Enable Preview Deployments (ligar prévias). Cada pull request ganha uma cópia da aplicação, num endereço próprio.
1. Botão Enable Preview Deployments, que liga as prévias.
2. Preview URL template: o modelo do endereço. {{pr_id}} vira o número do pull request, como em 12.loja.example.com.

O endereço da prévia precisa de um DNS curinga, como *.loja.example.com, apontando para a VPS. A prévia some sozinha quando o pull request é fechado ou mesclado, e tem variáveis próprias (variáveis de ambiente).

Cuidado com pull request de fork

Um pull request roda código na sua VPS. Em repositório público, qualquer pessoa pode abrir um a partir de um fork. Mantenha PR deployment access em Repository members only (só membros do repositório).

Como saber se deu certo

Um push no branch publicado inicia o deploy sozinho, a página Rollback lista as versões guardadas e, se ligadas, as prévias aparecem em Preview Deployments.

Problemas comuns

O push não dispara o deploy

Causa provável: O Git não alcança o painel (acesso só por IP e porta, ou firewall), o segredo é diferente nos dois lados ou o Auto deploy está desligado.
O que fazer: Ponha o painel no domínio com HTTPS, gere o segredo de novo e cole o mesmo valor no Git. No Git, a lista de entregas do webhook mostra a resposta do painel.

A chamada ao Deploy webhook falha

Causa provável: A API está desligada, o token não tem a permissão deploy ou a chamada usa GET.
O que fazer: Ligue a API, crie um token com permissão deploy e chame o endereço com POST, como no exemplo acima.

A versão que eu queria não aparece em Rollback

Causa provável: A imagem foi apagada pela limpeza do Docker ou passou do limite de Images to keep.
O que fazer: Aumente Images to keep e confira a limpeza automática em atualizar e manter o Coolify. Uma versão sem imagem só volta com um deploy novo do commit antigo.

Depois do rollback, a aplicação dá erro de banco

Causa provável: As migrations da versão nova continuam aplicadas no banco.
O que fazer: Corrija para frente com um deploy novo ou restaure o banco de antes da atualização (backup do banco).

Não resolveu? Veja os problemas comuns do Coolify ou abra um chamado na central do cliente.

Próximo passoLogs, terminal e monitoramento no CoolifyAs ferramentas para entender o que a aplicação está fazendo: logs, terminal web, healthcheck, limites de CPU e memória e métricas.

Fontes e documentação oficial

Coolify é um software de código aberto mantido pelo próprio projeto. Este manual é da Hospedagem Segura, para quem roda o Coolify nas nossas VPS, e foi conferido na versão 4.7.5.

Continue aprendendo

Ver todos os guias do Manual do Coolify

Rode o Coolify numa VPS da Hospedagem Segura

VPS Linux com acesso root, disco NVMe e IPv4 dedicado a partir de R$ 69,90/mês. Prefere a VPS pronta? No VPS Assistido, o Coolify vem instalado, com o painel no seu domínio, e a equipe ajuda no dia a dia.

Ver VPS para Coolify Conhecer o VPS Assistido