Entenda Docker Compose build sem cache no CentOS 9

16 min de leitura  ·  Guia técnico

Docker Compose build sem cache é o processo de reconstrução de imagens Docker ignorando completamente as camadas armazenadas localmente, garantindo que cada instrução do Dockerfile seja executada do zero. Para realizar um build limpo no CentOS 9, siga estes passos:

1. Instale o Docker Engine e o plugin Docker Compose no CentOS 9
2. Crie ou ajuste seu arquivo docker-compose.yml com os serviços desejados
3. Execute docker compose build --no-cache para reconstruir todas as imagens
4. Para reconstruir apenas um serviço, use docker compose build --no-cache nome_do_servico
5. Suba os containers com docker compose up -d após o build
6. Verifique os logs com docker compose logs -f para confirmar o funcionamento

Pré-requisitos para usar Docker Compose build sem cache no CentOS 9

• CentOS 9 Stream instalado e atualizado (dnf update -y)
• Acesso root ou usuário com privilégios sudo via SSH
• Docker Engine versão 24 ou superior instalado
• Plugin docker-compose-plugin instalado (substitui o binário legado docker-compose)
• Pelo menos 2 GB de RAM disponível e espaço em disco suficiente para as imagens
• Arquivo docker-compose.yml válido com pelo menos um serviço com diretiva build
• Conexão com a internet para baixar imagens base e pacotes durante o rebuild

Como instalar o Docker Engine e o plugin Compose no CentOS 9

O Docker Compose build sem cache depende do plugin oficial docker-compose-plugin, que substitui o binário legado. No CentOS 9 Stream, o repositório oficial do Docker é a fonte recomendada para garantir versões atualizadas e compatíveis.

Primeiro, remova versões antigas e adicione o repositório oficial:

sudo dnf remove -y docker docker-client docker-client-latest \
  docker-common docker-latest docker-latest-logrotate \
  docker-logrotate docker-engine

sudo dnf install -y dnf-plugins-core

sudo dnf config-manager --add-repo \
  https://download.docker.com/linux/centos/docker-ce.repo

Em seguida, instale o Docker Engine e o plugin Compose:

sudo dnf install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

Ative e inicie o serviço Docker:

sudo systemctl enable --now docker

Verifique se a instalação foi bem-sucedida:

docker --version
docker compose version

Docker version 26.1.4, build 5650f9b
Docker Compose version v2.27.1

Se quiser executar o Docker sem sudo, adicione seu usuário ao grupo docker:

sudo usermod -aG docker $USER
newgrp docker

Para servidores em produção, consulte o artigo Acessando servidores VPS Linux da AviraHost para garantir que o acesso SSH esteja configurado corretamente antes de prosseguir.

Estrutura do docker-compose.yml com diretiva build

Para que o comando docker compose build --no-cache funcione, o arquivo docker-compose.yml precisa conter a diretiva build apontando para o contexto do Dockerfile. Sem ela, o Compose apenas baixa imagens prontas e não há nada para reconstruir.

Exemplo de estrutura completa com dois serviços — uma aplicação web e um banco de dados:

version: "3.9"

services:
  web:
    build:
      context: ./app
      dockerfile: Dockerfile
    ports:
      - "8080:80"
    environment:
      - APP_ENV=production
    depends_on:
      - db

  db:
    image: mariadb:11.4
    environment:
      MYSQL_ROOT_PASSWORD: senhaforte
      MYSQL_DATABASE: meuapp
    volumes:
      - db_data:/var/lib/mysql

volumes:
  db_data:

Neste exemplo, apenas o serviço web possui diretiva build. O serviço db usa uma imagem pré-construída do MariaDB 11.4 e não será afetado pelo --no-cache. O contexto ./app indica que o Dockerfile está dentro do diretório app relativo ao docker-compose.yml.

Um Dockerfile simples para o serviço web poderia ser:

FROM nginx:1.26-alpine

COPY ./html /usr/share/nginx/html

RUN apk add --no-cache curl

EXPOSE 80

A instrução RUN apk add --no-cache curl dentro do Dockerfile usa o flag --no-cache do gerenciador de pacotes Alpine — isso é diferente do --no-cache do Docker Compose e serve apenas para não armazenar o índice de pacotes dentro da imagem final.

Executando docker compose build --no-cache: passo a passo detalhado

Com o ambiente configurado, o processo de rebuild sem cache no Docker Compose é direto. Navegue até o diretório que contém o docker-compose.yml e execute os comandos abaixo.

Para reconstruir todos os serviços que possuem diretiva build:

docker compose build --no-cache

Ao rodar este comando, você verá cada etapa do Dockerfile sendo executada novamente, com o prefixo # indicando o número da camada:

[+] Building 45.3s (8/8) FINISHED
 => [web internal] load build definition from Dockerfile          0.1s
 => [web internal] load .dockerignore                             0.1s
 => [web 1/4] FROM docker.io/library/nginx:1.26-alpine            8.2s
 => [web 2/4] COPY ./html /usr/share/nginx/html                   0.3s
 => [web 3/4] RUN apk add --no-cache curl                        12.4s
 => [web 4/4] EXPOSE 80                                           0.0s
 => [web] exporting to image                                       1.1s
 => [web] naming to docker.io/library/app_web:latest              0.0s

