Pular para o conteúdo

Tutorial: Docker Compose build com multi-stage para reduzir imagens

Por Equipe Técnica AviraHost · 17 min de leitura · Atualizado em · AviraHost, docker, docker-compose, multi-stage, dockerfile, imagens-docker, vps-linux · 0

Docker Compose build com multi-stage é o uso do docker compose build sobre um Dockerfile com vários estágios (FROM), no qual você compila a aplicação em um estágio e copia só o resultado para uma imagem final enxuta. O Compose não reduz a imagem sozinho: a redução vem da estrutura do Dockerfile, e o Compose apenas aponta o contexto e o estágio (target). Para aplicar no seu VPS Linux, siga estes passos:

  1. Escreva um Dockerfile com um estágio de build e um estágio final enxuto.
  2. Copie para o estágio final apenas os artefatos necessários com COPY --from.
  3. Crie um .dockerignore para reduzir o contexto de build.
  4. Configure build.context, build.dockerfile e build.target no docker-compose.yml.
  5. Rode docker compose build e compare o tamanho com docker image ls.
  6. Limpe imagens e cache antigos com docker image prune e docker builder prune.

Pré-requisitos

  • Um VPS Linux com acesso SSH e usuário com permissão para usar o Docker (grupo docker ou sudo).
  • Docker Engine com o plugin Compose v2 (comando docker compose, sem hífen). Confirme com docker compose version.
  • Uma aplicação de exemplo. Neste tutorial usamos Node.js 22 LTS, mas o princípio vale para Go, Java, Python e outras linguagens.
  • Projeto com package-lock.json ou npm-shrinkwrap.json versionado no repositório. Os exemplos usam npm ci, que exige um desses arquivos; sem ele, o build falha. Gere o lockfile com npm install antes do primeiro build.
  • Noções básicas de Dockerfile e YAML. Se precisar de uma base, leia Entenda Docker Compose: suba múltiplos serviços no VPS.
  • Espaço em disco livre para as camadas de cache. Para dimensionar o servidor, veja VPS para Docker: como dimensionar memória, CPU e disco.

Por que as imagens ficam grandes sem multi-stage

Em um Dockerfile de estágio único, tudo o que você instala para compilar permanece na imagem final: compiladores, cabeçalhos, cache do gerenciador de pacotes, dependências de desenvolvimento e código-fonte. Cada instrução RUN, COPY e ADD cria uma camada, e apagar um arquivo em uma camada posterior não devolve o espaço das camadas anteriores.

O resultado em um VPS é concreto: pulls e deploys mais lentos, mais disco ocupado e uma superfície de ataque maior, já que a imagem de produção carrega ferramentas que a aplicação nunca usa em execução.

Veja um exemplo de estágio único, que serve de ponto de partida para comparar depois:

FROM node:22
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
CMD ["node", "dist/server.js"]

Essa imagem inclui o node_modules completo (com dependências de desenvolvimento), o código-fonte original e a base completa do Node.js. Antes de otimizar, anote o tamanho atual:

docker build -t app:single .
docker image ls app:single

Guarde o valor da coluna SIZE. Ele será sua referência para medir o ganho real, já que o resultado varia por projeto.

Escrevendo o Dockerfile com estágios separados

Um Dockerfile multi-stage usa mais de um FROM. Cada estágio recebe um nome com AS, e o estágio final copia só o necessário dos anteriores com COPY --from. Este exemplo assume uma aplicação Node.js que gera a saída em dist/ e tem um servidor em dist/server.js. O projeto precisa ter o package-lock.json versionado, pois o npm ci o exige:

# Estágio 1: instala todas as dependências e compila
FROM node:22-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Estágio 2: instala só as dependências de produção
FROM node:22-alpine AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev

# Estágio 3: imagem final de produção
FROM node:22-alpine AS production
ENV NODE_ENV=production
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY --from=build /app/dist ./dist
COPY package*.json ./
USER node
EXPOSE 3000
CMD ["node", "dist/server.js"]

