Containers e Docker
pela lente da F1.

Etapa 01 fundamentos

Por que containers existem

O problema

O conceito

A evolução foi esta: primeiro, uma aplicação por servidor físico, com configuração manual; depois, a virtualização, que divide um servidor em várias VMs; por fim, os containers, que isolam apenas os processos e compartilham o kernel do sistema operacional do host. O foco deixa de ser a máquina e passa a ser a aplicação.

Um container é um conjunto de processos isolados no nível do sistema operacional. Em Linux, dois mecanismos do kernel tornam isso possível:

• Namespaces controlam o que o processo consegue enxergar. Há um tipo para cada recurso: PID (a lista de processos), rede (interfaces e tabelas de rota), mount (sistema de arquivos), UTS (hostname), IPC (comunicação entre processos, como filas e memória compartilhada) e user (identificação de usuários e grupos).
• Cgroups (control groups) medem e limitam recursos, como CPU, memória e operações de entrada e saída em disco. Um container que tenta consumir mais que o previsto fica limitado ao que foi definido, e isso protege os demais.

O container compartilha o kernel do host. Por isso ele costuma iniciar mais rápido e consumir menos recursos que uma VM. Esse compartilhamento também significa que container não é sinônimo de máquina virtual nem uma barreira absoluta de segurança: a proteção depende da configuração do runtime e do host (a Etapa 09 aprofunda isso).

O Docker é a ferramenta que tornou containers acessíveis: ele padroniza como empacotar, distribuir e executar. Uma aplicação empacotada roda do mesmo jeito no seu notebook, no servidor de teste, em produção ou na nuvem, o que elimina o problema do "na minha máquina funciona".

Os conceitos-chave

Exemplos comentados

# Baixa a imagem, cria um container, executa seu processo e exibe a saída.
$ docker run --name primeiro-container hello-world
 
# Lista também containers que já terminaram.
$ docker ps --all
 
# Mostra metadados completos do container em JSON.
$ docker inspect primeiro-container
 
# Remove o container já encerrado.
$ docker rm primeiro-container
 
# saída esperada
Hello from Docker!
...
CONTAINER ID   IMAGE         STATUS                     NAMES
abc123         hello-world   Exited (0) ...             primeiro-container

Comandos essenciais desta etapa

Mão na massa

1. Execute docker run --name fundamentos hello-world.
2. Rode docker ps e depois docker ps --all.
3. Observe que o container aparece apenas no segundo comando.
4. Inspecione seu status com docker inspect --format '{{.State.Status}} {{.State.ExitCode}}' fundamentos.
5. A saída esperada é exited 0. Remova-o com docker rm fundamentos.
6. Rode docker run --rm alpine ps e observe que o único processo listado tem PID 1: o container não enxerga os processos do host.
7. Rode docker run --rm --hostname demo alpine hostname e depois docker run --rm alpine hostname. Observe que o nome muda de um container para outro, e nenhum deles é o nome do seu computador.

Etapa 02 imagem + runtime

Imagem, container e ciclo de vida

O problema

O conceito

Uma imagem reúne o sistema de arquivos e os metadados necessários para iniciar um processo. Ela é imutável e composta por camadas reutilizáveis. Um container acrescenta uma camada gravável temporária sobre a imagem e executa o comando configurado. A mesma imagem pode originar vários containers independentes, e remover um container não remove a imagem.

O fluxo básico é:

1. docker pull baixa uma imagem de um registry, como o Docker Hub.
2. docker run cria e inicia um container a partir da imagem.
3. docker stop solicita a parada do processo.
4. docker start reinicia o mesmo container.
5. docker rm remove o container.
6. docker rmi remove uma imagem que não está sendo usada.

Tags como node:lts-alpine ou nginx:alpine identificam variantes. Evite depender de latest em ambientes que precisam de reprodutibilidade, pois o conteúdo associado à tag pode mudar. Uma tag explícita (por exemplo, a versão principal) ajuda, embora uma tag ainda possa ser movida pelo mantenedor. Quando a exigência for imutabilidade forte, um digest (imagem@sha256:...) identifica o conteúdo da imagem com precisão.

Um registry público permite descobrir e baixar imagens públicas, muitas vezes sem autenticação. O Docker Hub é o exemplo mais conhecido e hospeda tanto software livre (Nginx, Node.js) quanto bases de sistema (Ubuntu, Alpine). Um registry privado restringe o acesso a imagens internas e exige autenticação com docker login. Empresas costumam combinar os dois: imagens comuns vêm do registry público, e as imagens que contêm o código proprietário ficam em repositórios internos, acessíveis apenas a quem é autorizado. Entre as opções de registry privado estão o Amazon Elastic Container Registry (ECR), o Azure Container Registry (ACR), o Google Artifact Registry (que substituiu o antigo Google Container Registry), e soluções auto-hospedadas como Harbor e JFrog Artifactory. Elas se integram a pipelines de CI/CD para automatizar a criação e a distribuição das imagens.

Use imagens públicas apenas quando forem confiáveis e verificadas, e guarde em repositórios privados tudo o que for sensível ou interno.

Antes de enviar uma imagem, o nome local precisa receber uma tag que inclua o endereço do registry, o namespace e a versão.

Um container é a imagem, em camadas somente leitura, mais uma camada gravável fina por cima. Tudo o que o container escreve vai para essa camada.

Vários containers da mesma imagem compartilham as camadas somente leitura, e cada um tem a sua camada gravável. Remover um container apaga só a camada dele.

Os conceitos-chave

Exemplos comentados

# Baixa explicitamente a variante Alpine da imagem oficial.
$ docker pull nginx:alpine
 
# Cria um container em segundo plano.
# O nome facilita os próximos comandos.
# A porta 8080 do host é encaminhada para a porta 80 do container.
$ docker run --detach --name pagina --publish 8080:80 nginx:alpine
 
# Lista os containers em execução.
$ docker ps
 
# Consulta o servidor dentro do container pela porta publicada no host.
$ curl http://localhost:8080
 
# Mostra as mensagens produzidas pelo processo do Nginx.
$ docker logs pagina
 
# Executa um comando em um container que já está em execução.
$ docker exec pagina nginx -v
 
# Encerra e remove o container.
$ docker stop pagina
$ docker rm pagina
 
# saída esperada
CONTAINER ID   IMAGE          PORTS                  NAMES
abc123         nginx:alpine   0.0.0.0:8080->80/tcp   pagina
<!DOCTYPE html>
<title>Welcome to nginx!</title>
nginx version: nginx/...

Comandos essenciais desta etapa

Mão na massa

