Noções Básicas de Docker

10 exemplos para containerizar uma API Node.js TypeScript em Node 24 LTS - 7 básicos e 3 intermediários.

Pré-requisitos

mkdir node-api && cd node-api
npm init -y
npm pkg set type=module
npm install express@5
npm install -D typescript@5.6 tsx @types/express @types/node

Para padrões multi-estágio e hardening de imagem, veja Builds Multi-Estágio e Contêineres Não-Root.

Exemplos Básicos

1. Dockerfile Mínimo

FROM node:24-bookworm-slim
 
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY dist ./dist
 
ENV NODE_ENV=production
USER node
EXPOSE 3000
CMD ["node", "dist/main.js"]

• npm ci usa o lockfile para instalações reproduzíveis
• Copie package*.json antes do código fonte para que as camadas de dependência sejam bem cacheadas
• USER node executa o processo sem privilégios de root

2. .dockerignore

node_modules
dist
.git
.env
.env.*
*.md
coverage
.vscode
Dockerfile*
docker-compose*.yml

• Contexto de build menor significa docker build mais rápido
• Nunca copie .env para uma camada de imagem
• Ignore artefatos de teste e documentação que você não precisa em runtime

3. Compile TypeScript em CI, Execute JS na Imagem

FROM node:24-bookworm-slim AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY tsconfig.json ./
COPY src ./src
RUN npm run build
 
FROM node:24-bookworm-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY --from=build /app/dist ./dist
USER node
CMD ["node", "dist/main.js"]

• Compile TypeScript em um estágio de build ou em CI antes do docker build
• A imagem de runtime contém apenas dist/ e node_modules de produção
• Veja Builds Multi-Estágio para padrões mais aprofundados

4. PORT do Ambiente

import express from "express";
 
const app = express();
const port = Number(process.env.PORT ?? 3000);
 
app.get("/health", (_req, res) => {
  res.json({ status: "ok" });
});
 
app.listen(port, "0.0.0.0", () => {
  console.log(`listening on ${port}`);
});

• Vincule a 0.0.0.0 dentro de contêineres, não a 127.0.0.1
• Kubernetes, ECS e Cloud Run injetam PORT
• O endpoint de health é necessário para verificações do load balancer

5. docker build e docker run

docker build -t my-api:local .
docker run --rm -p 3000:3000 -e PORT=3000 my-api:local
curl http://localhost:3000/health

• -p 3000:3000 mapeia a porta do host para a porta do contêiner
• --rm remove o contêiner após a saída (bom para testes rápidos locais)
• Passe segredos via -e localmente; use um gerenciador de segredos em produção

6. Scripts package.json para Docker

{
  "scripts": {
    "build": "tsc",
    "start": "node dist/main.js",
    "docker:build": "docker build -t my-api:local .",
    "docker:run": "docker run --rm -p 3000:3000 -e PORT=3000 my-api:local"
  }
}

• Um comando para a equipe construir e testar localmente
• CI pode chamar npm run docker:build após os testes passarem
• Mantenha start como node simples, não tsx, em imagens de produção

7. HEALTHCHECK no Dockerfile

HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
  CMD node -e "fetch('http://127.0.0.1:' + (process.env.PORT||3000) + '/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"

• Docker marca contêineres não saudáveis para políticas de reinício
• Orquestradores (K8s) preferem suas próprias sondas em vez de HEALTHCHECK
• Mantenha /health rápido: sem chamadas de banco de dados (use /ready para isso)

Exemplos Intermediários

8. Multi-Estágio com Alvos Dev e Prod

FROM node:24-bookworm-slim AS base
WORKDIR /app
COPY package*.json ./
 
FROM base AS dev
RUN npm ci
COPY . .
CMD ["npx", "tsx", "watch", "src/main.ts"]
 
FROM base AS prod
RUN npm ci --omit=dev
COPY dist ./dist
USER node
CMD ["node", "dist/main.js"]

docker build --target dev -t my-api:dev .
docker build --target prod -t my-api:prod .

• Um único Dockerfile serve para desenvolvimento local (tsx watch) e produção
• --target seleciona o estágio final
• O alvo de desenvolvimento pode incluir devDependencies; o de produção não

9. docker compose para Stack Local

# compose.yml
services:
  api:
    build: .
    ports:
      - "3000:3000"
    environment:
      NODE_ENV: development
      PORT: 3000
      DATABASE_URL: postgres://postgres:postgres@db:5432/app
    depends_on:
      db:
        condition: service_healthy
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_PASSWORD: postgres
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 3s
      retries: 5

• depends_on com condition: service_healthy evita race conditions na inicialização
• Compose é para desenvolvimento local; produção usa K8s ou plataformas gerenciadas
• Veja Sondas de Health & Readiness

10. Fixar Imagem Base por Digest

FROM node:24-bookworm-slim@sha256:abc123def456...

• Digests evitam reconstruções surpresa quando uma tag muda
• Renovate ou Dependabot podem abrir PRs quando imagens base são atualizadas
• Combine com escaneamento de imagem em CI - Melhores Práticas Docker

FAQs

Relacionados

• Builds Multi-Estágio - devDependencies fora da produção
• Contêineres Não-Root - padrões USER node
• Sondas de Health & Readiness - /health vs /ready
• Otimização de Imagem - camadas menores
• Melhores Práticas Docker - checklist da seção

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.