Docker para Node.js: O Setup de Produção Que Ninguém Conta | Akousa

10 de novembro de 202526 min de leitura

Docker para Node.js: O Setup de Produção Que Ninguém Conta

Multi-stage builds, usuários non-root, health checks, gestão de secrets e otimização de tamanho de imagem. Os padrões Docker que uso em todo deploy Node.js de produção.

A maioria dos Dockerfiles de Node.js em produção são ruins. Não "ligeiramente subótimos" ruins. Quero dizer rodando como root, entregando imagens de 600MB com devDependencies embutidas, sem health checks, e secrets hardcoded em variáveis de ambiente que qualquer pessoa com docker inspect pode ler.

Eu sei porque fui eu que escrevi esses Dockerfiles. Por anos. Funcionavam, então nunca questionei. Até que um dia uma auditoria de segurança sinalizou nosso container rodando como PID 1 root com acesso de escrita ao sistema de arquivos inteiro, e percebi que "funciona" e "pronto para produção" são patamares muito diferentes.

This setup is a production-tested baseline for Node.js services. Every pattern here exists because the weaker alternative tends to fail under real traffic.

Por Que Seu Dockerfile Atual Provavelmente Está Errado

Deixa eu adivinhar como é o seu Dockerfile:

dockerfile

# Estágio único: ~600MB
FROM node:20
WORKDIR /app
COPY . .
RUN npm install
CMD ["node", "server.js"]
 
# Multi-stage: ~150MB
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
 
FROM node:20-alpine AS runner
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./
CMD ["node", "dist/server.js"]

Abordagem	Tamanho da Imagem
`node:20` + `npm install`	1.1 GB
`node:20-slim` + `npm install`	420 MB
`node:20-alpine` + `npm ci`	280 MB
Multi-stage + alpine + apenas deps de produção	150 MB
Multi-stage + alpine + deps podadas	95 MB

dockerfile

# ============================================
# Estágio 1: Instalar dependências
# ============================================
FROM node:20-alpine AS deps
 
# Segurança: criar diretório de trabalho antes de qualquer coisa
WORKDIR /app
 
# Instalar dependências baseado no lockfile
# Copiar APENAS arquivos de pacote primeiro — isso é crítico para cache de camadas
COPY package.json package-lock.json ./
 
# ci é melhor que install: é mais rápido, estrito e reproduzível
# --omit=dev exclui devDependencies deste estágio
RUN npm ci --omit=dev
 
# ============================================
# Estágio 2: Compilar a aplicação
# ============================================
FROM node:20-alpine AS builder
 
WORKDIR /app
 
# Copiar arquivos de pacote e instalar TODAS as dependências (incluindo dev)
COPY package.json package-lock.json ./
RUN npm ci
 
# AGORA copiar código fonte — mudanças aqui não invalidam o cache do npm ci
COPY . .
 
# Compilar a aplicação (TypeScript compile, Next.js build, etc.)
RUN npm run build
 
# ============================================
# Estágio 3: Runner de produção
# ============================================
FROM node:20-alpine AS runner
 
# Adicionar labels para metadados da imagem
LABEL maintainer="your-email@example.com"
LABEL org.opencontainers.image.source="https://github.com/yourorg/yourrepo"
 
# Segurança: instalar dumb-init para tratamento adequado de sinais PID 1
RUN apk add --no-cache dumb-init
 
# Segurança: definir NODE_ENV antes de qualquer coisa
ENV NODE_ENV=production
 
# Segurança: usar usuário non-root
# A imagem node já inclui um usuário 'node' (uid 1000)
USER node
 
# Criar diretório da app com propriedade do usuário node
WORKDIR /app
 
# Copiar dependências de produção do estágio deps
COPY --from=deps --chown=node:node /app/node_modules ./node_modules
 
# Copiar aplicação compilada do estágio builder
COPY --from=deps --chown=node:node /app/package.json ./
COPY --from=builder --chown=node:node /app/dist ./dist
 
# Expor a porta (apenas documentação — não publica)
EXPOSE 3000
 
# Health check: curl não está disponível no alpine, usar node
HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
  CMD node -e "require('http').get('http://localhost:3000/health', (r) => { process.exit(r.statusCode === 200 ? 0 : 1) })"
 
# Usar dumb-init como PID 1 para tratar sinais adequadamente
ENTRYPOINT ["dumb-init", "--"]
 
# Iniciar a aplicação
CMD ["node", "dist/server.js"]

javascript

// server.js
const server = app.listen(3000);
 