1. Suba nginx:alpine na porta 8080 com o nome ciclo.
2. Confirme a resposta com curl -I http://localhost:8080. A primeira linha da saída deve ser HTTP/1.1 200 OK.
3. Pare o container e repita o curl. A conexão deve falhar, com uma mensagem como curl: (7) Failed to connect to localhost port 8080.
4. Execute docker start ciclo e confirme que a página voltou (HTTP/1.1 200 OK de novo).
5. Confirme que não há dado necessário somente dentro do container. Então remova-o com docker rm --force ciclo. Essa opção interrompe e remove a instância imediatamente, por isso não deve ser usada sem conferir o alvo.
6. Rode docker images nginx e observe que a imagem continua disponível mesmo sem nenhum container: remover o container não remove a imagem.
7. Garanta que o arquivo nota.txt existe na pasta atual (echo "ola do host" > nota.txt). Crie um container com docker run --detach --name caixa alpine sleep 300, copie o arquivo para ele com docker cp nota.txt caixa:/tmp/nota.txt, leia-o com docker exec caixa cat /tmp/nota.txt (a saída é ola do host) e remova o container com docker rm --force caixa. Em seguida crie outro com o mesmo docker run e rode de novo docker exec caixa cat /tmp/nota.txt. A saída esperada agora é cat: can't open '/tmp/nota.txt': No such file or directory, porque o arquivo ficou na camada gravável do container que foi removido. Remova o segundo container com docker rm --force caixa.

Etapa 03 build reproduzível

Dockerfile como receita reproduzível

O problema

O conceito

O Dockerfile é um arquivo de texto que descreve, de forma declarativa, o passo a passo para construir uma imagem: você diz o que quer e o Docker constrói. O comando docker build lê o Dockerfile e uma pasta de arquivos (o contexto de build, indicado no final do comando, normalmente .) e produz uma imagem.

As instruções essenciais são:

• FROM: escolhe a imagem base. Exemplo: FROM node:lts-alpine significa "comece a partir da imagem do Node em uma base Alpine".
• WORKDIR: define o diretório usado pelas instruções seguintes, para evitar caminhos longos em cada comando. Exemplo: WORKDIR /app.
• COPY: copia arquivos do contexto de build para dentro da imagem. Exemplo: COPY . /app copia tudo o que está no diretório atual para /app.
• RUN: executa uma ação durante a construção (instalar dependências, criar pastas) e grava o resultado como uma nova camada. Exemplo: RUN npm install.
• CMD: define o comando padrão executado quando o container inicia. Exemplo: CMD ["node", "index.js"].
• EXPOSE: documenta a porta usada pela aplicação. Ela não publica a porta no host.

RUN acontece no build e grava uma camada na imagem. CMD acontece no runtime, quando um container é iniciado. Misturar esses dois momentos é uma fonte comum de erro. O CMD pode ser substituído na linha de comando do docker run.

A ordem das instruções importa porque o Docker guarda em cache o resultado de cada uma. Se você muda algo no topo, tudo o que vem abaixo é reconstruído; se muda apenas o CMD, o restante é reaproveitado. A Etapa 04 explora essa regra.

O processo principal e os sinais. O processo definido pelo CMD é o PID 1 do container. No Linux, o PID 1 não recebe o tratamento padrão de sinais: um sinal como SIGTERM ou SIGINT, que normalmente encerra um programa, é ignorado se o programa não instalou um tratador para ele, e o Node.js sem tratador explícito se enquadra nesse caso. O resultado é que o Ctrl+C no terminal pode não encerrar o container, e o docker stop espera o prazo (10 segundos por padrão) e então envia SIGKILL. A opção --init do docker run (e init: true no Compose) coloca um pequeno processo init como PID 1, que repassa os sinais ao seu programa. Por isso os exemplos de API deste guia usam --init. Para encerrar um container em primeiro plano, use o Ctrl+C no terminal dele ou, em outro terminal, docker stop nome. O código de saída 137 que resulta de um encerramento forçado por SIGKILL não indica, por si só, falta de memória; a Etapa 11 mostra como distinguir os dois casos.

Os conceitos-chave

Exemplos comentados

// Importa apenas o módulo HTTP incluído no Node.js.
const http = require("node:http");
 
// Lê a porta do ambiente e mantém 3000 como padrão local.
const port = Number(process.env.PORT || 3000);
 
// Cria uma resposta JSON simples para qualquer requisição.
const server = http.createServer((_request, response) => {
  response.writeHead(200, { "content-type": "application/json" });
  response.end(JSON.stringify({ status: "ok" }));
});
 
// Escuta em todas as interfaces do container.
server.listen(port, "0.0.0.0", () => {
  console.log(`Servidor disponível na porta ${port}`);
});

Comandos essenciais desta etapa

Mão na massa

1. Crie os dois arquivos do exemplo em um diretório vazio.
2. Construa minha-api:1.0 e execute o container com --init, como no exemplo.
3. Em outro terminal, confirme a resposta com curl http://localhost:3000 e encerre o container com docker stop minha-api (ou Ctrl+C no terminal dele). Confirme com docker ps que a porta 3000 ficou livre.
4. Troque o valor da resposta para {"status":"pronto"}.
5. Reconstrua com a tag minha-api:1.1.
6. Rode docker images minha-api e observe que as versões são imagens distintas.
7. Rode docker run --rm minha-api:1.1 node -e "console.log('outro comando')" e observe que o CMD foi substituído sem reconstruir nada.

Etapa 04 otimização

Camadas, cache, imagens mínimas e multistage build

O problema

O conceito

O Docker armazena o resultado de cada instrução como uma camada. Se encontra uma camada idêntica à que já construiu, ele a reaproveita (aparece como CACHED no build). Isso só acontece enquanto a instrução e seus arquivos de entrada não mudam, e, quando uma camada é invalidada, todas as seguintes também são. Por isso arquivos de dependências devem ser copiados antes do restante do código: copie primeiro o mínimo necessário para instalar as dependências, rode a instalação e só depois copie o resto do projeto.

A mesma lógica vale para qualquer gerenciador de pacotes (npm, pip, yarn, pnpm, composer); mudam só os nomes dos arquivos. Use também o modo que respeita o lockfile (npm ci, --frozen-lockfile) para builds previsíveis.

Um multistage build usa uma etapa rica em ferramentas para construir o artefato e uma etapa final menor para executá-lo. Você abre um FROM para o build, instala dependências e compila, e depois abre um novo FROM limpo, copiando apenas o resultado com COPY --from=. Ferramentas de build, node_modules de desenvolvimento e arquivos temporários não vão para a imagem final.

Variantes comuns de imagem base:

• slim: base Debian reduzida, com boa compatibilidade. É um meio-termo entre peso e conveniência.
• alpine: distribuição mínima (poucos megabytes) que usa musl em vez da glibc e o gerenciador de pacotes apk. Faltam coisas que costumam vir por padrão, como bash e curl; instale-as com apk add quando precisar. Pode exigir ajustes para dependências nativas.
• distroless: contém apenas o necessário para executar a aplicação, sem shell, sem gerenciador de pacotes e sem utilitários. É excelente para produção do ponto de vista de segurança, mas exige um build muito bem feito e normalmente depende de multistage.

Menor nem sempre significa melhor. Para desenvolvimento, ou enquanto você ainda não sabe o que vai precisar, comece com uma imagem mais completa e "seque" depois que tudo funcionar. Para produção, quando você já sabe exatamente o que roda, alpine ou slim reduzem o tamanho final, o tempo de transferência e a superfície de ataque. A base deve ser compatível, atualizada e suficiente para diagnosticar e executar a aplicação.

