Build compartilhado — do código ao ambiente¶

Build é a construção da imagem Docker a partir do código. Registry é o serviço que guarda a imagem. Deploy é sua instalação no ambiente escolhido.

O Coolify coordena, a máquina de build constrói e o servidor do ambiente executa.

Base desta documentação — 05/10/2026

Página preparada a partir dos registros de implantação de agosto e setembro de 2026. A configuração atual dos servidores não foi reconferida nesta revisão. Conferir permissões e limitações de versão antes de alterar o ambiente.

Quem faz o quê¶

flowchart LR
    A["Coolify<br/>Adapter / BravoCore"]
    S["Coolify<br/>SmartITBI"]
    L["Coolify<br/>LBCA"]
    B["Coolify<br/>Bravobot"]
    BUILD["Máquina de build<br/>Constrói as imagens"]
    REG[("IBM Container Registry<br/>br.icr.io")]
    AMB["Servidores dos ambientes<br/>Executam as aplicações"]
    A --> BUILD
    S --> BUILD
    L --> BUILD
    B --> BUILD
    BUILD -->|"Envia as imagens"| REG
    REG -->|"Ambientes baixam as imagens"| AMB

Peça	Responsabilidade
GitHub	Guarda o código e avisa sobre alterações na branch configurada
Coolify do produto	Coordena a construção e a publicação da aplicação
Máquina de build compartilhada	Constrói pelo Dockerfile e envia a imagem ao registry
IBM Container Registry (`br.icr.io`)	Guarda as imagens privadas
Servidor do ambiente	Baixa a imagem e executa com suas variáveis, redes e volumes

A máquina de build atende Adapter/BravoCore, SmartITBI, LBCA e Bravobot. Cada produto mantém seu próprio Coolify.

Construir fora do ambiente reduz a disputa por CPU, memória e disco com as aplicações. Isso não elimina o impacto da troca de containers ou de alterações no banco.

A mesma máquina também hospeda a wiki e o Langfuse fora do gerenciamento de aplicações do Coolify. Manutenção e falta de disco podem afetar esses serviços e novas publicações.

Do código à aplicação¶

flowchart TD
    G["Alteração na branch do GitHub"]
    C["Coolify recebe o aviso"]
    B["Máquina de build constrói<br/>a imagem pelo Dockerfile"]
    R["Imagem enviada ao registry"]
    D["Servidor do ambiente<br/>baixa a imagem"]
    E["Aplicação inicia com suas<br/>variáveis, redes e volumes"]
    V["Conferir versão publicada<br/>e testar o fluxo alterado"]
    G -->|"Webhook"| C
    C --> B
    B --> R
    R --> D
    D --> E
    E --> V

Uma alteração chega à branch configurada para o ambiente.
O GitHub envia um webhook, aviso automático, ao Coolify do produto.
O Coolify usa o servidor de build para construir a imagem pelo Dockerfile.
A imagem é enviada ao namespace do produto no registry. Namespace é a divisão que agrupa suas imagens.
O servidor do ambiente baixa a imagem e inicia os containers.
A equipe confere a versão em execução e o funcionamento da aplicação.

Deploy automático depende do webhook correspondente no GitHub. A opção ligada no painel, sozinha, não comprova que uma alteração dispara a publicação.

Configuração no Coolify¶

Configuração	O que conferir
Código	Repositório, branch, diretório base e caminho do Dockerfile
Destino	Servidor e ambiente onde a aplicação executará
Build externo	Servidor cadastrado como build server e selecionado para a aplicação
Imagem	Campo `docker_registry_image_name` com o caminho completo no registry
Variáveis	Separação entre valores de build e valores de execução
Inicialização	Comando, porta, verificação de saúde, redes e volumes
Automação	Webhook correspondente ao recurso e à branch

As branches variam: no Adapter, frontend e API Koa usam dev; o BravoCore usa develop. Consulte a página do produto antes de copiar a configuração.

Dockerfile e Docker Compose

Na implantação do Bravobot de 01/09/2026, o build externo funcionou com aplicações por Dockerfile. O caminho de Docker Compose daquela versão falhou com No such container. Isso explica a separação em aplicações; não comprova que versões atuais tenham a mesma limitação.