process.on("SIGTERM", () => {
  console.log("SIGTERM recebido, encerrando graciosamente");
  server.close(() => {
    console.log("Servidor HTTP fechado");
    // Fechar conexões de banco, flush de logs, etc.
    process.exit(0);
  });
});

# .dockerignore
node_modules
npm-debug.log*
.git
.gitignore
.env
.env.*
!.env.example
Dockerfile
docker-compose*.yml
.dockerignore
README.md
LICENSE
.github
.vscode
.idea
coverage
.nyc_output
*.test.ts
*.test.js
*.spec.ts
*.spec.js
__tests__
test
tests
docs
.husky
.eslintrc*
.prettierrc*
tsconfig.json
jest.config.*
vitest.config.*

dockerfile

# syntax=docker/dockerfile:1
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
 
# Montar o secret em tempo de build — nunca é armazenado na imagem
RUN --mount=type=secret,id=npmrc,target=/app/.npmrc \
    npm ci
 
COPY . .
RUN npm run build

yaml

# docker-compose.yml (modo Swarm)
version: "3.8"
services:
  api:
    image: myapp:latest
    secrets:
      - db_password
      - api_key
 
secrets:
  db_password:
    external: true
  api_key:
    external: true

javascript

import { readFileSync } from "fs";
 
function getSecret(name) {
  try {
    return readFileSync(`/run/secrets/${name}`, "utf8").trim();
  } catch {
    // Fallback para variável de ambiente para desenvolvimento local
    return process.env[name.toUpperCase()];
  }
}
 
const dbPassword = getSecret("db_password");

dockerfile

HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
  CMD node -e "require('http').get('http://localhost:3000/health', (r) => { process.exit(r.statusCode === 200 ? 0 : 1) })"

javascript

// healthcheck.js
const http = require("http");
 
const options = {
  hostname: "localhost",
  port: 3000,
  path: "/health",
  timeout: 5000,
};
 
const req = http.request(options, (res) => {
  process.exit(res.statusCode === 200 ? 0 : 1);
});
 
req.on("error", () => process.exit(1));
req.on("timeout", () => {
  req.destroy();
  process.exit(1);
});
 
req.end();

javascript

app.get("/health", async (req, res) => {
  const checks = {
    uptime: process.uptime(),
    timestamp: Date.now(),
    status: "ok",
  };
 
  try {
    // Verificar conexão com banco de dados
    await db.query("SELECT 1");
    checks.database = "connected";
  } catch (err) {
    checks.database = "disconnected";
    checks.status = "degraded";
  }
 
  try {
    // Verificar conexão Redis
    await redis.ping();
    checks.redis = "connected";
  } catch (err) {
    checks.redis = "disconnected";
    checks.status = "degraded";
  }
 
  const statusCode = checks.status === "ok" ? 200 : 503;
  res.status(statusCode).json(checks);
});

yaml

# docker-compose.dev.yml
services:
  app:
    build:
      context: .
      dockerfile: Dockerfile.dev
      args:
        NODE_VERSION: "20"
    ports:
      - "3000:3000"
      - "9229:9229" # Debugger Node.js
    volumes:
      # Montar código fonte para hot reload
      - .:/app
      # Volume anônimo para preservar node_modules da imagem
      # Impede que o node_modules do host sobreponha o do container
      - /app/node_modules
    environment:
      - NODE_ENV=development
      - DATABASE_URL=postgres://postgres:devpassword@db:5432/myapp_dev
      - REDIS_URL=redis://redis:6379
    env_file:
      - .env.local
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
    command: npm run dev
 
  db:
    image: postgres:16-alpine
    ports:
      - "5432:5432"
    environment:
      POSTGRES_DB: myapp_dev
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: devpassword
    volumes:
      # Volume nomeado para dados persistentes entre reinícios de container
      - pgdata:/var/lib/postgresql/data
      # Scripts de inicialização
      - ./scripts/init-db.sql:/docker-entrypoint-initdb.d/init.sql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
 
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redisdata:/data
    command: redis-server --appendonly yes
 
  # Opcional: UI de admin do banco de dados
  adminer:
    image: adminer:latest
    ports:
      - "8080:8080"
    depends_on:
      - db
 
volumes:
  pgdata:
  redisdata:

dockerfile

# Dockerfile.dev
ARG NODE_VERSION=20
FROM node:${NODE_VERSION}-alpine
 
WORKDIR /app
 
# Instalar todas as dependências (incluindo devDependencies)
COPY package*.json ./
RUN npm ci
 
# Código fonte é montado via volume, não copiado
# Mas ainda precisamos dele para o build inicial
COPY . .
 
EXPOSE 3000 9229
 
CMD ["npm", "run", "dev"]

yaml