O exemplo multistage a seguir copia apenas /app/dist para o runtime. Isso só funciona quando dist é autossuficiente ou quando a aplicação usa apenas módulos nativos do Node. Se o artefato importa pacotes de node_modules, a etapa final também precisa receber as dependências de produção, por exemplo com uma instalação npm ci --omit=dev própria. Multistage não autoriza deixar dependências necessárias para trás.

Sem mudança nos arquivos, cada instrução reaproveita a camada já construída.

Os arquivos copiados mudaram: o COPY perde o cache, e todas as instruções depois dele também. Por isso o que muda menos vem primeiro.

Os conceitos-chave

Exemplos comentados

# ERRADO: copiar o projeto inteiro antes de instalar.
# Qualquer alteração em qualquer arquivo invalida o COPY, e o npm ci roda de novo.
FROM node:lts-alpine
WORKDIR /app
COPY . .
RUN npm ci

Comandos essenciais desta etapa

Mão na massa

1. Crie uma pasta com o server.js da Etapa 03, o package.json, o package-lock.json, o build.js e o Dockerfile multistage desta etapa.
2. Confirme que o package-lock.json é exatamente o fornecido acima. Ele permite que npm ci rode dentro do build sem exigir Node ou npm no host.
3. Rode docker build --tag minha-app:otimizada . duas vezes.
4. Na segunda execução, observe CACHED nas etapas que não mudaram.
5. Altere apenas a mensagem de resposta em server.js e reconstrua.
6. Confirme que a etapa npm ci continuou em cache e teste com docker run --rm --init --publish 3000:3000 minha-app:otimizada, seguido de curl http://localhost:3000 em outro terminal. Para encerrar, use Ctrl+C no terminal do container ou docker stop com o ID mostrado por docker ps, em outro terminal. Como o container foi criado sem --name, o Docker escolhe um nome aleatório; consulte-o em docker ps.
7. Troque a ordem das instruções para o formato "ERRADO" (um COPY . . antes do npm ci), altere server.js de novo e reconstrua. Observe que desta vez o npm ci roda novamente. Desfaça a troca.
8. Rode os três comandos de "sentindo a diferença entre bases" e anote o que está ausente no Alpine.

Etapa 05 volumes + mounts

Persistência com volumes, bind mounts e tmpfs

O problema

O conceito

A camada gravável do container é descartável por definição. Dados que precisam sobreviver à troca do container devem ficar em outro lugar, conectado a ele. O Docker oferece três mecanismos principais:

Volume nomeado. É a forma recomendada para produção. O Docker cria e registra o volume em seus metadados internos e o armazena, por padrão, no host em um caminho como /var/lib/docker/volumes/<nome>/_data; o que o container enxerga é esse diretório montado no caminho que você definiu (por exemplo, /var/lib/mysql). Pontos fortes: gerenciamento por comandos Docker, backup e migração mais simples, isolamento do restante do host. O caminho físico é um detalhe interno da Engine e pode variar conforme sistema e runtime, então prefira os comandos Docker em vez de manipular /var/lib/docker diretamente.

Bind mount. Aponta diretamente para um caminho específico do host, que o container enxerga exatamente como ele está, com todos os arquivos e permissões. É ótimo no desenvolvimento, porque você edita o código no host e o container vê a mudança em tempo real. Em contrapartida, não há isolamento (o container pode alterar o sistema de arquivos do host) e a portabilidade é limitada, porque depende da estrutura de pastas daquele computador.

tmpfs. Armazena os dados na memória do host. Ao parar ou reiniciar o container, tudo é perdido. É adequado para dados temporários ou sensíveis que, em geral, não devem ser gravados em disco (sob pressão de memória, o sistema pode mover páginas de tmpfs para a área de swap, então não o trate como garantia absoluta de que nada chega ao disco). tmpfs é um tipo de montagem, e não um driver de volume persistente.

Drivers de volume. O driver local é o padrão e usa o sistema de arquivos do host; atende bem à maioria dos casos e é o ponto de partida recomendado. Quando vários hosts precisam acessar o mesmo armazenamento, o volume pode usar NFS por meio do próprio driver local ou um plugin de terceiros compatível com o provedor (por exemplo, integrações com EBS, Azure Disk ou Ceph). Em ambientes com orquestrador na nuvem, drivers especializados ou plugins CSI no Kubernetes são as opções comuns. Essa escolha depende de rede, disponibilidade, permissões, backup e consistência exigida pela aplicação; só parta para ela se houver necessidade real de compartilhamento, persistência remota ou requisitos específicos de desempenho.

Os conceitos-chave

Exemplos comentados

# Cria um volume administrado pelo Docker.
$ docker volume create dados-demo
 
# Escreve um arquivo dentro do volume e remove o container ao terminar.
$ docker run --rm \
  --volume dados-demo:/dados \
  alpine sh -c 'echo persistiu > /dados/mensagem.txt'
 
# Um novo container lê o mesmo volume.
$ docker run --rm \
  --volume dados-demo:/dados:ro \
  alpine cat /dados/mensagem.txt
 
# Exibe metadados do volume.
$ docker volume inspect dados-demo
 
# saída esperada
persistiu

Comandos essenciais desta etapa

Mão na massa

1. Execute os comandos do primeiro exemplo (volume dados-demo).
2. Confirme que o primeiro container não existe mais com docker ps --all.
3. Leia o arquivo usando um segundo container.
4. Prove que o tmpfs não sobrevive ao reinício: rode o exemplo do tmpfs (docker run --detach --init --name tmp-demo --tmpfs /dados alpine sleep 300, grave com docker exec tmp-demo sh -c 'echo x > /dados/a', rode docker restart tmp-demo e liste com docker exec tmp-demo ls -A /dados). A listagem deve sair vazia. Remova o container com docker rm --force tmp-demo.
5. Rode o exemplo do bind mount e confirme que a edição feita no host aparece na resposta sem reiniciar o container.
6. Confirme que o volume contém apenas dados de laboratório. Então execute docker volume rm dados-demo. A remoção é permanente e não oferece lixeira ou recuperação automática.

Etapa 06 conectividade

Redes, DNS interno e publicação de portas

O problema

O conceito

Cada container recebe seu próprio namespace de rede e um IP próprio dentro de uma rede Docker. Quando você cria uma rede personalizada com docker network create, o Docker habilita nela um DNS interno: cada container conectado pode ser encontrado pelo nome definido em --name. A API se conecta ao banco usando o hostname banco, sem IP fixo; uma aplicação Node.js falaria com um MongoDB apenas apontando a URI para mongodb://mongo:27017, desde que o container se chame mongo e ambos estejam na mesma rede.

As redes personalizadas também são isoladas por padrão: só containers conectados à mesma rede se enxergam. Isso permite isolar bancos de dados, separar ambientes (dev e prod) e reduzir a superfície de ataque. Containers podem ser conectados e desconectados de redes a qualquer momento, o que dá controle fino sobre quem conversa com quem. A mesma lógica de redes é usada pelo Docker Compose (Etapa 07) e por orquestradores como o Kubernetes.