O que cada parte faz:

  • build: contém o código-fonte, as dependências de desenvolvimento e o resultado da compilação. Nada disso vai para a imagem final, exceto dist/.
  • deps: isola a instalação das dependências de produção (--omit=dev), mantendo o node_modules final sem pacotes de teste ou de build.
  • production: parte de uma base limpa, copia os dois resultados e roda como o usuário node, que já existe nas imagens oficiais do Node.js, em vez de root.

Separar package*.json do restante do código também melhora o uso de cache: se só o código mudar, a camada do npm ci é reaproveitada. Se o seu projeto compila para um binário estático (como em Go), o estágio final pode ser ainda menor, usando alpine ou uma imagem distroless.

Reduzindo o contexto com .dockerignore

Antes de qualquer instrução, o Docker envia o contexto de build ao daemon. Sem um arquivo .dockerignore, pastas como node_modules local e .git entram no contexto, deixam o build lento e podem sobrescrever arquivos com o COPY . .. Crie o arquivo na raiz do projeto:

node_modules
dist
.git
.gitignore
.env
*.log
Dockerfile
docker-compose.yml

Incluir .env evita que segredos locais sejam copiados para dentro de camadas da imagem. Para segredos de runtime, prefira o mecanismo secrets do Compose, arquivos montados com permissões restritas ou um gerenciador externo de segredos. Use variáveis de ambiente somente quando o modelo de segurança aceitar sua maior exposição (seus valores podem aparecer em docker inspect e diagnósticos), e nunca grave o valor no Dockerfile ou na imagem com COPY.

Atenção: ignorar dist só faz sentido porque o estágio build o gera dentro do container. Se o seu fluxo compila fora do Docker e copia o resultado, remova essa linha.

Configurando build e target no docker-compose.yml

No Compose, a chave build define como a imagem é construída, e a opção target escolhe até qual estágio do Dockerfile o build vai. Isso permite manter desenvolvimento e produção no mesmo Dockerfile. Um arquivo básico fica assim:

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
      target: production
    image: seudominio.com.br/app:1.0
    restart: unless-stopped
    ports:
      - "127.0.0.1:3000:3000"
    environment:
      - NODE_ENV=production

Observações importantes:

  • target: production constrói o estágio chamado production. Com BuildKit (padrão atual), só são construídos o estágio indicado em target e os estágios de que ele depende (via FROM ou COPY --from); os demais, antes ou depois dele no arquivo, são ignorados.
  • Publicar a porta em 127.0.0.1 mantém o container acessível só pelo próprio host, o que é o desenho certo quando um Nginx faz proxy reverso na frente. Veja o padrão em Otimizar Docker Compose e Nginx no mesmo servidor AlmaLinux 9.
  • Com build e image juntos, o Compose nomeia a imagem construída com o valor de image.

Um estágio para desenvolvimento e outro para produção

Para usar o mesmo Dockerfile em ambientes diferentes, adicione um estágio de desenvolvimento e escolha o alvo por serviço. Acrescente ao Dockerfile, antes do estágio final:

FROM node:22-alpine AS development
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
CMD ["npm", "run", "dev"]

Depois, use um arquivo de override para desenvolvimento. O Compose lê docker-compose.override.yml automaticamente quando você não especifica arquivos com -f, então em produção prefira nomes explícitos:

docker compose -f docker-compose.yml -f docker-compose.dev.yml build

E o arquivo docker-compose.dev.yml:

services:
  app:
    image: seudominio.com.br/app:dev
    build:
      target: development
    environment:
      NODE_ENV: development
    volumes:
      - ./:/app
      - /app/node_modules
    ports: !override
      - "127.0.0.1:3000:3000"