Registry e acesso¶

Os registros de implantação usam o IBM Container Registry em br.icr.io, com namespaces por produto e imagens por aplicação e ambiente. A tag identifica o commit.

Exemplo: br.icr.io/bravobot/<aplicacao>-<ambiente>:<commit>.

Leia o nome exato no recurso do Coolify. Um mesmo commit pode gerar imagens diferentes entre ambientes, pois as variáveis de build podem mudar.

Push, envio: a máquina de build precisa escrever nos namespaces atendidos.
Pull, download: o servidor do ambiente precisa ler as imagens do produto.

A credencial de envio é compartilhada

No desenho registrado, uma identidade atende os quatro produtos. Substituí-la por uma credencial limitada a um produto no mesmo contexto Docker pode interromper os demais. Ao adicionar um produto, revisar as permissões da identidade existente antes de executar um novo login.

A autenticação Docker depende do usuário e do contexto de execução. Um login no terminal não prova que o processo usado pelo Coolify tenha acesso. Confira envio e download separadamente, sem imprimir tokens ou arquivos de autenticação.

Solicite credenciais à equipe responsável. Nunca coloque segredos nas variáveis incorporadas ao JavaScript do frontend: esse conteúdo chega ao navegador.

Como conferir o resultado¶

No histórico de deploys, conferir branch, commit e as etapas de construção, envio, download e inicialização. Depois, conferir a imagem em execução e testar o fluxo alterado.

Imagem no registry prova envio, não execução no ambiente. HTTP 200 também não comprova, sozinho, acesso ao banco, funcionamento dos workers ou conclusão de tarefas.

Onde o deploy pode falhar¶

flowchart TD
    F{"Em qual etapa falhou?"}
    F --> B["Construção"]
    F --> P["Envio ao registry"]
    F --> D["Download da imagem"]
    F --> I["Inicialização"]
    B --> BC["Conferir Dockerfile,<br/>dependências, variáveis de build<br/>e espaço em disco"]
    P --> PC["Conferir nome da imagem,<br/>permissão de escrita<br/>e conexão com o registry"]
    D --> DC["Conferir tag disponível,<br/>permissão de leitura<br/>e acesso do servidor"]
    I --> IC["Conferir logs, variáveis,<br/>comando, porta,<br/>banco e volumes"]
    BC --> V["Antes de tentar novamente:<br/>conferir se a versão anterior<br/>continua saudável"]
    PC --> V
    DC --> V
    IC --> V

Sintoma	Onde investigar
Alteração não inicia deploy	Entrega do webhook, branch e opção de deploy automático
Falha ao baixar código	Acesso ao repositório, branch e diretório base
Erro na construção	Log do Dockerfile, dependências, variáveis de build e disco
`Failed to push image to docker registry`	Nome da imagem, permissão de escrita, conectividade e resposta do registry
`pull access denied`	Nome da imagem, tag existente e permissão de leitura no destino
Imagem baixada, aplicação não inicia	Variáveis de execução, comando, banco, volumes e logs do container
Frontend usa a API anterior	Variável de build: mudar apenas a configuração de execução não refaz o JavaScript

Antes de repetir, identificar a etapa que falhou e conferir se a versão anterior continua saudável. Não apagar imagens ou volumes como tentativa de corrigir um erro ainda sem diagnóstico.

Manutenção e retorno à versão anterior¶

Mudanças em Docker, SSH, credencial do registry e limpeza de disco devem considerar os quatro produtos e os serviços hospedados na máquina de build.

Antes de limpar, conferir builds em andamento e distinguir cache, imagens necessárias para retorno e volumes persistentes. Não remover volumes como rotina de limpeza de build.

Para retornar uma aplicação, identificar a imagem anterior e confirmar sua disponibilidade no registry. Conferir a compatibilidade com o banco atual: trocar a imagem não desfaz migrações nem recupera dados. O procedimento deve ser definido para cada produto antes de uma publicação que altera seu banco.

A wiki tem publicação própria¶

Esta wiki usa MkDocs e o script publicar.sh. Um merge não atualiza o site sozinho. Veja como publicar a wiki.