Os modos de rede são:

• bridge: rede isolada no mesmo host, com IP por container. Redes bridge criadas pelo usuário oferecem resolução automática por nome. É o modo do dia a dia, indicado para desenvolvimento local e ambientes simples em um só host.
• host: o container compartilha a pilha de rede do host, sem NAT e sem IP próprio. Dá mais desempenho e acesso direto à rede do host (útil para monitoramento e proxies locais), mas elimina o isolamento de rede e pode causar conflito de portas.
• none: desabilita a conectividade de rede do container. Útil para testes e cargas que não devem se comunicar com nada.
• overlay: conecta containers em hosts diferentes, usado com o Docker Swarm. Outras redes avançadas (como macvlan) existem para cenários específicos de orquestração e ficam fora deste guia.

A rede bridge padrão (a que o container recebe quando você não especifica nada) e uma bridge criada pelo usuário não são equivalentes. O DNS por nome de container é uma vantagem da rede personalizada. Na bridge padrão, não dependa dessa descoberta automática.

Descoberta por nome é diferente de acesso externo. EXPOSE 3000 documenta uma porta na imagem. --publish 8080:3000 cria o encaminhamento da porta 8080 do host para a porta 3000 do container. Para serviços que só outros containers acessam (como o banco), não publique nada.

DNS não transmite dados nem autentica participantes: ele só resolve nomes para endereços. Isolamento, criptografia e autorização exigem mecanismos próprios.

Os conceitos-chave

Exemplos comentados

# Cria uma bridge com DNS interno.
$ docker network create rede-demo
 
# Inicia um servidor chamado web nessa rede.
$ docker run --detach --name web --network rede-demo nginx:alpine
 
# Um container temporário resolve o hostname web e faz uma requisição.
$ docker run --rm --network rede-demo curlimages/curl \
  --silent --head http://web
 
# Mostra quais containers estão conectados.
$ docker network inspect rede-demo
 
# Limpa os recursos do exercício.
$ docker rm --force web
$ docker network rm rede-demo
 
# saída esperada
HTTP/1.1 200 OK
Server: nginx/...

Comandos essenciais desta etapa

Mão na massa

1. Rode o primeiro exemplo (rede-demo) sem os dois comandos de limpeza do final (docker rm --force web e docker network rm rede-demo), porque os passos seguintes ainda precisam do container web e da rede. Confirme o status HTTP/1.1 200 OK.
2. Execute docker run --rm curlimages/curl --head http://web, sem --network rede-demo.
3. Observe a falha de resolução, pois o novo container está fora da rede. A saída esperada é curl: (6) Could not resolve host: web.
4. Crie um cliente com docker run --detach --name cliente alpine sleep 300.
5. Conecte-o com docker network connect rede-demo cliente.
6. Prove a descoberta por nome com docker exec cliente wget -qO- http://web. A saída deve conter o HTML de boas-vindas do Nginx (<title>Welcome to nginx!</title>).
7. Inspecione as conexões com docker network inspect rede-demo e localize web e cliente na lista de containers.
8. Desconecte o cliente com docker network disconnect rede-demo cliente, repita o wget e observe que a resolução falha de novo, com wget: bad address 'web'.
9. Confira os nomes e remova os containers de laboratório com docker rm --force cliente web; depois remova a rede com docker network rm rede-demo. --force encerra os containers sem a parada normal e só é apropriado aqui porque ambos são descartáveis.
10. Rode o exemplo "a bridge padrão não resolve nomes" e compare o erro (wget: bad address 'alvo') com o sucesso do passo 6.

Etapa 07 multicontainer

Docker Compose para aplicações multicontainer

O problema

O conceito

O Docker Compose descreve uma aplicação inteira em um único arquivo YAML (por padrão compose.yaml; o nome mais antigo docker-compose.yml continua aceito). Com um comando você sobe, observa e derruba todos os containers, redes e volumes. O Compose cria automaticamente uma rede para o projeto, e os serviços se encontram pelo nome do serviço (db, web), com a mesma lógica de DNS da Etapa 06. O nome do projeto é, por padrão, o nome da pasta, e os containers recebem nomes como projeto-web-1.

Os elementos principais do arquivo são:

• services: os containers que formam a aplicação.
• build ou image: como obter a imagem de cada serviço.
• ports: portas publicadas no host.
• volumes: persistência ou compartilhamento de arquivos.
• networks: limites de comunicação.
• environment e env_file: configuração não secreta.
• secrets: arquivos montados para dados sensíveis (Etapa 10).
• init: init: true executa um init como PID 1 do serviço, equivalente ao --init do docker run (Etapa 03).

Em vez de image:, um serviço pode usar um bloco build: para ser construído localmente antes de subir. Três campos dão controle sobre isso: context (a pasta usada como base do build), dockerfile (qual arquivo usar, útil para Dockerfile.dev e Dockerfile.prod) e args (parâmetros de build declarados com ARG no Dockerfile). Isso evita acumular Dockerfiles quase idênticos e permite que qualquer pessoa clone o repositório e rode docker compose up com builds adaptados ao fluxo do time.

O Compose não resolve tudo sozinho. Ele interpreta a definição e coordena recursos Docker, mas a aplicação ainda precisa lidar corretamente com inicialização, falhas transitórias e dependências. depends_on garante a ordem de criação, e não que o banco esteja pronto; a prontidão é tratada com healthchecks nas Etapas 08 e 12.

Os conceitos-chave

Exemplos comentados

services:
  web:
    # Constrói usando o Dockerfile do diretório atual.
    build:
      context: .
      dockerfile: Dockerfile
    # Executa um init como PID 1, para que o Node receba o SIGTERM e o down seja rápido.
    init: true
    # Publica apenas o serviço que recebe tráfego externo.
    ports:
      - "3000:3000"
    # O hostname db será resolvido pelo DNS da rede do Compose.
    environment:
      DB_HOST: db
    # Expressa a dependência de criação, não a prontidão do banco.
    depends_on:
      - db
 
  db:
    # Fixa a versão principal da imagem oficial.
    image: postgres:16-alpine
    environment:
      POSTGRES_PASSWORD: exemplo-local
    # Persiste os dados fora do ciclo de vida do container.
    volumes:
      - dados_db:/var/lib/postgresql/data
 
 # Declara o volume nomeado usado pelo banco.
volumes:
  dados_db:

Comandos essenciais desta etapa

Mão na massa

1. Salve o exemplo como compose.yaml ao lado do Dockerfile e do server.js da Etapa 03.
2. Rode docker compose config antes de iniciar. Esse comando mostra a configuração consolidada e detecta erros de YAML.
3. Execute docker compose up --detach --build.
4. Consulte docker compose ps e docker compose logs db.
5. De dentro do serviço web, confirme a descoberta por nome do banco com docker compose exec web nslookup db. A saída deve mostrar o nome db e um endereço IP interno.
6. Finalize com docker compose down. Não use --volumes se quiser preservar os dados. Depois rode docker volume ls e observe que o volume do banco continua lá, com o nome <pasta>_dados_db.

