Docker para desenvolvedores: do zero ao primeiro deploy em 2026

Docker virou requisito de fato em vaga back-end e full-stack desde ~2018, mas continua sendo o tópico que mais trava iniciante. O motivo é simples: a maioria dos tutoriais salta da motivação direto para Kubernetes. Aqui vamos do conceito (o que diabos é um container) até o seu primeiro deploy reproduzível, passando só pelo que realmente importa.

O que é um container, sem mística

Um container é um processo do sistema operacional isolado em três coisas: sistema de arquivos próprio, rede própria e visão própria de outros processos. Não é uma máquina virtual — não tem kernel próprio, não roda um SO inteiro. É o seu Linux compartilhando o kernel do host, usando recursos do kernel (namespaces e cgroups) para fingir que está sozinho.

Instalando

Em Linux, instale o Docker Engine oficial (apt/dnf) — evite o pacote da distro, costuma ser velho. Em macOS e Windows, use o Docker Desktop (gratuito para uso pessoal e empresas com menos de 250 funcionários ou US$ 10 mi de receita; pago acima disso). Em Windows, ative WSL2 antes.

# verificar instalação
docker --version
docker run hello-world

# rodar um nginx temporário
docker run --rm -p 8080:80 nginx:alpine
# acesse http://localhost:8080 e Ctrl+C para parar

Imagem x container x volume

• Imagem: receita imutável, em camadas. Análogo a uma classe.
• Container: instância em execução de uma imagem. Análogo a um objeto.
• Volume: armazenamento persistente fora do container. Container morre, volume fica.
• Rede: subnets virtuais que conectam containers entre si por nome.

Seu primeiro Dockerfile

Dockerfile é um script declarativo que constrói uma imagem. Cada instrução vira uma camada cacheada. A ordem importa: ponha o que muda menos no topo, o que muda mais no fim.

# Node.js 22 LTS slim (~180 MB) — evite "node:22" puro (~1 GB)
FROM node:22-slim

# define diretório de trabalho dentro do container
WORKDIR /app

# copia só os manifestos primeiro — aproveita cache se package.json não mudou
COPY package.json package-lock.json ./
RUN npm ci --only=production

# agora copia o código (muda mais frequentemente)
COPY . .

# documenta a porta; não publica sozinho
EXPOSE 3000

# usuário não-root por padrão é boa prática
USER node

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

# build (o ponto no fim é o contexto)
docker build -t minha-api:1.0 .

# rodar mapeando porta
docker run -d --name api -p 3000:3000 minha-api:1.0

# ver logs
docker logs -f api

# parar e limpar
docker stop api && docker rm api

Multi-stage build: imagens 90% menores

Apps com etapa de build (TypeScript, Vite, Java, Go) não precisam carregar o compilador na imagem final. Multi-stage separa “estágio que compila” de “estágio que roda”.

# Estágio 1: build
FROM node:22-slim AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Estágio 2: runtime — só o necessário
FROM node:22-slim AS runtime
WORKDIR /app
ENV NODE_ENV=production
COPY package*.json ./
RUN npm ci --only=production && npm cache clean --force
COPY --from=builder /app/dist ./dist
USER node
EXPOSE 3000
CMD ["node", "dist/server.js"]

Resultado típico: imagem cai de ~1.2 GB para ~180 MB. Menos superfície de ataque, deploy mais rápido, cache de registry mais barato.

docker compose: orquestrando múltiplos serviços

Quase nenhuma aplicação real é um único container. Você tem API + banco + cache + worker. O docker compose declara tudo em um YAML e sobe junto.

# docker-compose.yml
services:
  api:
    build: .
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgres://app:secret@db:5432/app
      REDIS_URL: redis://cache:6379
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_started

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: app
    volumes:
      - db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app"]
      interval: 5s
      retries: 5

  cache:
    image: redis:7-alpine

volumes:
  db-data:

docker compose up -d         # sobe tudo em background
docker compose logs -f api   # acompanha logs
docker compose down          # para tudo (mantém volumes)
docker compose down -v       # para tudo e apaga volumes

Os 6 erros que travam todo iniciante

1. Esquecer o .dockerignore

Sem .dockerignore o COPY . . manda node_modules, .git, dist/, .env para dentro da imagem. Build fica lento, imagem incha, segredos vazam. Sempre crie:

node_modules
.git
.env
.env.*
dist
build
*.log
coverage

2. Commitar segredos em ENV

ENV no Dockerfile vira parte da imagem — qualquer um que baixe a imagem do registry lê o valor. Use --env-file na hora do run, secrets do docker compose, ou um gerenciador (Doppler, AWS Secrets Manager).

3. Rodar como root

Por padrão o processo roda como root dentro do container, e em volumes montados isso vira arquivos com dono errado no host. Imagens oficiais bem feitas (node, python, nginx) já criam um usuário; use USER no Dockerfile.

4. Não usar HEALTHCHECK

Sem healthcheck, o orquestrador (compose, swarm, k8s) considera o container “vivo” no momento em que o processo subiu — mesmo que esteja em loop de erro. Adicione HEALTHCHECK no Dockerfile ou healthcheck no compose para evitar tráfego em container quebrado.

5. Reconstruir do zero a cada deploy

Se package.json não mudou, npm ci não precisa rodar. Ordene as instruções para aproveitar cache: dependências primeiro, código depois. Em CI, use --cache-from apontando para a imagem anterior.

6. Usar tag latest em produção

latest é um ponteiro mutável. Hoje aponta para 1.4.2, amanhã para 1.5.0 com breaking change. Use versão fixa (node:22.11.0-slim) e bumpe deliberadamente.

E quando aprender Kubernetes?

Não antes de ter um docker compose rodando em produção e doer. Kubernetes resolve problema de escala (centenas de containers, múltiplos hosts, rollout sem downtime, auto-healing). Para uma API + banco em uma VPS, é overkill: aumenta complexidade, custo e tempo de manutenção. Comece com compose ou plataformas tipo Fly.io, Railway, Render — vá para k8s quando o problema aparecer de verdade.

Perguntas frequentes

Fontes consultadas

• Docker — Get Started (documentação oficial)
• Docker — Dockerfile reference
• Docker Compose specification
• Docker — Multi-stage builds
• OWASP Docker Security Cheat Sheet