O override define image: seudominio.com.br/app:dev para evitar que a imagem de desenvolvimento sobrescreva a tag de produção :1.0. A variável NODE_ENV: development substitui o valor herdado do arquivo base, garantindo que o estágio development não rode com configurações de produção. A diretiva ports: !override substitui completamente a lista de portas herdada em vez de mesclá-la, evitando conflito entre as publicações 127.0.0.1:3000 e 0.0.0.0:3000. Confirme o resultado final com:

docker compose -f docker-compose.yml -f docker-compose.dev.yml config

O segundo volume anônimo em /app/node_modules evita que o node_modules da imagem seja escondido pela pasta do host. Para outras ideias de ambiente de desenvolvimento, veja Docker para ambiente de desenvolvimento no VPS.

Executando o build e medindo o resultado

Com os arquivos prontos, construa a imagem pelo Compose:

docker compose build

O BuildKit é o construtor padrão nas versões atuais do Docker, e a saída mostra cada estágio sendo processado. Você verá linhas com os nomes dos estágios, como [build 3/5] e [production 4/6]. Para ver a saída completa e sem agrupamento, use:

docker compose build --progress=plain

Depois compare os tamanhos:

docker image ls
REPOSITORY               TAG       IMAGE ID       CREATED          SIZE
seudominio.com.br/app    1.0       ...            ...              ...
app                      single    ...            ...              ...

Compare a coluna SIZE da imagem multi-stage com a do build de estágio único feito antes. Para ver o que ocupa espaço em cada camada, use:

docker history seudominio.com.br/app:1.0

Suba o serviço e confirme que a aplicação continua funcionando com a imagem enxuta:

docker compose up -d
docker compose ps
docker compose logs app

Se precisar reconstruir ignorando camadas armazenadas, por exemplo depois de atualizar uma dependência de base, leia Entenda Docker Compose build sem cache no CentOS 9.

Limpando imagens e cache no VPS

Cada build deixa camadas antigas e cache no disco. Em um VPS com disco limitado, isso se acumula. Primeiro veja o consumo:

docker system df

Atenção: os comandos abaixo removem dados. docker image prune apaga imagens dangling (sem tag e sem uso), e docker builder prune apaga o cache de build dangling (para remover todo o cache não utilizado, use docker builder prune -a após revisar o impacto), o que deixa o próximo build mais lento. Confira o que será removido antes de confirmar; ambos pedem confirmação por padrão.

docker image prune
docker builder prune

Evite docker system prune -a em produção sem revisar: ele remove todas as imagens não usadas por containers existentes, inclusive imagens taggeadas que você pretende usar em um rollback — uma tag local não protege contra esse comando. Antes de limpar, garanta que a versão anterior esteja armazenada em um registro externo ou exportada com docker image save. Você pode usar docker system df -v para conferir quais imagens seriam afetadas.

Problemas comuns e como resolver

Sintoma: o Compose constrói o estágio errado ou a imagem continua grande

Causa: a opção target está ausente ou aponta para outro estágio, então o Compose constrói até o último estágio do Dockerfile ou até um alvo de desenvolvimento. Outra causa comum é o estágio final partir de uma imagem pesada ou copiar a pasta inteira (COPY --from=build /app .).
Solução: confirme build.target no YAML com docker compose config, que mostra o arquivo já resolvido. No estágio final, copie apenas o que a aplicação precisa em execução e use uma base enxuta.

Sintoma: erro "failed to compute cache key" ou arquivo não encontrado no COPY --from

Causa: o caminho copiado do estágio anterior não existe, porque o build gerou a saída em outra pasta ou o .dockerignore excluiu algo que o estágio precisa. O nome do estágio em --from também pode estar diferente do declarado em AS.
Solução: confira o nome do estágio e o caminho absoluto dentro dele. Para inspecionar, construa só o estágio de build com docker build --target build -t app:debug . e liste os arquivos com docker run --rm app:debug ls /app.

Sintoma: o binário falha na imagem final com "not found" ou erro de biblioteca