Etapa 08 operações

Ambientes, reinício, escala e CI

O problema

O conceito

Vários arquivos Compose. O Compose combina arquivos na ordem fornecida por -f, e os posteriores sobrepõem os anteriores, desde que os serviços mantenham o mesmo nome. Um arquivo de produção pode substituir somente imagem, portas ou variáveis necessárias, sem duplicar o YAML base:

docker compose \
  -f compose.yaml \
  -f compose.prod.yaml \
  config

Use config para conferir o resultado antes de subir. Por padrão, docker compose up (sem -f) carrega automaticamente compose.yaml e, se existir, compose.override.yaml (nos nomes antigos, docker-compose.yml e docker-compose.override.yml). Isso torna o override o lugar natural dos ajustes de desenvolvimento. Ao usar -f explicitamente, somente os arquivos listados são carregados.

Políticas de reinício:

• no (padrão): não reinicia automaticamente.
• on-failure: reinicia quando o processo termina com código diferente de zero; aceita um limite de tentativas (on-failure:3).
• always: tenta manter o container ativo, qualquer que seja o motivo da parada.
• unless-stopped: semelhante a always, mas respeita uma parada manual.

Não coloque always em tudo: entenda o papel de cada serviço. Um banco costuma ficar bem com unless-stopped; uma API que depende do banco pode usar on-failure com limite, para evitar laços infinitos quando o erro é de configuração; um consumidor de fila que deve estar sempre ativo pode usar always. Política de reinício não resolve ordem de inicialização nem garante que uma dependência esteja pronta. Para prontidão, combine healthcheck e dependências condicionadas (depends_on com condition: service_healthy) quando sua versão do Compose oferecer suporte, e mantenha retentativas na própria aplicação.

Escala. docker compose up --scale worker=3 cria réplicas de um serviço. Cada réplica é uma instância independente, e um mapeamento fixo de porta como 8080:3000 impede várias réplicas no mesmo host, porque a porta 8080 só pode ser ocupada uma vez. Réplicas atrás de uma porta única exigem um balanceador na frente delas.

CI (integração contínua). A mesma definição que roda na máquina de quem desenvolve pode ser usada numa pipeline: subir as dependências (por exemplo, aplicação Node.js e um banco Postgres), rodar os testes de integração e remover tudo. Isso traz consistência entre o ambiente local e a esteira de build, evita depender de serviços externos ou de mocks para tudo e aproxima o ambiente de testes do de produção. O Compose funciona em praticamente qualquer provedor de CI (GitHub Actions, GitLab CI, Bitbucket, Jenkins).

Os conceitos-chave

Exemplos comentados

services:
  web:
    # Usa uma imagem pública para que o exemplo rode sem projeto externo.
    image: nginx:alpine
    # Reinicia somente diante de falha do processo, até três vezes.
    restart: on-failure:3
    labels:
      ambiente: desenvolvimento
    healthcheck:
      # wget já existe nesta variante da imagem.
      test: ["CMD", "wget", "--quiet", "--spider", "http://localhost"]
      interval: 5s
      timeout: 2s
      retries: 5

Comandos essenciais desta etapa

Mão na massa

1. Crie uma pasta vazia e salve nela os dois arquivos YAML do exemplo "base e produção". Nenhum Dockerfile ou código adicional é necessário.
2. Compare docker compose -f compose.yaml config com docker compose -f compose.yaml -f compose.prod.yaml config.
3. Observe a tag da imagem e o valor da label ambiente no resultado consolidado: no primeiro comando aparecem nginx:alpine e desenvolvimento; no segundo, nginx:stable-alpine e producao.
4. Execute docker compose -f compose.yaml -f compose.prod.yaml up --detach --wait.
5. Confirme healthy com docker compose -f compose.yaml -f compose.prod.yaml ps. A coluna de status deve terminar em (healthy).
6. Valide o Nginx com docker compose -f compose.yaml -f compose.prod.yaml exec web nginx -t. A saída deve terminar em test is successful. Encerre com docker compose -f compose.yaml -f compose.prod.yaml down.
7. Em outra pasta, rode o exemplo de reinício e escala. Confirme três réplicas do worker em docker compose ps e o reinicios=3 do falhador. Encerre com docker compose down.
8. Ainda nessa pasta, acrescente ports: ["8080:80"] ao serviço worker e rode docker compose up --detach --scale worker=2. Observe o conflito de porta: uma das réplicas não sobe e o Docker informa Bind for 0.0.0.0:8080 failed: port is already allocated. Finalize com docker compose down para liberar a pasta e a porta.

Etapa 09 menor privilégio

Segurança em camadas

O problema

O conceito

Como o container compartilha o kernel com o host, não basta confiar no isolamento padrão: um escape do container pode dar acesso ao sistema. A defesa vem da combinação de várias camadas, cada uma reduzindo o que uma exploração conseguiria fazer:

• Namespaces isolam a visão de recursos (Etapa 01).
• Capabilities dividem os privilégios tradicionais do root em permissões menores. Por padrão, o root do container já vem com menos poderes que o root do host. Você remove capacidades perigosas (como NET_ADMIN e SYS_ADMIN) com --cap-drop e concede uma específica com --cap-add somente se o serviço provar que precisa dela. A regra é o menor privilégio.
• Seccomp funciona como um filtro de chamadas de sistema (syscalls). O Linux tem centenas delas, e o seccomp permite bloquear várias, com base em uma lista permitida. O Docker já traz um perfil padrão que bloqueia chamadas perigosas, e é possível fornecer um perfil próprio, mais restritivo, com --security-opt seccomp=perfil.json.
• AppArmor ou SELinux, quando habilitados no host, acrescentam controle de acesso obrigatório.
• Usuário não root reduz o impacto de uma exploração. Por padrão, o container roda como root; crie um usuário sem privilégios na imagem e use USER.
• Permissões mínimas evitam chmod 777 como solução genérica: entenda quem deve ser dono de quê e conceda o mínimo necessário.
• Sistema de arquivos somente leitura (--read-only), com tmpfs apenas onde a aplicação precisa gravar, impede que um invasor altere a imagem em execução.
• Imagem pequena e atualizada reduz ferramentas e vulnerabilidades disponíveis.
• Segredos em arquivos próprios evitam valores sensíveis no Dockerfile e no ambiente (Etapa 10).

O usuário root dentro de um container não é automaticamente idêntico ao root do host, pois namespaces e capabilities impõem limites. Ainda assim, executar sem necessidade como UID 0 aumenta o risco, especialmente com mounts perigosos, capabilities extras ou falhas do runtime.

Ao criar o usuário na imagem, use adduser (ou useradd, conforme a distribuição base) e defina o dono dos arquivos copiados com --chown. Ao usar volumes ou bind mounts, o usuário do host pode ser diferente do usuário do container, o que causa problemas de permissão; a solução comum é executar o container com os mesmos UID e GID do host (--user "$(id -u):$(id -g)").