# docker-compose.prod.yml
services:
  app:
    image: ghcr.io/yourorg/myapp:${TAG:-latest}
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
    env_file:
      - .env.production
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 512M
        reservations:
          cpus: "0.25"
          memory: 128M
      replicas: 2
    healthcheck:
      test:
        [
          "CMD",
          "node",
          "-e",
          "require('http').get('http://localhost:3000/health', r => process.exit(r.statusCode === 200 ? 0 : 1))",
        ]
      interval: 30s
      timeout: 10s
      start_period: 40s
      retries: 3
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
    networks:
      - internal
      - web
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
 
  db:
    image: postgres:16-alpine
    restart: unless-stopped
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: myapp
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 1G
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${DB_USER}"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - internal
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
 
  redis:
    image: redis:7-alpine
    restart: unless-stopped
    command: >
      redis-server
      --appendonly yes
      --maxmemory 256mb
      --maxmemory-policy allkeys-lru
    volumes:
      - redisdata:/data
    deploy:
      resources:
        limits:
          cpus: "0.5"
          memory: 512M
    networks:
      - internal
    logging:
      driver: "json-file"
      options:
        max-size: "5m"
        max-file: "3"
 
volumes:
  pgdata:
    driver: local
  redisdata:
    driver: local
 
networks:
  internal:
    driver: bridge
  web:
    external: true

dockerfile

# ============================================
# Estágio 1: Instalar dependências
# ============================================
FROM node:20-alpine AS deps
RUN apk add --no-cache libc6-compat
WORKDIR /app
 
COPY package.json package-lock.json ./
RUN npm ci
 
# ============================================
# Estágio 2: Compilar a aplicação
# ============================================
FROM node:20-alpine AS builder
WORKDIR /app
 
COPY --from=deps /app/node_modules ./node_modules
COPY . .
 
# Desabilitar telemetria do Next.js durante o build
ENV NEXT_TELEMETRY_DISABLED=1
 
RUN npm run build
 
# ============================================
# Estágio 3: Runner de produção
# ============================================
FROM node:20-alpine AS runner
WORKDIR /app
 
RUN apk add --no-cache dumb-init
 
ENV NODE_ENV=production
ENV NEXT_TELEMETRY_DISABLED=1
 
# Usuário non-root
RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs
 
# Copiar assets públicos
COPY --from=builder /app/public ./public
 
# Configurar o diretório de output standalone
# Aproveita automaticamente output traces para reduzir tamanho da imagem
# https://nextjs.org/docs/advanced-features/output-file-tracing
RUN mkdir .next
RUN chown nextjs:nodejs .next
 
# Copiar o servidor standalone e arquivos estáticos
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
 
USER nextjs
 
EXPOSE 3000
 
ENV PORT=3000
ENV HOSTNAME="0.0.0.0"
 
HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
  CMD node -e "require('http').get('http://localhost:3000/api/health', (r) => { process.exit(r.statusCode === 200 ? 0 : 1) })"
 
ENTRYPOINT ["dumb-init", "--"]
CMD ["node", "server.js"]

myapp:latest (alpine 3.19.1)
=============================
Total: 0 (UNKNOWN: 0, LOW: 0, MEDIUM: 0, HIGH: 0, CRITICAL: 0)

Node.js (node_modules/package-lock.json)
=========================================
Total: 2 (UNKNOWN: 0, LOW: 0, MEDIUM: 1, HIGH: 1, CRITICAL: 0)

┌──────────────┬────────────────┬──────────┬────────┬───────────────┐
│   Library    │ Vulnerability  │ Severity │ Status │ Fixed Version │
├──────────────┼────────────────┼──────────┼────────┼───────────────┤
│ semver       │ CVE-2022-25883 │ HIGH     │ fixed  │ 7.5.4         │
│ word-wrap    │ CVE-2023-26115 │ MEDIUM   │ fixed  │ 1.2.4         │
└──────────────┴────────────────┴──────────┴────────┴───────────────┘

yaml

# .github/workflows/docker.yml
- name: Build image
  run: docker build -t myapp:${{ github.sha }} .
 
- name: Scan image
  uses: aquasecurity/trivy-action@master
  with:
    image-ref: myapp:${{ github.sha }}
    exit-code: 1
    severity: CRITICAL,HIGH
    ignore-unfixed: true

yaml

# .github/workflows/docker.yml
name: Build and Push Docker Image
 
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
 
env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}
 
jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
      security-events: write
 
    steps:
      - name: Checkout
        uses: actions/checkout@v4
 
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
 
      - name: Log in to Container Registry
        if: github.event_name != 'pull_request'
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
 
      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          tags: |
            type=sha
            type=ref,event=branch
            type=semver,pattern={{version}}
 
      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          context: .
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max
 
      - name: Scan image with Trivy
        uses: aquasecurity/trivy-action@master
        with:
          image-ref: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:sha-${{ github.sha }}
          exit-code: 1
          severity: CRITICAL,HIGH
          ignore-unfixed: true
 
      - name: Upload Trivy results
        if: always()
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: trivy-results.sarif

dockerfile

# Configuração em tempo de build
ARG NODE_VERSION=20
FROM node:${NODE_VERSION}-alpine
 
# Configuração em runtime
ENV PORT=3000
 
# ERRADO: Isso torna o secret visível na imagem
ARG API_KEY
ENV API_KEY=${API_KEY}
 
# CORRETO: Passe secrets em runtime
# docker run -e API_KEY=secret myapp

yaml

# docker-compose.monitoring.yml
services:
  prometheus:
    image: prom/prometheus:latest
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
      - prometheus_data:/prometheus
    ports:
      - "9090:9090"
    networks:
      - internal
 
  grafana:
    image: grafana/grafana:latest
    volumes:
      - grafana_data:/var/lib/grafana
    ports:
      - "3001:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_PASSWORD}
    networks:
      - internal
 
volumes:
  prometheus_data:
  grafana_data:

javascript

import { collectDefaultMetrics, Registry, Histogram } from "prom-client";
 
const register = new Registry();
collectDefaultMetrics({ register });
 
const httpRequestDuration = new Histogram({
  name: "http_request_duration_seconds",
  help: "Duração de requisições HTTP em segundos",
  labelNames: ["method", "route", "status_code"],
  buckets: [0.01, 0.05, 0.1, 0.5, 1, 5],
  registers: [register],
});
 
// Middleware
app.use((req, res, next) => {
  const end = httpRequestDuration.startTimer();
  res.on("finish", () => {
    end({ method: req.method, route: req.route?.path || req.path, status_code: res.statusCode });
  });
  next();
});
 
// Endpoint de métricas
app.get("/metrics", async (req, res) => {
  res.set("Content-Type", register.contentType);
  res.end(await register.metrics());
});

Abordagem	Tamanho da Imagem
`node:20` + `node_modules` completo + `.next`	1.4 GB
`node:20-alpine` + `node_modules` completo + `.next`	600 MB
`node:20-alpine` + output standalone	120 MB

Por Que Seu Dockerfile Atual Provavelmente Está Errado

Rodando como Root

Instalando devDependencies em Produção

Copiando Tudo

Sem Health Checks

Sem Estratégia de Cache de Camadas

Multi-Stage Builds: O Maior Ganho

Comparações Reais de Tamanho

Por Que Alpine?

O Dockerfile de Produção Completo

Por Que Três Estágios em Vez de Dois?

Por Que dumb-init?

O Arquivo .dockerignore

Cache de Camadas: Pare de Esperar 3 Minutos Por Build

A Ordem Errada

A Ordem Correta

Cache Mount para npm

Usando ARG para Cache Busting

Gestão de Secrets: Pare de Colocar Secrets no Seu Dockerfile

Os Três Níveis de Secrets

Arquivos .env e Docker

Health Checks: Deixe o Docker Saber Que Sua App Realmente Funciona

A Instrução HEALTHCHECK

Por Que Não Usar curl?

O Endpoint de Health

Por Que Health Checks Importam para Orquestradores

docker-compose para Desenvolvimento

Padrões Chave de Desenvolvimento

O Dockerfile de Desenvolvimento

Docker Compose de Produção

O Que é Diferente do Desenvolvimento

Next.js Específico: O Output Standalone

O Dockerfile de Produção Next.js

Comparação de Tamanho para Next.js

Tratamento de Arquivos Estáticos

Sharp para Otimização de Imagens

Scan de Imagens e Segurança

Trivy: Escaneie Suas Imagens

Sistema de Arquivos Somente Leitura

Remover Todas as Capabilities

Fixar o Digest da Imagem Base

Integração CI/CD: Juntando Tudo

Cache BuildKit no CI

Armadilhas Comuns e Como Evitá-las

O Conflito node_modules Dentro da Imagem vs Host

Tratamento de SIGTERM em Projetos TypeScript

Limites de Memória e Node.js

Problemas de Fuso Horário

Build Arguments vs Variáveis de Ambiente

Monitoramento em Produção

O Checklist

Posts Relacionados

Monorepos in 2026: Nx, Turborepo, and the Lessons Nobody Shares

YAML Validator Guide: Catch Config Errors Before Deploy