Causa: o binário foi compilado em uma base glibc (Debian, Ubuntu) e executado em Alpine, que usa musl, ou depende de bibliotecas dinâmicas ausentes na imagem final.
Solução: compile no mesmo tipo de base do runtime (por exemplo, estágio de build em Alpine para runtime em Alpine) ou gere binários estáticos quando a linguagem permitir. Além disso, verifique as dependências dinâmicas com ldd no binário gerado e instale ou copie para a imagem final todas as bibliotecas compartilhadas de runtime necessárias; usar a mesma base resolve glibc versus musl, mas não garante que todas as bibliotecas estejam presentes no estágio final.

Sintoma: o disco do VPS enche após vários builds

Causa: imagens antigas e cache do BuildKit se acumulam a cada docker compose build.
Solução: use docker system df para medir e docker image prune e docker builder prune para limpar, depois de conferir o que será removido. Para ajustes de rede, volumes e memória no mesmo host, veja Otimizar Docker Compose no Debian 12: rede, volumes e RAM.

Perguntas frequentes

O que é multi-stage build no Docker?

Multi-stage build é um recurso do Dockerfile que permite usar várias instruções FROM no mesmo arquivo, cada uma iniciando um estágio. Você compila ou instala dependências em um estágio e copia apenas o resultado final para o estágio de runtime com COPY --from, descartando compiladores e arquivos temporários da imagem final.

Como o Docker Compose usa o multi-stage no build?

No docker-compose.yml, a chave build aponta para o contexto e o Dockerfile, e a opção target escolhe qual estágio construir. Ao executar docker compose build, o Compose constrói a imagem até o estágio indicado, o que permite ter um estágio de desenvolvimento e outro de produção no mesmo Dockerfile.

Quanto o multi-stage reduz o tamanho da imagem?

A redução depende da linguagem e das dependências do projeto, e não existe um número fixo. Em aplicações compiladas ou com Node.js, remover compiladores, caches de pacotes e dependências de desenvolvimento costuma diminuir bastante a imagem. Confirme o resultado no seu caso com docker image ls antes e depois.

Posso combinar multi-stage com imagens Alpine ou distroless?

Sim, é uma combinação comum: o estágio de build usa uma imagem completa e o estágio final usa uma base enxuta como Alpine ou distroless. Com Alpine, atenção à biblioteca musl, que pode causar incompatibilidades com binários compilados para glibc, então compile no mesmo tipo de base do runtime quando necessário. Mesmo com bases compatíveis, verifique com ldd se há bibliotecas dinâmicas que precisam ser copiadas ou instaladas no estágio final.

Como limpar imagens antigas depois de refazer o build no VPS?

Execute docker image prune para remover imagens dangling e docker builder prune para limpar o cache de build dangling, após conferir o que será removido. Esses comandos liberam disco no VPS, mas apagam camadas de cache, então o próximo build pode demorar mais. Antes de qualquer limpeza, certifique-se de que imagens de rollback estejam armazenadas em um registro externo ou exportadas com docker image save, pois uma tag local não protege contra docker system prune -a.

Conclusão

  • Separe o Dockerfile em estágios (build, dependências de produção e final) e copie para a imagem final só o que a aplicação usa em execução.
  • Defina build.target no Compose, use .dockerignore e meça o ganho real com docker image ls e docker history.
  • Faça a limpeza periódica com docker image prune e docker builder prune, conferindo antes o que será removido e mantendo imagens de rollback em um registro externo ou exportadas com docker image save.

Leia também

Precisa de ajuda com Docker Compose no VPS?

Rodar builds, imagens e containers com folga de CPU, memória e disco faz diferença no tempo de deploy. Um VPS Linux dimensionado para Docker facilita manter seus ambientes de produção e desenvolvimento no mesmo servidor.

Conheça os planos de VPS


Esta resposta foi útil?