Namespaces não são paredes invioláveis e USER node não resolve segurança sozinho. A defesa vem da combinação de controles, e a implementação real pertence ao kernel, ao runtime, à imagem e às opções de execução. Não monte /var/run/docker.sock em aplicações comuns: quem controla esse socket pode controlar a Docker Engine e, na prática, comprometer o host.

Os conceitos-chave

Exemplos comentados

# Modelo para uma aplicação Node.js em Alpine.
FROM node:lts-alpine
 
# Cria um usuário sem privilégios; -D dispensa senha (comando do Alpine).
# Em bases Debian o equivalente é: RUN useradd -m appuser
RUN adduser -D appuser
 
WORKDIR /app
 
# Copia os arquivos já pertencendo ao usuário da aplicação.
COPY --chown=appuser:appuser . .
 
# Instala dependências conforme o lockfile, ainda com privilégio de build.
RUN npm ci --omit=dev
 
# As instruções seguintes e o processo principal rodam sem privilégios.
USER appuser
 
CMD ["npm", "start"]

Comandos essenciais desta etapa

Mão na massa

1. Rode docker run --rm node:lts-alpine id e observe o usuário padrão da imagem (uid=0(root)).
2. Rode docker run --rm --user node node:lts-alpine id e confirme uid=1000(node).
3. Prove o --read-only como root: rode docker run --rm alpine sh -c 'touch /liberado && echo "escrita permitida"' e depois docker run --rm --read-only alpine touch /bloqueado. A saída do segundo deve ser touch: /bloqueado: Read-only file system.
4. Execute o comando completo do exemplo de runtime com --read-only e --tmpfs /tmp, e confirme as duas mensagens esperadas: raiz bloqueada e tmpfs gravável.
5. Remova --tmpfs /tmp do comando combinado e repita. A escrita em /tmp também falha, pois ele volta a fazer parte da raiz somente para leitura. A saída esperada é raiz bloqueada, seguida de sh: can't create /tmp/teste: Read-only file system e de cat: can't open '/tmp/teste': No such file or directory.
6. Rode os dois comandos do exemplo de capabilities e compare o resultado.
7. Construa e execute o usuario-demo e confirme que o id mostra appuser, e não root.
8. Rode o exemplo de UID e GID e confirme que os donos dos dois arquivos são diferentes e que a edição do arquivo do root pelo host é negada (Permission denied).

Etapa 10 supply chain

Contexto de build, segredos e análise de imagem

O problema

O conceito

O contexto de build é tudo o que está na pasta indicada no docker build (ou no caminho que você passar). Por padrão, o Docker tenta enviar tudo, incluindo .git, node_modules, arquivos grandes e segredos. O `.dockerignore` funciona como um .gitignore para o build: lista o que não deve ser enviado ao contexto. O resultado é um build mais rápido, uma imagem menor e mais segura, e menos invalidações de cache. Mantenha o .dockerignore na raiz do projeto, perto do Dockerfile, e rode o docker build o mais perto possível do Dockerfile. Se o build parece pesado demais, confira o que está no contexto: é comum enviar gigabytes sem perceber.

Considere o projeto:

meu-app/
├── node_modules/
├── .env
├── .git/
├── build/
├── src/
├── Dockerfile
└── compose.yaml

Um .dockerignore adequado:

# Dependências locais serão instaladas dentro da imagem.
node_modules
 
# Configuração local e possíveis segredos não entram no contexto.
.env
.env.*
 
# Histórico, metadados e arquivos temporários são desnecessários.
.git
*.log
coverage
dist
build

Isso evita enviar milhares de arquivos de node_modules, impede que o .env vá parar dentro da imagem, evita copiar o histórico da pasta .git e impede que artefatos de builds anteriores entrem por engano. Cada stack tem necessidades diferentes, então revise qualquer .dockerignore sugerido por ferramentas ou assistentes de código para a sua realidade.

Variáveis de ambiente e segredos. env_file é prático para configuração local, mas não transforma valores em segredos. Eles podem aparecer na configuração e na inspeção do container (docker inspect). Arquivos .env com credenciais não devem ser versionados. A diretiva secrets: do Compose monta o valor como arquivo dentro do container, em /run/secrets/<nome>, o que evita deixá-lo no ambiente do processo. Em desenvolvimento local, env_file continua prático; quando a aplicação passa a ter staging ou produção, migre os dados críticos para secrets.

Parâmetros de build. ARG declara um valor disponível durante a construção, e build.args fornece esse valor pelo Compose. Eles servem para dados não confidenciais, como versão, canal de distribuição ou seleção de recurso. Não use ARG para senha ou token: valores de build podem aparecer no histórico, em metadados e em registros da pipeline.

Ferramentas de análise de imagem. Passada a fase de escrever um Dockerfile enxuto, vale inspecionar a imagem de verdade:

• Dive mostra o conteúdo e o peso de cada camada: o que cada RUN, COPY e ADD adicionou, o que está pesando e o que pode sair.
• Snyk verifica vulnerabilidades conhecidas na imagem e em dependências, usando uma base de dados de vulnerabilidades mantida continuamente. Funciona por linha de comando e se integra a pipelines de CI.

Um complementa o outro: o Dive ajuda a entender o tamanho, e o Snyk cuida da segurança.

Os conceitos-chave

Exemplos comentados

# Usa uma base concreta antes de declarar o argumento do estágio.
FROM node:lts-alpine
 
# Declara um parâmetro não confidencial com valor padrão.
ARG APP_VERSION=dev
 
# Registra a versão como metadado consultável na imagem.
LABEL org.opencontainers.image.version=$APP_VERSION

Comandos essenciais desta etapa

Mão na massa

1. Entre na pasta da Etapa 04 e crie o peso de propósito: mkdir -p node_modules && head -c 50000000 /dev/urandom > node_modules/pesado.bin.
2. Rode docker build --progress plain --tag minha-app:analise . uma única vez e anote o tamanho do contexto (cerca de 50 MB).
3. Crie o .dockerignore do exemplo na mesma pasta, repita o build e compare o tamanho enviado (alguns kB) e o reaproveitamento do cache.
4. Use docker history minha-app:analise para identificar instruções que adicionaram mais dados. Remova o peso artificial com rm -rf node_modules.
5. Reproduza o exemplo "um segredo que sobrevive no histórico": confirme no docker history a linha do COPY com 21B (ou um valor um pouco maior e arredondado, se o Docker usar o image store do containerd) e a do RUN rm com 0B, e rode o roteiro com docker save para ver senha-de-laboratorio aparecer em texto puro.
6. Reproduza o exemplo do ARG com image: versao-demo e confirme que o docker inspect imprime 1.4.0.
7. Se Dive ou Snyk estiver instalado, analise a mesma tag e registre um ponto de melhoria.

Etapa 11 diagnóstico

Troubleshooting com uma ordem de investigação

O problema

O conceito

Use uma sequência previsível, da evidência mais barata à mais específica:

1. Estado: docker ps --all mostra se o container está rodando, encerrado ou reiniciando.
2. Logs: docker logs mostra stdout e stderr do processo.
3. Configuração: docker inspect revela comando, mounts, rede, portas e estado.
4. Eventos: docker events mostra criação, início, parada, kill e remoção em tempo real.
5. Processo e recursos: docker top e docker stats mostram processos e consumo.
6. Teste interno: docker exec executa uma verificação dentro de um container ainda ativo.

O docker inspect devolve JSON detalhado e é a fonte de respostas para perguntas como: qual comando original está sendo executado (Config.Cmd), quais volumes estão montados e onde (Mounts), quais portas estão expostas e mapeadas (NetworkSettings.Ports), qual é a imagem (Image) e se o container está parado por erro ou reiniciando (State). Para saber se o container morreu por falta de memória, verifique State.OOMKilled. A opção --format extrai exatamente o campo desejado, e a saída completa pode ser combinada com ferramentas como jq ou usada em scripts de shell.

O código de saída conta uma parte da história: 0 indica término normal; qualquer outro valor vem do próprio programa ou do Docker. Valores conhecidos incluem 125 (o Docker falhou ao executar o docker run), 126 (o comando existe mas não pôde ser invocado), 127 (o comando não foi encontrado) e 137 (o processo recebeu SIGKILL). O 137 tem mais de uma origem: pode ser falta de memória (nesse caso OOMKilled aparece como true), mas também aparece quando um docker stop esgota o prazo sem que o processo atenda ao SIGTERM e o Docker envia SIGKILL (nesse caso OOMKilled continua false; é o efeito do PID 1 sem tratador de sinal descrito na Etapa 03). Confirme sempre com OOMKilled antes de concluir que faltou memória.

O docker events é leve e nativo, e acompanha mudanças de estado de containers, imagens, volumes e redes, com timestamps. É especialmente útil no troubleshooting em tempo real, ao testar scripts de automação ou durante deploys. Pode ser filtrado por tipo (--filter type=container) ou por container (--filter container=nome) e a saída pode alimentar scripts ou um sistema de logs.

docker restart sem evidência desliga e liga o sistema sem ler o que ele disse: pode devolver o serviço por alguns minutos, mas também apaga o contexto operacional e não identifica a causa. A ordem acima protege o diagnóstico contra palpites: a inspeção vem antes de qualquer reinício.

Os conceitos-chave

Exemplos comentados

# O shell registra uma mensagem de erro e termina com código 42.
$ docker run --name falha alpine \
  sh -c 'echo "configuração ausente" >&2; exit 42'
 
# Confirma o código de saída sem ler todo o JSON.
$ docker inspect --format \
  'status={{.State.Status}} exit={{.State.ExitCode}} oom={{.State.OOMKilled}}' \
  falha
 
# Recupera a mensagem emitida pelo processo.
$ docker logs falha
 
# saída esperada
configuração ausente
status=exited exit=42 oom=false
configuração ausente

Comandos essenciais desta etapa

Mão na massa

1. Provoque a falha rodando só o primeiro comando do exemplo (o docker run --name falha ...), sem o docker rm: a remoção fica para o passo 5. A mensagem configuração ausente já aparece no terminal durante esse comando.
2. Antes de olhar os logs, formule uma hipótese apenas com estado e exit code: rode o docker inspect --format do exemplo e leia status=exited exit=42 oom=false.
3. Confira a hipótese com docker logs falha. A mesma mensagem aparece uma segunda vez, agora vinda do registro do Docker.
4. Use docker inspect --format '{{json .Config.Cmd}}' falha para ver o comando original.
5. Remova o container somente depois de registrar a causa: docker rm falha.
6. Rode docker run --rm alpine comando-inexistente, leia o erro e confira o código com echo $?. A saída esperada é 127.
7. Com docker events --filter type=container aberto em um terminal, rode docker run --rm --name evento alpine true em outro e identifique cada evento (create, attach, start, die, destroy).

Etapa 12 observabilidade

Logs, healthcheck e prontidão operacional

O problema

O conceito

Um healthcheck executa periodicamente uma verificação e classifica o container como starting, healthy ou unhealthy. O estado do processo indica presença; o healthcheck verifica capacidade de serviço. Ele não corrige a aplicação sozinho: a política do runtime ou do orquestrador decide como reagir. Um bom healthcheck também funciona como alerta para instabilidade.

Um resultado healthy tem alcance limitado. Ele prova apenas a condição examinada pelo teste naquele momento. Um endpoint raso pode passar no teste enquanto uma função importante está quebrada; um teste pesado demais pode criar carga e falso alarme. O healthcheck precisa representar a função certa com custo controlado.

Os parâmetros principais são test (o comando), interval (de quanto em quanto tempo), timeout (quanto esperar por uma tentativa), retries (quantas falhas seguidas marcam unhealthy) e start_period (um período inicial em que falhas não contam, para a aplicação ter tempo de subir). Ele pode ser declarado no Dockerfile (instrução HEALTHCHECK), no Compose (healthcheck:) ou no docker run (--health-cmd e opções relacionadas).

Logs. Aplicações devem escrever logs em stdout e stderr, que é o que docker logs lê. Mas confiar apenas em docker logs deixa de bastar com múltiplas instâncias: os logs ficam fragmentados entre containers e, se o container for destruído, geralmente se perdem. A solução é centralizar e estruturar. Logs estruturados são registros em formato padronizado (geralmente JSON), com campos consistentes como timestamp, level, message e service, o que facilita busca e correlação de eventos. Em ambientes maiores:

• Promtail é um agente que roda junto dos containers, lê os logs locais e os envia ao Loki. (Ele é o agente histórico do Loki, e a Grafana passou a indicar outro coletor; confirme na documentação da Grafana qual agente de coleta ela recomenda.)
• Loki armazena e consulta logs de forma eficiente, com um modelo semelhante ao do Prometheus, só que para logs.
• Fluentd pode coletar, transformar e rotear eventos, e serve em cenários mais complexos, em que os logs precisam ser enriquecidos antes do envio.
• Grafana consulta e visualiza os dados, monta dashboards e correlaciona logs com métricas.

Para começar, vale montar um setup simples com Compose que inclua o coletor, o Loki e o Grafana. Combinar logs estruturados com alertas sobre eventos críticos eleva a observabilidade da aplicação.

Os conceitos-chave

Exemplos comentados

services:
  api:
    image: minha-api:1.0
    healthcheck:
      # Executa uma requisição com uma ferramenta presente na imagem.
      test: ["CMD", "curl", "--fail", "http://localhost:3000/health"]
      # Verifica a cada 30 segundos.
      interval: 30s
      # Interrompe uma tentativa que passe de 10 segundos.
      timeout: 10s
      # Marca unhealthy após três falhas consecutivas.
      retries: 3
      # Dá tempo para a aplicação iniciar antes de contar falhas.
      start_period: 20s

Comandos essenciais desta etapa

Mão na massa