Para reconstruir apenas o serviço web sem afetar os demais:

docker compose build --no-cache web

Após o build, suba os containers:

docker compose up -d

[+] Running 2/2
 ✔ Container app-db-1   Started
 ✔ Container app-web-1  Started

Verifique se os containers estão rodando corretamente:

docker compose ps

NAME          IMAGE        COMMAND                  SERVICE   STATUS    PORTS
app-db-1      mariadb:11.4 "docker-entrypoint.s…"  db        running   3306/tcp
app-web-1     app-web      "/docker-entrypoint.…"  web       running   0.0.0.0:8080->80/tcp

Para acompanhar os logs em tempo real e confirmar que a aplicação iniciou sem erros:

docker compose logs -f web

Combinando --no-cache com outras flags úteis do Docker Compose

O rebuild forçado de containers Docker pode ser combinado com outras opções para otimizar ainda mais o fluxo de trabalho em ambientes de produção e CI/CD no CentOS 9.

Para reconstruir e subir os containers em um único comando, use --build junto com up. Porém, esta combinação não aceita --no-cache diretamente — é necessário separar os passos:

docker compose build --no-cache
docker compose up -d --force-recreate

A flag --force-recreate garante que os containers sejam recriados mesmo que a configuração não tenha mudado, útil quando variáveis de ambiente foram alteradas.

Para remover imagens intermediárias geradas durante o build e liberar espaço:

docker compose build --no-cache --pull

A flag --pull força o download da versão mais recente da imagem base declarada no FROM, mesmo que já exista localmente. Isso é especialmente útil ao atualizar de nginx:1.26-alpine para uma versão mais nova.

Para pipelines de CI/CD, uma sequência robusta seria:

docker compose pull
docker compose build --no-cache --pull
docker compose up -d --force-recreate --remove-orphans

A flag --remove-orphans remove containers de serviços que foram removidos do docker-compose.yml, mantendo o ambiente limpo.

Veja também as Dicas de Otimização de Servidores Linux para ajustar os recursos do host antes de executar builds pesados.

Gerenciando o cache do Docker para builds eficientes

Entender como o cache de camadas do Docker funciona ajuda a decidir quando usar --no-cache e quando preservá-lo. O Docker armazena cada instrução do Dockerfile como uma camada imutável. Se uma camada não mudou desde o último build, ela é reutilizada, acelerando o processo.

Para visualizar o espaço ocupado pelo cache de build:

docker system df

TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          12        3         4.21GB    3.1GB (73%)
Containers      3         3         2.5MB     0B (0%)
Local Volumes   2         1         512MB     256MB (50%)
Build Cache     47        0         1.8GB     1.8GB

Para limpar apenas o cache de build sem remover imagens ou containers:

docker builder prune

Atenção: o comando abaixo remove todo o cache de build sem confirmação adicional. Use com cautela em ambientes compartilhados:

docker builder prune -f

Para remover imagens não utilizadas e liberar espaço em disco sem afetar containers ativos:

docker image prune -a

A diferença entre docker compose build --no-cache e docker system prune é fundamental: o primeiro reconstrói ignorando o cache mas não apaga nada do disco, enquanto o segundo remove recursos não utilizados para liberar espaço. Use cada um para o propósito correto.

Uma boa prática é organizar o Dockerfile para que as camadas que mudam com menos frequência fiquem no topo. Por exemplo, instale dependências do sistema antes de copiar o código da aplicação:

FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY . .

EXPOSE 3000
CMD ["node", "server.js"]

Com esta estrutura, o npm ci só será reexecutado quando o package.json mudar, não a cada alteração no código-fonte. Isso reduz drasticamente o tempo de build no dia a dia, reservando o --no-cache para situações específicas.

Problemas comuns e como resolver

Sintoma: build falha com "permission denied" ao acessar o contexto

Causa: O daemon Docker não tem permissão para ler os arquivos no diretório de contexto definido em context: no docker-compose.yml. Isso ocorre frequentemente quando o diretório pertence a outro usuário ou tem permissões restritivas.
Solução: Verifique as permissões do diretório e ajuste conforme necessário. Execute ls -la ./app para inspecionar. Se necessário, corrija com chmod -R 755 ./app e chown -R $USER:$USER ./app. Certifique-se também de que o usuário que executa o Docker pertence ao grupo docker.

Sintoma: --no-cache não parece ter efeito, imagem continua desatualizada

Causa: O container em execução ainda usa a imagem antiga. O --no-cache reconstrói a imagem, mas não recria automaticamente os containers que já estão rodando com a versão anterior.
Solução: Após o build, force a recriação dos containers com docker compose up -d --force-recreate. Verifique qual imagem o container está usando com docker inspect app-web-1 | grep Image e confirme que o hash corresponde à imagem recém-construída.

Sintoma: erro "no space left on device" durante o build

