SSD Nodes Learn Hosting plans →
Guias Matt ConnorPor Matt Connor

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 --build faz 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 web compila um serviço e não inicia nada. Use-o com docker compose up --no-deps -d web para substituir apenas esse contentor e manter o resto da stack em execução.
  • docker compose build --no-cache web ignora as camadas em cache e reconstrói o serviço.
  • docker compose build --pull tenta obter uma versão mais recente da imagem base em FROM. Assim, uma tag móvel como node:22 recebe o conteúdo atual, em vez da cópia que foi descarregada em março.
  • docker compose up -d --force-recreate forç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, mas up ainda 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: build

També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/
.env

Há 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 -d

Execute 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: build
docker compose -f compose.yaml -f compose.dev.yaml up -d --build

Dê 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 images mostra 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 config mostra 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 web durante 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 ls mostra 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.

Este artigo foi útil?