1. Rode o exemplo do sensor e observe a sequência starting, unhealthy e healthy.
2. Construa a imagem minha-api:saude, suba o container e acompanhe o STATUS em docker ps até aparecer (healthy).
3. Rode docker logs --tail 5 --timestamps api-saude e observe o horário de cada linha. Depois remova o container com docker rm --force api-saude. Os exercícios de perder a dependência real de uma API e ver o healthcheck reagir ficam na Etapa 13, depois que você tiver a stack completa para testar.

Etapa 13 stack defensiva

Capstone, uma stack pequena e defensiva

O problema

O conceito

Este projeto final combina somente mecanismos já apresentados: Dockerfile, multistage build, usuário não root, rede personalizada, volume, tmpfs, segredo em arquivo, healthcheck, dependência por saúde, privilégios reduzidos, logs e Compose. Nenhum mecanismo isolado entrega uma aplicação confiável; o resultado vem da disciplina do conjunto.

A API usa apenas módulos nativos do Node. Ela testa se consegue abrir uma conexão TCP com o PostgreSQL. Isso prova descoberta por DNS e conectividade sem adicionar uma biblioteca de banco ao exercício.

O Compose também aplica limites simples de CPU e memória. Eles contêm o consumo máximo do laboratório, mas não garantem desempenho nem reservam capacidade exclusiva. Labels acrescentam metadados para inventário, automação e observabilidade; elas descrevem os serviços sem alterar seu comportamento.

O serviço api usa init: true: como a Etapa 03 explicou, o Node como PID 1 ignora o SIGTERM sem um tratador de sinal, e o init repassa o sinal, de modo que docker compose down e docker compose stop terminam em segundos em vez de esperar o prazo de 10 segundos.

O healthcheck do banco usa pg_isready -h 127.0.0.1, com o endereço TCP explícito. A imagem do PostgreSQL, na primeira inicialização, sobe um servidor temporário que escuta apenas em socket Unix enquanto prepara o banco. Sem o -h, o pg_isready consulta esse socket e pode responder "pronto" antes de o servidor definitivo aceitar conexões TCP, que é o caminho que a API usa. Com o endereço explícito, o teste só passa quando o banco realmente atende por TCP.

Checklist de produção. Antes de colocar qualquer container em produção, vale uma última revisão. O capstone cobre cada item abaixo, e o arquivo indica onde:

1. Imagem otimizada: evite imagens genéricas e pesadas (como node:latest); prefira variantes slim/alpine ou um multistage, para que só o essencial vá para produção. Coberto pelo Dockerfile.
2. Variáveis sensíveis seguras: senhas e tokens via secrets:, e não via env_file ou diretamente no Compose. Coberto pelo bloco secrets.
3. Limites de recursos: CPU e memória definidos para não sobrecarregar o host. Coberto por cpus e mem_limit.
4. Healthcheck configurado: serve de alerta e dá ao orquestrador o critério de reinício. Coberto pelos dois healthcheck.
5. Log estruturado: a aplicação escreve JSON em stdout, pronto para uma stack de observabilidade (Etapa 12). Coberto pelo server.js.
6. Usuário sem privilégios: USER node no Dockerfile. Coberto.
7. Rede isolada: rede específica entre serviços, em vez da bridge padrão. Coberto pela rede interna.
8. Persistência garantida: volume para que nenhum dado importante se perca em um restart. Coberto por dados_db.
9. Labels e metadados: facilitam automação e integração com ferramentas de monitoramento. Coberto pelas labels.
10. Teste final local: simule o ambiente de produção localmente, combinando os arquivos (docker compose -f compose.yaml -f compose.prod.yaml up) antes de subir de verdade. Veja o último passo da seção "Mão na massa".

Os limites também podem ser escritos no formato deploy.resources.limits do Compose, que a bibliografia usa:

services:
  api:
    deploy:
      resources:
        limits:
          # Meia CPU e 512 MB de memória.
          cpus: "0.50"
          memory: 512M

Ambos os formatos são aceitos pelo Compose v2; este guia usa cpus e mem_limit. Confira o resultado com docker compose config.

Os conceitos-chave

Exemplos comentados

capstone/
├── app/
│   └── server.js
├── secrets/
│   └── db_password.txt
├── .dockerignore
├── Dockerfile
└── compose.yaml

Comandos essenciais desta etapa

Mão na massa

1. Crie a estrutura e os arquivos exatamente como mostrados.
2. Grave uma senha de laboratório com mkdir -p secrets && printf 'troque-esta-senha' > secrets/db_password.txt && chmod 644 secrets/db_password.txt. O chmod 644 importa porque o Postgres lê o arquivo como o usuário postgres dentro do container; com uma umask restritiva no host, o arquivo nasceria legível só por você e a leitura poderia falhar.
3. Valide o YAML com docker compose config --quiet.
4. Suba a stack com docker compose up --detach --build --wait.
5. Rode curl http://localhost:3000/health.
6. A saída esperada é {"service":"api","database":"reachable"}.
7. Rode docker compose ps e confirme que ambos os serviços estão saudáveis.
8. Rode docker compose logs api e localize o log JSON da requisição.
9. Confirme o usuário com docker compose exec api id. A saída deve identificar o usuário node, não root.
10. Execute docker compose down, suba novamente e confirme que o volume capstone_dados_db (o prefixo é o nome da sua pasta) continua existindo com docker volume ls. Repare também que o down termina em poucos segundos, graças ao init: true.
11. Se quiser preservar o banco, encerre apenas com docker compose down. Use docker compose down --volumes somente quando decidir descartar o laboratório: esse comando remove o volume capstone_dados_db e apaga definitivamente seu conteúdo, sem lixeira ou recuperação automática. Faça backup antes se houver qualquer dado necessário.
12. Para fechar o item 10 do checklist de produção, escreva um compose.prod.yaml mínimo (por exemplo, trocando restart ou adicionando uma label ambiente: producao), valide com docker compose -f compose.yaml -f compose.prod.yaml config e suba com -f nos dois arquivos antes de considerar o ambiente pronto.
13. Extra, perder o banco e voltar: com a stack no ar (docker compose up --detach --build --wait), confirme o estado inicial com docker compose ps. API e banco devem aparecer como healthy.
14. Extra: pare a dependência real da API com docker compose stop db.
15. Extra: acompanhe docker compose ps até a API aparecer como unhealthy. O endpoint retorna 503 porque o teste TCP ao banco falha, e curl -i http://localhost:3000/health mostra HTTP/1.1 503 com {"service":"api","database":"unreachable"}.
16. Extra: consulte as tentativas com docker inspect --format '{{json .State.Health}}' $(docker compose ps -q api) e correlacione com docker compose logs api, onde as linhas de nível error aparecem.
17. Extra: recupere o banco com docker compose start db e aguarde os dois serviços voltarem a healthy em docker compose ps.

Etapa 14 · revisão

Checklist de autoavaliação

Próximos passos: com todos os itens marcados, refaça os laboratórios sem consultar o guia e depois junte as peças. Provoque falhas no capstone (pare o banco, troque a senha, remova o volume) e explique cada resposta do sistema antes de olhar os logs. Em seguida, acrescente um terceiro serviço (por exemplo, um cache) e leve a mesma stack para um fluxo de CI com docker compose up --wait.