Docker Compose: diferença entre build e image no VPS
Entenda por que compose up ignora mudanças no Dockerfile, como pull_policy decide entre baixar e criar a imagem e qual chave usar no VPS.
Docker Compose build vs image: a resposta curta
Num ficheiro Docker Compose, image: identifica a imagem a utilizar, incluindo uma imagem local, uma tag ou uma referência a um digest, e build: indica ao Compose como criar uma imagem a partir do código-fonte. Defina apenas image: e o Compose utiliza ou obtém a imagem conforme pull_policy. Defina apenas build: e o Compose cria a imagem com o builder configurado, atribuindo-lhe um nome derivado do nome do projeto e do nome do serviço. Defina ambos e pull_policy controla se o Compose obtém ou cria a imagem; quando a cria, atribui-lhe a tag com o nome indicado em image:. É assim que se cria uma imagem e se publica com um nome escolhido por si. O builder pode ser executado localmente ou num Docker host remoto.
Essa é toda a distinção. O restante explica o que isto significa na operação de um servidor. Isto pressupõe que o Docker Engine e o plugin Compose já estão instalados; executar Docker num VPS explica essa parte.
As três formas completas
Use uma tag publicada, fazendo pull se ela não existir, de acordo com a política de pull predefinida. Não há qualquer Dockerfile envolvido.
services:
web:
image: nginx:1.27
restart: unless-stopped
ports:
- "80:80"Faça o build a partir de um Dockerfile no diretório do projeto. O build também pode fazer pull de imagens e transferir as dependências exigidas pelo Dockerfile.
services:
web:
build: .
restart: unless-stopped
ports:
- "80:80"Faça o build e atribua ao resultado a tag docker compose build; sem uma política de pull explícita, up tenta fazer pull desta imagem antes de a criar. Em seguida, docker compose push pode enviar essa tag exata para um registry.
services:
web:
build:
context: .
dockerfile: Dockerfile
image: registry.example.com/acme/web:1.4.2
restart: unless-stopped
ports:
- "80:80"context é o diretório enviado para o builder. dockerfile é resolvido relativamente a esse contexto, por isso context: . com dockerfile: docker/prod.Dockerfile é normal e correto. Execute docker compose images para ver o nome e o ID da imagem associados a cada contentor de serviço; verifique o ficheiro Compose para confirmar se o serviço usa image:, build: ou ambos.
Por que docker compose up não faz um novo build depois que altero o Dockerfile?
Porque o up comum reutiliza uma imagem existente, a menos que você solicite um build ou configure uma política que exija um.
Quando o Compose inicia um serviço que tem apenas uma seção build:, ele usa a imagem existente, se houver uma disponível. Ele não lê o seu Dockerfile, compara os ficheiros-fonte nem verifica timestamps. Quando existem image: e build:, mas nenhum pull_policy explícito, o Compose tenta fazer pull primeiro e faz o build se a imagem não estiver disponível no registry ou no cache da plataforma. Se a imagem estiver presente, ela é considerada suficiente.
Assim, você edita o app.py, executa docker compose up -d, vê o Compose informar que o container está em execução e acaba a servir o código antigo. Nada falhou, portanto nada emitiu um aviso. O indício está na palavra de estado que o Compose imprime ao lado do nome do container: um container que o Compose substituiu aparece como recriado ou iniciado, enquanto um container que o Compose decidiu manter aparece como em execução.
Duas verificações resolvem a questão. docker compose images imprime o ID da imagem usada por cada container. Anote-o antes do deploy e compare-o depois. docker image ls tem uma coluna CREATED, mas builds em cache e timestamps reproduzíveis significam que essa data, por si só, não prova se o código-fonte mais recente foi incluído no build.
Que flags forçam uma reconstrução
docker compose up -d --buildfaz primeiro a compilação e, em seguida, recria qualquer contentor cuja imagem tenha sido alterada. Este é o flag que a maioria das pessoas procura.docker compose build webcompila um serviço e não inicia nada. Use-o comdocker compose up --no-deps -d webpara substituir apenas esse contentor e manter o resto da stack em execução.docker compose build --no-cache webignora as camadas em cache e reconstrói o serviço.docker compose build --pulltenta obter uma versão mais recente da imagem base emFROM. Assim, uma tag móvel comonode:22recebe o conteúdo atual, em vez da cópia que foi descarregada em março.docker compose up -d --force-recreateforça a recriação do contentor mesmo que a configuração e a imagem não tenham sido alteradas. O flag, por si só, não solicita uma compilação, masupainda pode compilar quando falta uma imagem ou quando a política de pull o exige. Usar este flag quando pretendia usar--buildé um erro comum.
Também pode colocar essa decisão no ficheiro. Segundo a especificação do Compose, pull_policy: build significa que o Compose compila a imagem e volta a compilá-la se ela já existir. Cada up implica então uma compilação, o que é útil num portátil e raramente é desejável num servidor.
services:
web:
build: .
image: registry.example.com/acme/web:dev
pull_policy: buildTambém é importante conhecer outra interação. docker compose pull tenta obter imagens para serviços que também têm uma secção build. Se essa obtenção falhar, informa que a imagem tem de ser compilada. Passe --ignore-buildable para ignorar esses serviços silenciosamente.
Como o cache de build determina o tempo do deploy
O builder verifica cada instrução do Dockerfile à procura de um resultado reutilizável em cache quando essa instrução e as suas entradas não foram alteradas. Para COPY, as entradas incluem o conteúdo e os metadados dos ficheiros, excluindo as datas de modificação. Quando uma camada deixa de ser encontrada no cache, os passos seguintes que dependem dela são reconstruídos.
Essa regra determina se o deploy demora segundos ou minutos. Ordene o Dockerfile começando pelo que muda raramente e terminando pelo que muda em cada commit.
FROM node:22-slim
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
CMD ["node", "server.js"]npm ci fica acima de COPY . ., por isso editar um ficheiro-fonte mantém a camada de instalação em cache e o build retoma no passo de cópia. Se trocar essas duas linhas, uma alteração de um único carácter reinstala todas as dependências, porque COPY . . invalida a camada sobre a qual npm ci é construído. A mesma estrutura aplica-se a pip install -r requirements.txt e a go mod download.
--no-cache é a ferramenta adequada quando suspeita que uma camada obsoleta está a ocultar a sua correção. É uma opção predefinida inadequada, porque elimina a reutilização que a ordenação do Dockerfile pretende proporcionar.
Há um aspeto que os conjuntos de imagem e o Compose podem substituir: CMD do Dockerfile define o que a imagem executa por predefinição, e uma chave command: no serviço substitui esse valor. Como command e entrypoint interagem é relevante neste caso, porque uma substituição no Compose pode fazer com que uma imagem acabada de construir se comporte exatamente como a antiga.
Contexto de build e .dockerignore
context: . disponibiliza o diretório do projeto para o builder. Sem exclusões, isso inclui .git e qualquer diretório de dados que mantenha junto do código-fonte, embora o BuildKit ignore ficheiros não utilizados e transfira incrementalmente as alterações. Se um build ficar parado na etapa de transferência do contexto num projeto que não sofreu alterações, isso indica que o contexto é demasiado grande.
Um ficheiro .dockerignore na raiz do contexto exclui caminhos dessa transferência. A sintaxe é semelhante à de .gitignore.
.git
node_modules
*.log
data/
.envHá duas vantagens. A transferência diminui, reduzindo o tempo gasto a enviar esses ficheiros. Além disso, COPY . . deixa de poder copiar .env para a imagem, onde qualquer pessoa que faça pull dessa imagem pode ler o conteúdo.
O caso de builds que ficam progressivamente mais lentos envolve um bind mount. Um volume nomeado fica fora do diretório do projeto, mas um bind mount como ./data:/var/lib/postgresql/data fica dentro do contexto de build. Por isso, os builds ficam mais lentos a cada semana à medida que a base de dados cresce. Uma linha em .dockerignore resolve o problema. Bind mounts e volumes nomeados aborda o compromisso mais amplo.
Os argumentos de build apresentam uma versão menor do mesmo risco. Os valores transmitidos por args: podem persistir no histórico da imagem ou nos metadados de proveniência. Por isso, coloque aí um número de versão e nunca um token. Os argumentos de proxy predefinidos são excluídos da cache de build e de docker history por predefinição, exceto quando são referenciados explicitamente no Dockerfile. Ficheiros de ambiente e secrets no Compose explica onde devem ficar as credenciais.
Você deve compilar na VPS ou compilar noutro local e fazer pull?
Compilar no servidor que serve o seu tráfego é a opção padrão porque é o caminho mais curto: git pull e depois docker compose up -d --build. Isto é adequado num servidor pequeno de que ainda ninguém depende. Deixa de ser adequado por dois motivos que pode medir e por outro que só aparece num dia problemático.
Memória. Uma compilação executa compiladores e bundlers junto da aplicação em produção, e estes são a parte que mais memória consome na maioria das stacks. Um bundler de JavaScript ou uma compilação de Rust pode esgotar a memória disponível numa VPS de 1 GB. Quando a memória se esgota, o kernel seleciona uma vítima de OOM usando uma pontuação de gravidade baseada na utilização de memória, no contexto da alocação e em oom_score_adj; não termina simplesmente o processo maior. A compilação pode parar com Killed e o código de saída 137, ou a base de dados pode ser terminada em vez dela e o site pode ficar indisponível a meio de um deploy. dmesg -T | grep -i oom procura mensagens de OOM no log do kernel; o acesso requer permissão para ler esse log.
Disco. As compilações deixam camadas de imagens e cache de compilação. docker system df mostra a utilização de disco; a recolha periódica de lixo do BuildKit recupera o espaço da cache de acordo com as políticas configuradas. Recupere espaço com docker image prune para imagens dangling e com docker builder prune para camadas em cache. Um disco cheio interrompe mais do que a compilação. A base de dados também deixa de escrever, e essa falha custa muito mais do que um deploy lento.
Reprodutibilidade. Sem fazer push ou exportar a imagem, uma imagem compilada no servidor só existe nesse servidor. Se a imagem antiga já não estiver disponível, fazer rollback significa mudar para o commit antigo e compilar novamente. Essa compilação não garante produzir o que tinha antes, porque a tag base mudou e os mirrors de pacotes também mudaram. Compilar noutro local e fazer push de uma tag transforma o rollback numa edição: aponte image: para a tag anterior e execute docker compose up -d.
A configuração que se mantém estável é simples. A sua integração contínua executa a compilação e faz push de registry.example.com/acme/web:<git-sha>, e o ficheiro Compose na VPS contém image: sem nenhuma chave build:.
docker compose pull
docker compose up -dExecute docker login registry.example.com no servidor para guardar as credenciais necessárias para fazer pull de tags privadas.
Mantenha a secção de compilação para desenvolvimento, em vez de a eliminar, num ficheiro com o nome que escolher.
# compose.dev.yaml
services:
web:
build:
context: .
pull_policy: builddocker compose -f compose.yaml -f compose.dev.yaml up -d --buildDê a esse ficheiro o nome compose.dev.yaml, e não compose.override.yaml. O Compose carrega automaticamente um ficheiro de override quando este está presente, por isso um override copiado por engano para o servidor voltaria a iniciar compilações nesse servidor sem aviso. Sobreposição de vários ficheiros Compose explica como a combinação resolve cada chave.
A armadilha da arquitetura quando compila noutro local
Uma imagem de plataforma única inclui a arquitetura de CPU para a qual foi compilada. Se compilar uma imagem ARM num portátil com Apple Silicon, fizer push e depois usar essa imagem numa VPS x86_64, o Docker avisa durante a criação do contentor se utilizar uma imagem em cache incompatível sem uma plataforma explícita. Sem emulação, o processo falha com exec format error. A mensagem parece indicar um binário corrompido, mas não é esse o problema. Compile explicitamente para o destino:
docker buildx build --platform linux/amd64 \
-t registry.example.com/acme/web:1.4.2 --push .A mesma incompatibilidade ocorre no sentido inverso se o portátil usar x86 e executar uma VPS ARM em vez de uma VPS x86. Permitir que o CI compile na arquitetura onde a aplicação será implementada elimina esta questão. Uma imagem multiplataforma também resolve o problema: o Docker seleciona a variante correspondente ao fazer pull.
O que verificar depois de uma implementação
docker compose imagesmostra a imagem e a tag usadas por cada contentor em execução. Um ID de imagem diferente confirma que a nova compilação está em serviço.docker compose configmostra o ficheiro resultante depois da substituição das variáveis, para que possa ler o nome final da imagem que o Compose vai usar antes de executar qualquer comando.docker compose logs -f webdurante os primeiros 30 segundos depois da troca. Um contentor que inicia e termina repetidamente só é reiniciado se a respetiva política de reinício o determinar; consulte os logs para identificar a causa.docker image lsmostra uma coluna CREATED. Consulte também o resultado da compilação e o ID da imagem implementada, porque o timestamp de criação, por si só, não confirma se foi executada uma nova compilação.
Se ainda estiver a montar o ficheiro que estas verificações vão analisar, os conceitos básicos de um ficheiro Compose num VPS explica as chaves relacionadas, e a referência rápida dos comandos Compose lista os restantes subcomandos.
FAQ
Posso usar build e image no mesmo serviço?
Sim. Essa é a configuração normal para um projeto que você mesmo compila. Quando o Compose compila a partir da secção build:, atribui ao resultado a tag com o valor de image:; sem um pull_policy explícito, up tenta fazer pull primeiro. Essa tag é a que docker compose push envia para um registry e que outra máquina obtém. Sem a chave image:, o Compose continua a compilar, mas atribui à imagem um nome baseado no projeto e no serviço. Também avisa que o atributo em falta impede o push da imagem.
Por que docker compose up não deteta a alteração no meu Dockerfile?
Porque um up normal reutiliza uma imagem existente, a menos que você solicite uma compilação ou configure uma política que a exija. Ele não compara essa imagem com o Dockerfile nem com os ficheiros-fonte para decidir se é necessário recompilar. Execute docker compose up -d --build ou execute docker compose build web seguido de docker compose up --no-deps -d web para substituir um único serviço. Definir pull_policy: build no serviço faz com que cada up recompile a imagem, o que é adequado para uma máquina de desenvolvimento.
Qual é a diferença entre --build e --force-recreate?
--build recompila a imagem e depois recria os contentores cuja imagem foi alterada. --force-recreate força a recriação dos contentores mesmo que a configuração e a imagem não tenham sido alteradas; por si só, não solicita uma compilação. Se a alteração estiver no código-fonte ou no Dockerfile, --build é a flag pretendida. --force-recreate serve para repor o próprio contentor, por exemplo, para limpar a camada gravável mantendo a mesma imagem.
Devo compilar as minhas imagens Docker no VPS ou noutro local?
Compile noutro local e faça pull de uma tag quando o servidor também servir tráfego. A compilação disputa memória com a aplicação e, quando a memória se esgota, o kernel seleciona um processo para terminar usando uma pontuação OOM ajustável. Esse processo pode ser a compilação ou a base de dados. As compilações também deixam cache no disco, embora o BuildKit a recupere automaticamente de acordo com as respetivas políticas de recolha de lixo. Compilar no servidor continua a ser aceitável para um projeto pequeno sem utilizadores. A migração posterior é simples se você mantiver a secção build: num ficheiro Compose exclusivo para desenvolvimento.
Como impeço que a cache de compilação do Docker encha o disco?
Execute docker system df para ver quanto espaço as suas imagens e a cache de compilação ocupam. docker builder prune remove as camadas em cache e docker image prune remove as imagens dangling deixadas por compilações anteriores. Adicionar -a remove toda a cache de compilação não utilizada ou todas as imagens não referenciadas por contentores, respetivamente; isso não garante que a próxima compilação comece sem cache. Não agende docker system prune -af --volumes num servidor, porque ele remove contentores parados e volumes anónimos não utilizados, colocando em risco os dados de bases de dados armazenados num volume anónimo durante a manutenção.