Causa: O disco do servidor está cheio, frequentemente por acúmulo de imagens antigas, camadas de build e volumes não utilizados. Builds sem cache são especialmente suscetíveis pois geram novas camadas sem reutilizar as existentes.
Solução: Execute docker system df para identificar o que ocupa mais espaço. Limpe recursos não utilizados com docker system prune -a --volumes. Atenção: esta operação remove todos os containers parados, imagens sem uso e volumes não associados a containers ativos. Faça backup dos dados importantes antes.

Sintoma: docker compose build --no-cache ignora o .dockerignore

Causa: O arquivo .dockerignore não está no mesmo diretório que o docker-compose.yml ou no diretório de contexto definido. O Docker procura o .dockerignore na raiz do contexto de build, não necessariamente onde o Compose é executado.
Solução: Certifique-se de que o .dockerignore está dentro do diretório especificado em context:. Verifique com ls -la ./app/.dockerignore. Um .dockerignore bem configurado exclui node_modules, .git, arquivos de log e outros recursos desnecessários, reduzindo o contexto enviado ao daemon.

Sintoma: serviço com imagem pré-construída é reconstruído desnecessariamente

Causa: O docker compose build --no-cache sem especificar o nome do serviço tenta reconstruir todos os serviços, incluindo aqueles que usam apenas image: sem build:. O Compose ignora silenciosamente esses serviços, mas pode gerar confusão nos logs.
Solução: Especifique sempre o nome do serviço quando quiser reconstruir apenas parte da stack: docker compose build --no-cache web. Para verificar quais serviços possuem diretiva build, execute docker compose config | grep -A3 "build:".

Perguntas frequentes sobre Docker Compose build sem cache

O que faz o --no-cache no Docker Compose build?

A flag --no-cache instrui o Docker a ignorar todas as camadas armazenadas em cache durante o processo de build. Isso força o download e a execução de cada instrução do Dockerfile do zero, garantindo que a imagem final reflita o estado atual do código e das dependências, sem resíduos de builds anteriores. É especialmente útil quando uma dependência foi atualizada no repositório remoto mas o cache local ainda serve a versão antiga.

Quando devo usar docker compose build --no-cache?

Use --no-cache quando suspeitar que o cache está servindo uma versão desatualizada de uma dependência, após alterar variáveis de ambiente no Dockerfile, ao atualizar a imagem base (FROM), ou em pipelines de CI/CD onde a reprodutibilidade é obrigatória. Em desenvolvimento local cotidiano, o cache acelera o fluxo e pode ser mantido. Reserve o rebuild completo para situações de depuração, releases e atualizações de segurança.

Qual a diferença entre docker compose build --no-cache e docker system prune?

O comando docker compose build --no-cache reconstrói as imagens ignorando o cache, mas não remove nada do disco. Já o docker system prune remove imagens pendentes, containers parados, redes não utilizadas e, com a flag -a, todas as imagens sem container ativo. Use --no-cache para rebuild limpo e prune para liberar espaço em disco. Os dois comandos têm propósitos complementares e podem ser usados em sequência.

Como forçar o rebuild de apenas um serviço no Docker Compose?

Execute docker compose build --no-cache nome_do_servico, substituindo nome_do_servico pelo nome definido no docker-compose.yml. Isso reconstrói somente aquele serviço sem afetar os demais, economizando tempo quando apenas uma parte da stack foi alterada. Após o build, recrie apenas aquele container com docker compose up -d --force-recreate nome_do_servico.

O build sem cache deixa o processo mais lento?

Sim, builds sem cache são significativamente mais lentos porque cada camada do Dockerfile é executada novamente, incluindo downloads de pacotes e compilações. Em ambientes de produção e CI/CD isso é aceitável pela garantia de consistência. Para desenvolvimento local, prefira usar o cache e reservar --no-cache para situações específicas de depuração ou release. Organizar bem o Dockerfile com camadas estáveis no topo minimiza o impacto mesmo quando o cache é usado.

Conclusão

• Use --no-cache estrategicamente: em pipelines de CI/CD, ao atualizar imagens base e ao suspeitar de dependências desatualizadas — não em todo build de desenvolvimento local.
• Combine com --force-recreate: reconstruir a imagem sem recriar o container não aplica as mudanças; sempre execute docker compose up -d --force-recreate após um rebuild sem cache.
• Mantenha o disco saudável: monitore o espaço com docker system df regularmente e use docker builder prune para limpar o cache de build sem remover imagens ativas.

Leia também

• Comparativo: Portainer vs Rancher para Docker em VPS 2026
• Entenda Docker no Ubuntu 24.04: instale e configure do zero
• Entenda o que é Docker: como funciona e quando usar

Precisa de ajuda com Docker e containers no seu servidor?

Configurar e manter ambientes Docker em produção exige um servidor com recursos adequados e suporte técnico disponível. Um VPS Linux com CentOS 9 bem dimensionado garante que seus builds e containers rodem com estabilidade e desempenho consistentes.

Conheça os planos de VPS da AviraHost e escolha o ideal para seu ambiente Docker