Docker: from the first container to a smaller attack surface.

O que é Docker: contêiner, imagem e por que usarWhat Docker is: container, image and why use it

Todo mundo já ouviu “na minha máquina funciona”. O Docker resolve isso empacotando o app junto com tudo que ele precisa para rodar (runtime, bibliotecas, arquivos de sistema) numa unidade que se comporta igual no seu notebook, no CI e no servidor. Essa unidade em execução é um contêiner.Everyone has heard “it works on my machine”. Docker fixes that by packaging the app together with everything it needs to run (runtime, libraries, system files) into a unit that behaves the same on your laptop, in CI and on the server. That unit, running, is a container.

Um contêiner não é uma máquina virtual. A VM simula um computador e roda um sistema operacional inteiro por cima. O contêiner é só um processo comum do Linux, isolado por recursos do próprio kernel (namespaces escondem o resto do sistema; cgroups limitam CPU e memória). Por isso sobe em milissegundos e pesa megabytes em vez de gigabytes.A container is not a virtual machine. A VM simulates a computer and runs a whole operating system on top. A container is just an ordinary Linux process, isolated by features of the kernel itself (namespaces hide the rest of the system; cgroups cap CPU and memory). That is why it starts in milliseconds and weighs megabytes instead of gigabytes.

O exemplo que acompanha a nota é um mini serviço em Go (o código completo está na atividade 0) com três rotas: / responde com o nome do contêiner, /health diz que está vivo e /db tenta abrir uma conexão com um Postgres vizinho. Go foi escolhido porque gera um binário único, o que deixa o multi-stage build (mais abaixo) bem visível; nada aqui depende de Go.The example that runs through the note is a tiny Go service (full code in activity 0) with three routes: / answers with the container name, /health says it is alive and /db tries to open a connection to a neighbouring Postgres. Go was chosen because it produces a single binary, which makes the multi-stage build (below) very visible; nothing here depends on Go.

Do Dockerfile ao contêiner: o ciclo de vidaFrom Dockerfile to container: the life cycle

O fluxo é sempre o mesmo: build (Dockerfile → imagem), push/pull (levar a imagem de e para um registry) e run (imagem → contêiner). Uma imagem pode virar muitos contêineres, e apagar um contêiner nunca apaga a imagem.The flow is always the same: build (Dockerfile → image), push/pull (move the image to and from a registry) and run (image → container). One image can become many containers, and deleting a container never deletes the image.

A imagem é feita de camadas, uma por instrução do Dockerfile. O Docker guarda cada camada em cache: se a instrução e tudo acima dela não mudaram, ele reaproveita. Por isso a ordem das linhas importa (veja a seção do Dockerfile). Dois contêineres da mesma imagem compartilham as camadas de leitura e só cada um tem a sua camada gravável, que desaparece junto com o contêiner.The image is made of layers, one per Dockerfile instruction. Docker caches each layer: if the instruction and everything above it did not change, it reuses it. That is why the order of the lines matters (see the Dockerfile section). Two containers from the same image share the read-only layers and each has its own writable layer, which vanishes with the container.

Comandos essenciaisEssential commands

# --- imagens ---
docker pull alpine:3.22                 # baixa do registry
docker images                           # lista imagens locais
docker build -t meu-app:1.0 .           # constroi a imagem a partir do ./Dockerfile
docker history meu-app:1.0              # camadas e tamanho de cada uma
docker rmi meu-app:1.0                  # apaga a imagem

# --- contêineres ---
docker run -d --name web -p 8080:8080 meu-app:1.0   # cria + inicia em segundo plano
docker run --rm -it alpine:3.22 sh                  # descartavel e interativo
docker ps                               # os que estao rodando (-a: todos)
docker stop web                         # SIGTERM, espera 10 s, depois SIGKILL
docker start web                        # liga de novo o mesmo contêiner
docker rm web                           # apaga o contêiner parado (-f: forca)
docker exec -it web sh                  # abre um shell DENTRO de um contêiner rodando
docker cp web:/app/arquivo.txt .        # copia arquivo para fora

# --- investigar ---
docker logs -f --tail 50 web            # ultimas 50 linhas e segue
docker inspect web                      # JSON com tudo (IP, volumes, saude, usuario)
docker stats                            # CPU e memoria ao vivo
docker top web                          # processos dentro do contêiner

# --- limpeza ---
docker system df                        # quanto espaco o Docker usa
docker system prune                     # apaga parados, redes e imagens sem tag

Dockerfile: escrevendo a receitaDockerfile: writing the recipe

Primeiro uma versão ingênua, de um único estágio, para entender as instruções. Ela funciona, e é exatamente o tipo de imagem que você não quer em produção (veja o motivo na seção de multi-stage):First a naive, single-stage version, to understand the instructions. It works, and it is exactly the kind of image you do not want in production (see why in the multi-stage section):

FROM golang:1.25-alpine          # imagem base: ponto de partida
WORKDIR /app                     # pasta de trabalho (criada se nao existir)
COPY go.mod ./                   # 1) so o arquivo de dependencias...
RUN go mod download              #    ...e baixa as dependencias (camada em cache)
COPY . .                         # 2) depois o codigo (muda toda hora)
RUN go build -o /app/server .    # compila
EXPOSE 8080                      # documenta a porta (nao publica nada)
CMD ["/app/server"]              # comando de partida

Cache: a ordem das linhas importaCache: line order matters

Repare que o Dockerfile acima copia o go.mod e baixa as dependências antes de copiar o resto do código. Como o código muda a cada commit e as dependências quase nunca, o Docker reaproveita a camada pesada do go mod download e só refaz o COPY . . e o build. A regra geral: o que muda menos vem primeiro. No Node seria COPY package*.json + npm ci antes do COPY . .; no Python, requirements.txt + pip install.Notice that the Dockerfile above copies go.mod and downloads dependencies before copying the rest of the code. Since code changes on every commit and dependencies almost never do, Docker reuses the heavy go mod download layer and only redoes COPY . . and the build. General rule: what changes least comes first. In Node it would be COPY package*.json + npm ci before COPY . .; in Python, requirements.txt + pip install.

.dockerignore.dockerignore

O COPY . . leva a pasta inteira. O arquivo .dockerignore (mesma sintaxe do .gitignore) diz o que ficar de fora: acelera o build e, mais importante, evita que .env, chaves e a pasta .git entrem na imagem, onde qualquer pessoa com a imagem os encontraria.The COPY . . takes the whole folder. The .dockerignore file (same syntax as .gitignore) says what to leave out: it speeds up the build and, more importantly, keeps .env, keys and the .git folder out of the image, where anyone holding the image would find them.

.git
.env
*.pem
node_modules
*.md
Dockerfile*
compose.yaml

Executar o app: PID 1, sinais e um processo por contêinerRunning the app: PID 1, signals and one process per container

• Um processo principal por contêiner. O contêiner vive enquanto esse processo viver; quando ele sai, o contêiner para. Banco, API e fila ficam em contêineres separados, ligados por rede (veja Compose), não todos dentro de um só com systemd ou supervisord.One main process per container. The container lives as long as that process lives; when it exits, the container stops. Database, API and queue go in separate containers, joined by a network (see Compose), not all inside one with systemd or supervisord.
• Use a forma exec (CMD ["/server"], com colchetes), não a forma shell (CMD /server). A forma shell executa sh -c "/server": o shell vira o PID 1 e não repassa o SIGTERM ao app, então o docker stop espera 10 s e acaba matando com SIGKILL, sem desligamento limpo.Use the exec form (CMD ["/server"], with brackets), not the shell form (CMD /server). The shell form runs sh -c "/server": the shell becomes PID 1 and does not forward SIGTERM to the app, so docker stop waits 10 s and ends up killing it with SIGKILL, with no clean shutdown.
• O app deve tratar o SIGTERM (parar de aceitar requisições, terminar as em andamento, fechar conexões). Se ele cria processos filhos, rode com --init (ou init: true no Compose) para um init mínimo recolher os zumbis.The app should handle SIGTERM (stop accepting requests, finish in-flight ones, close connections). If it spawns child processes, run with --init (or init: true in Compose) so a minimal init reaps the zombies.
• O app deve escutar em 0.0.0.0, não em 127.0.0.1: dentro do contêiner, “localhost” é o próprio contêiner, e a porta publicada chega pela interface de rede dele, não pelo loopback.The app must listen on 0.0.0.0, not 127.0.0.1: inside the container “localhost” is the container itself, and the published port arrives through its network interface, not the loopback.
• Configuração por variáveis de ambiente (PORT, DB_ADDR), e logs na saída padrão. Assim a mesma imagem serve para dev, teste e produção.Configuration through environment variables (PORT, DB_ADDR) and logs on standard output. That way the same image serves dev, test and production.

Ubuntu ou Alpine? Escolhendo a imagem baseUbuntu or Alpine? Choosing the base image

Quando um Dockerfile diz FROM ubuntu:24.04, o contêiner não roda o Ubuntu como sistema: ele roda o kernel do host com o sistema de arquivos do Ubuntu por cima (/bin, /etc, o apt, a glibc). Não há boot, systemd nem login. A escolha da base decide quais ferramentas e bibliotecas existem dentro, e portanto o tamanho e a superfície de ataque.When a Dockerfile says FROM ubuntu:24.04, the container does not run Ubuntu as a system: it runs the host kernel with the Ubuntu file system on top (/bin, /etc, apt, glibc). There is no boot, no systemd, no login. The base you pick decides which tools and libraries exist inside, and therefore the size and the attack surface.

Medido no exemplo desta nota (o mesmo binário copiado para cada base, tamanho descomprimido de docker image inspect; varia com a versão e a arquitetura):Measured on this note's example (the same binary copied onto each base, uncompressed size from docker image inspect; varies with version and architecture):

Como decidirHow to decide

• Comece pela variante -slim (Debian) ou -alpine da imagem oficial da sua linguagem (node:22-slim, python:3.13-slim), em vez de partir de ubuntu e instalar o runtime. Já vem configurada, atualizada e menor.Start from the -slim (Debian) or -alpine variant of your language's official image (node:22-slim, python:3.13-slim) instead of starting from ubuntu and installing the runtime. It comes configured, maintained and smaller.
• Alpine quando o app roda bem em musl (Go, Node, a maioria dos apps Java e Python puros) e você quer uma base pequena. Cuidado com dependências nativas: se algo falhar com erros de biblioteca ou o pip install demorar para compilar, troque para -slim.Alpine when the app runs fine on musl (Go, Node, most Java and pure Python apps) and you want a small base. Mind native dependencies: if something fails with library errors or pip install takes forever compiling, switch to -slim.
• Ubuntu quando você precisa de pacotes específicos do apt, de compatibilidade máxima ou segue o padrão da empresa. Não é “errado”, só maior; mantenha-o enxuto (exemplo abaixo).Ubuntu when you need specific apt packages, maximum compatibility, or your company standard. It is not “wrong”, just larger; keep it lean (example below).
• Distroless ou scratch para produção de binários estáticos (Go, Rust) ou apps com runtime mínimo, geralmente como estágio final de um multi-stage.Distroless or scratch for production of static binaries (Go, Rust) or minimal-runtime apps, usually as the final stage of a multi-stage build.

# Ubuntu enxuto: um RUN so, sem recomendados, limpando o cache do apt na mesma camada
FROM ubuntu:24.04
RUN apt-get update \
 && apt-get install -y --no-install-recommends ca-certificates curl \
 && rm -rf /var/lib/apt/lists/* \
 && useradd --system --uid 10001 app
USER app

# Alpine equivalente
FROM alpine:3.22
RUN apk add --no-cache ca-certificates curl \
 && adduser -S -u 10001 app
USER app

Multi-stage build: levar para produção só o que rodaMulti-stage build: ship only what runs

Compilar um app exige compilador, cabeçalhos, gerenciador de pacotes, código-fonte e, às vezes, chaves de acesso a repositórios privados. Nada disso é necessário para executar o resultado, mas num Dockerfile de um estágio tudo fica na imagem final, pesando e dando ao atacante ferramentas prontas (um compilador, curl, apk). O multi-stage build usa vários FROM no mesmo arquivo: o primeiro estágio constrói, o último recebe só o artefato.Compiling an app needs a compiler, headers, a package manager, source code and sometimes access keys for private repositories. None of that is needed to run the result, but in a single-stage Dockerfile it all stays in the final image, adding weight and handing an attacker ready-made tools (a compiler, curl, apk). A multi-stage build uses several FROM lines in one file: the first stage builds, the last receives only the artifact.

# ---- estagio 1: compila (tem compilador, shell, apk; nada disso vai para o final)
FROM golang:1.25-alpine AS build
WORKDIR /src
COPY go.mod ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o /out/server .

# ---- estagio 2: so o binario, sem shell, sem apt/apk, usuario nao-root
FROM gcr.io/distroless/static-debian12:nonroot
COPY --from=build /out/server /server
EXPOSE 8080
HEALTHCHECK --interval=10s --timeout=3s --start-period=5s --retries=3 \
  CMD ["/server", "healthcheck"]
ENTRYPOINT ["/server"]

• AS build dá nome ao primeiro estágio; COPY --from=build traz de lá apenas o binário. Os outros arquivos do estágio 1 são descartados e não entram na imagem final nem nas suas camadas.AS build names the first stage; COPY --from=build brings over only the binary. The other files of stage 1 are discarded and do not enter the final image or its layers.
• CGO_ENABLED=0 gera um binário estático (não depende de glibc nem musl), o que permite rodar sobre a base mínima distroless/static ou até scratch (imagem vazia). -s -w remove símbolos de depuração e -trimpath tira caminhos da máquina de build.CGO_ENABLED=0 produces a static binary (depends on neither glibc nor musl), which lets it run on the minimal distroless/static base or even scratch (an empty image). -s -w strips debug symbols and -trimpath removes build-machine paths.
• A tag :nonroot da distroless já define USER 65532: o app não roda como root.The distroless :nonroot tag already sets USER 65532: the app does not run as root.
• Em linguagens interpretadas o desenho é o mesmo: estágio de build instala dependências de desenvolvimento e gera o bundle (npm run build, pip wheel); o final copia só dist/ ou o virtualenv para uma imagem -slim ou distroless do runtime (gcr.io/distroless/nodejs22-debian12).In interpreted languages the design is the same: the build stage installs development dependencies and produces the bundle (npm run build, pip wheel); the final one copies only dist/ or the virtualenv onto a -slim or distroless runtime image (gcr.io/distroless/nodejs22-debian12).
• É possível construir só um estágio com docker build --target build ., útil para rodar testes dentro do estágio de build.You can build just one stage with docker build --target build ., handy for running tests inside the build stage.

Reduzir a superfície de ataqueReducing the attack surface

Se alguém conseguir executar código dentro do seu contêiner (uma falha no app, uma dependência comprometida), o estrago depende do que existe lá dentro. Um shell permite navegar e rodar comandos; um curl baixa ferramentas; o root altera o que quiser; capacidades extras permitem mexer na rede. A estratégia é tirar tudo o que o app não usa, em camadas:If someone manages to execute code inside your container (a flaw in the app, a compromised dependency), the damage depends on what exists in there. A shell lets them roam and run commands; curl downloads tools; root can change anything; extra capabilities let them touch the network. The strategy is to remove everything the app does not use, in layers:

Na prática, as opções de execução ficam assim (e viram campos do Compose, veja adiante):In practice the run options look like this (and become Compose fields, see below):

docker run -d --name app \
  --read-only --tmpfs /tmp \
  --cap-drop ALL --security-opt no-new-privileges:true \
  --memory 128m --pids-limit 100 \
  -p 127.0.0.1:8080:8080 \
  meu-app:1.0

“Mas e se eu precisar de um terminal para depurar?”“But what if I need a terminal to debug?”

Em uma imagem sem shell, docker exec -it app sh falha de propósito:On an image with no shell, docker exec -it app sh fails on purpose:

$ docker exec -it app sh
OCI runtime exec failed: exec failed: unable to start container process: exec: "sh": executable file not found in $PATH

Isso é o objetivo, mas você ainda consegue investigar sem pôr ferramentas na imagem de produção: use docker logs e docker inspect; ou suba um contêiner de depuração descartável que compartilha a rede e os processos do alvo:That is the point, but you can still investigate without putting tools in the production image: use docker logs and docker inspect; or start a throwaway debug container that shares the network and processes of the target:

docker run --rm -it --network container:app --pid container:app nicolaka/netshoot
# dentro dele: ss -ltn, curl localhost:8080, ps aux (veem o alvo)

Outra opção é construir uma variante de depuração da mesma imagem (por exemplo, a tag :debug da distroless inclui um BusyBox) e usá-la só em desenvolvimento. O que não se faz é deixar o shell na imagem de produção “para o caso de precisar”.Another option is to build a debug variant of the same image (for example, the distroless :debug tag includes a BusyBox) and use it in development only. What you do not do is leave the shell in the production image “just in case”.

Mapeamento de portasPort mapping

Cada contêiner tem sua própria rede, e as portas dele não são visíveis fora até você publicá-las. O -p liga uma porta do host a uma porta do contêiner:Each container has its own network, and its ports are not visible outside until you publish them. -p ties a host port to a container port:

-p 8080:8080                  # host:contêiner  (escuta em TODAS as interfaces do host)
-p 127.0.0.1:8080:8080        # só a sua própria máquina acessa
-p 3000:8080                  # porta 3000 do host -> 8080 do contêiner
-p 8080                       # porta aleatória do host -> 8080 (veja com docker port)
-p 8080:8080/udp              # UDP em vez de TCP (o padrão é TCP)
-P                            # publica todas as portas do EXPOSE em portas aleatórias

• Ordem é HOST:CONTÊINER. A do contêiner é a que o app escuta (variável PORT); a do host é livre, mas dois contêineres não podem usar a mesma porta do host.The order is HOST:CONTAINER. The container side is the one the app listens on (the PORT variable); the host side is your choice, but two containers cannot use the same host port.
• EXPOSE no Dockerfile não publica nada: é documentação (e o que o -P usa). Quem abre a porta é o -p ou o campo ports do Compose.EXPOSE in the Dockerfile publishes nothing: it is documentation (and what -P uses). What opens the port is -p or the Compose ports field.
• Para conversa entre contêineres você não precisa publicar porta nenhuma: eles se falam pela rede interna, direto na porta do contêiner (veja redes). Publique só o que precisa ser acessado de fora, como a API ou um proxy reverso.For container-to-container traffic you do not need to publish any port: they talk over the internal network, straight to the container port (see networks). Publish only what must be reached from outside, like the API or a reverse proxy.
• Pergunte ao Docker o que está publicado: docker port app ou a coluna PORTS do docker ps.Ask Docker what is published: docker port app or the PORTS column of docker ps.

Redes e comunicação entre contêineresNetworks and container-to-container communication

O Docker cria redes virtuais e liga cada contêiner a uma ou mais. Os tipos que importam:Docker creates virtual networks and attaches each container to one or more. The types that matter:

DNS por nome: a regra mais importanteDNS by name: the most important rule

Numa rede criada pelo usuário (e em toda rede do Compose), o Docker roda um DNS interno: o nome do contêiner (ou do serviço) vira o endereço. O app não precisa saber o IP do banco, que muda a cada recriação; ele conecta em db:5432. Na rede bridge padrão isso não funciona, e é por isso que ela deve ser evitada.On a user-created network (and every Compose network), Docker runs an internal DNS: the container (or service) name becomes the address. The app does not need to know the database IP, which changes on every recreation; it connects to db:5432. On the default bridge network this does not work, which is why it should be avoided.

docker network create minha-rede
docker run -d --name db  --network minha-rede -e POSTGRES_PASSWORD=dev postgres:17-alpine
docker run --rm --network minha-rede alpine:3.22 nc -zv db 5432    # db (172.x.x.x:5432) open

docker network ls                       # redes existentes
docker network inspect minha-rede       # quem esta nela, sub-rede, IPs
docker network connect minha-rede app   # liga um contêiner existente a outra rede

• Dentro de um contêiner, localhost é ele mesmo. O erro mais comum é configurar o app com DB_HOST=localhost: ele procura o banco dentro de si. Use o nome do serviço (db).Inside a container, localhost is itself. The most common mistake is configuring the app with DB_HOST=localhost: it looks for the database inside itself. Use the service name (db).
• Entre contêineres vale a porta do contêiner, não a publicada. Se o Compose diz "5433:5432", os outros serviços usam db:5432; o 5433 é só para você, no host.Between containers the container port applies, not the published one. If Compose says "5433:5432", other services use db:5432; 5433 is only for you, on the host.
• Para o contêiner falar com algo no host (um banco rodando fora do Docker), use host.docker.internal (Docker Desktop; no Linux adicione extra_hosts: ["host.docker.internal:host-gateway"]).For a container to reach something on the host (a database running outside Docker), use host.docker.internal (Docker Desktop; on Linux add extra_hosts: ["host.docker.internal:host-gateway"]).
• Segmentação: contêineres só se enxergam se estiverem em uma rede em comum. Separe em frontend (proxy e API) e backend (API e banco): o proxy nunca alcança o banco. Marcar a rede como internal: true também corta a saída para a internet, o que impede um banco comprometido de “ligar para casa”.Segmentation: containers only see each other if they share a network. Split into frontend (proxy and API) and backend (API and database): the proxy never reaches the database. Marking the network internal: true also cuts outbound internet, which stops a compromised database from “phoning home”.

Volumes: dados que sobrevivemVolumes: data that survives

Como a camada gravável some com o contêiner, o que precisa persistir (arquivos do Postgres, uploads) fica fora dela:Since the writable layer vanishes with the container, whatever must persist (Postgres files, uploads) lives outside it:

docker volume ls
docker volume inspect dbdata            # onde fica no host
docker volume rm dbdata                 # APAGA os dados

Docker Compose: vários contêineres num arquivo YAMLDocker Compose: several containers in one YAML file

Subir app, banco e proxy com três docker run cheios de flags não escala. O Compose descreve tudo num compose.yaml (também aceita docker-compose.yml) e sobe com um comando. É declarativo, como o Kubernetes ou o Terraform, só que para uma máquina só.Starting app, database and proxy with three flag-heavy docker run commands does not scale. Compose describes everything in a compose.yaml (docker-compose.yml is also accepted) and starts it with one command. It is declarative, like Kubernetes or Terraform, only for a single machine.

services:
  app:
    build: .                              # constroi a imagem do ./Dockerfile
    ports:
      - "127.0.0.1:8080:8080"             # so a sua maquina acessa
    environment:
      DB_ADDR: db:5432                    # o NOME do servico e o host
    depends_on:
      db:
        condition: service_healthy        # so inicia quando o db estiver saudavel
    networks: [frontend, backend]
    restart: unless-stopped
    read_only: true
    cap_drop: [ALL]
    security_opt: ["no-new-privileges:true"]
    mem_limit: 128m
    logging:
      driver: json-file
      options: { max-size: "10m", max-file: "3" }

  db:
    image: postgres:17-alpine
    environment:
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password
    secrets: [db_password]
    volumes:
      - dbdata:/var/lib/postgresql/data
    networks: [backend]                   # sem "ports": ninguem de fora chega aqui
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 3s
      retries: 5
    restart: unless-stopped

networks:
  frontend:
  backend:
    internal: true                        # sem saida para a internet

volumes:
  dbdata:

secrets:
  db_password:
    file: ./db_password.txt

docker compose up -d --build     # constroi (se preciso) e sobe tudo em segundo plano
docker compose ps                # estado e saude de cada servico
docker compose logs -f app       # logs de um servico (sem o nome: de todos)
docker compose exec db psql -U postgres   # comando dentro de um servico rodando
docker compose config            # valida o YAML e mostra o resultado final
docker compose stop              # para sem apagar
docker compose down              # para e APAGA contêineres e redes (volumes ficam)
docker compose down -v           # idem, e apaga os volumes: os dados vao junto

Saúde do contêiner: HEALTHCHECKContainer health: HEALTHCHECK

“Contêiner rodando” só diz que o processo existe. Um app pode estar de pé e travado, sem conexão com o banco ou sem memória. O healthcheck é um comando que o Docker executa de tempos em tempos dentro do contêiner; o código de saída decide o estado: 0 saudável, 1 doente.“Container running” only says the process exists. An app can be up and stuck, with no database connection or out of memory. The healthcheck is a command Docker runs from time to time inside the container; the exit code decides the state: 0 healthy, 1 unhealthy.

# no Dockerfile
HEALTHCHECK --interval=10s --timeout=3s --start-period=5s --retries=3 \
  CMD ["/server", "healthcheck"]

# ou no Compose (sobrepoe o do Dockerfile)
healthcheck:
  test: ["CMD", "/server", "healthcheck"]
  interval: 10s
  timeout: 3s
  start_period: 5s
  retries: 3

Os estados são starting → healthy ou unhealthy, visíveis em docker ps (coluna STATUS) e em docker inspect:The states are starting → healthy or unhealthy, visible in docker ps (STATUS column) and in docker inspect:

$ docker compose ps
NAME        SERVICE   STATUS
lab-app-1   app       Up 12 seconds (healthy)
lab-db-1    db        Up 18 seconds (healthy)

$ docker inspect --format '{{.State.Health.Status}}' lab-app-1
healthy
$ docker inspect --format '{{json .State.Health.Log}}' lab-app-1   # ultimas execucoes e saidas

• O que o Docker faz com um contêiner unhealthy? Sozinho, nada: restart: unless-stopped só reage a um processo que saiu. O estado serve para o depends_on: service_healthy, para balanceadores e para orquestradores (Kubernetes, ECS, Swarm), que trocam a instância doente. Em um host único, alerte sobre ele (veja observabilidade) ou use uma ferramenta que reinicie por saúde.What does Docker do with an unhealthy container? By itself, nothing: restart: unless-stopped only reacts to a process that exited. The state serves depends_on: service_healthy, load balancers and orchestrators (Kubernetes, ECS, Swarm), which replace the sick instance. On a single host, alert on it (see observability) or use a tool that restarts on health.
• Teste algo que importa, mas barato. Um /health que só devolve 200 prova que o servidor HTTP responde. Um que também testa uma consulta simples ao banco prova mais, mas se o banco cair todas as instâncias ficam doentes ao mesmo tempo. Separe liveness (“estou vivo?”) de readiness (“posso receber tráfego?”) quando usar orquestrador.Test something that matters, but cheap. A /health that only returns 200 proves the HTTP server answers. One that also runs a simple database query proves more, but if the database goes down every instance turns sick at once. Separate liveness (“am I alive?”) from readiness (“can I take traffic?”) when you use an orchestrator.
• Imagens sem curl e sem shell (distroless, scratch) não conseguem rodar curl localhost/health. A saída é o próprio binário ter um modo de checagem, como no exemplo (/server healthcheck faz a requisição e sai com 0 ou 1). Em Alpine, wget -qO- http://127.0.0.1:8080/health (BusyBox) dispensa instalar o curl.Images with no curl and no shell (distroless, scratch) cannot run curl localhost/health. The way out is for the binary itself to have a check mode, as in the example (/server healthcheck makes the request and exits 0 or 1). On Alpine, wget -qO- http://127.0.0.1:8080/health (BusyBox) saves installing curl.

Logs e observabilidadeLogs and observability

A regra do contêiner é simples: o app escreve seus logs na saída padrão (stdout) e de erro (stderr), não em arquivos dentro dele. O Docker captura esses dois fluxos por um driver de log e deixa você ler com docker logs.The container rule is simple: the app writes its logs to standard output (stdout) and standard error (stderr), not to files inside it. Docker captures those two streams through a log driver and lets you read them with docker logs.

docker logs web                        # tudo
docker logs -f --tail 100 web          # ultimas 100 linhas e segue (Ctrl+C sai)
docker logs --since 10m -t web         # ultimos 10 min, com data/hora
docker compose logs -f --no-log-prefix app | jq 'select(.path == "/db")'   # filtra JSON

• Logue em JSON (uma linha por evento, como no exemplo: {"msg":"request","method":"GET","path":"/db"}). Texto livre é difícil de filtrar; JSON entra direto em jq, Loki ou Elasticsearch.Log in JSON (one line per event, as in the example: {"msg":"request","method":"GET","path":"/db"}). Free text is hard to filter; JSON feeds straight into jq, Loki or Elasticsearch.
• Sem rotação, o log enche o disco. O driver padrão (json-file) guarda tudo sem limite. Configure max-size e max-file (como no Compose acima) ou global em /etc/docker/daemon.json. O driver local já faz rotação por padrão.Without rotation, logs fill the disk. The default driver (json-file) keeps everything with no limit. Set max-size and max-file (as in the Compose above) or globally in /etc/docker/daemon.json. The local driver rotates by default.
• Não registre segredos nem dados pessoais: o log é copiado, indexado e guardado por meses. Veja Logging and alerting failures no OWASP Top 10.Do not log secrets or personal data: logs are copied, indexed and kept for months. See Logging and alerting failures in the OWASP Top 10.
• Para centralizar, um coletor (Grafana Alloy, Fluent Bit, Promtail) lê os logs dos contêineres e envia ao Loki/Elasticsearch; alternativamente, um driver como syslog, fluentd ou awslogs envia direto. Isso é montado passo a passo na nota de observabilidade.To centralise, a collector (Grafana Alloy, Fluent Bit, Promtail) reads the containers' logs and ships them to Loki/Elasticsearch; alternatively a driver such as syslog, fluentd or awslogs ships directly. This is built step by step in the observability note.

Além dos logs: o que olhar num contêinerBeyond logs: what to look at in a container

Resumindo: docker logs e docker stats resolvem o dia a dia numa máquina; assim que você tem vários contêineres ou hosts, precisa de métricas históricas e logs centralizados, senão só descobre o problema depois que o usuário reclama.In short: docker logs and docker stats cover day-to-day work on one machine; as soon as you have several containers or hosts you need historical metrics and centralised logs, or you only learn about the problem after the user complains.

Praticar na sua máquinaPractise on your machine

Pré-requisito: Docker com Compose v2 (docker version e docker compose version funcionando). Todos os comandos abaixo foram executados nesta ordem para escrever a nota. Cada atividade é pequena e usa a anterior.Prerequisite: Docker with Compose v2 (docker version and docker compose version working). Every command below was run in this order while writing the note. Each activity is small and builds on the previous one.

Atividade 0: criar os arquivosActivity 0: create the files

mkdir lab && cd lab
# arquivos: main.go  go.mod  .dockerignore  Dockerfile  compose.yaml  db_password.txt
echo "troque-esta-senha" > db_password.txt
printf 'db_password.txt\n' > .gitignore

main.go (o serviço de exemplo; a rota /db só abre uma conexão TCP com db:5432 para provar a rede, sem driver de banco):main.go (the example service; the /db route just opens a TCP connection to db:5432 to prove the network, no database driver):

package main

import (
	"encoding/json"
	"fmt"
	"log"
	"net"
	"net/http"
	"os"
	"time"
)

func main() {
	port := getenv("PORT", "8080")

	// Modo healthcheck: o proprio binario testa /health e sai com 0 ou 1.
	if len(os.Args) > 1 && os.Args[1] == "healthcheck" {
		c := http.Client{Timeout: 2 * time.Second}
		res, err := c.Get("http://127.0.0.1:" + port + "/health")
		if err != nil || res.StatusCode != 200 {
			os.Exit(1)
		}
		return
	}

	http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		host, _ := os.Hostname()
		fmt.Fprintf(w, "ola do container %s\n", host)
	})
	http.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintln(w, "ok")
	})
	// Prova a comunicacao entre containers: abre TCP para o banco pelo NOME do servico.
	http.HandleFunc("/db", func(w http.ResponseWriter, r *http.Request) {
		addr := getenv("DB_ADDR", "db:5432")
		conn, err := net.DialTimeout("tcp", addr, 2*time.Second)
		if err != nil {
			http.Error(w, "db inacessivel: "+err.Error(), http.StatusBadGateway)
			return
		}
		conn.Close()
		fmt.Fprintf(w, "db alcancavel em %s\n", addr)
	})

	logJSON("start", map[string]any{"port": port})
	log.Fatal(http.ListenAndServe(":"+port, logged(http.DefaultServeMux)))
}

func logged(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		if r.URL.Path != "/health" { // o healthcheck roda a cada 10 s; nao polui o log
			logJSON("request", map[string]any{"method": r.Method, "path": r.URL.Path})
		}
		next.ServeHTTP(w, r)
	})
}

func logJSON(msg string, fields map[string]any) {
	fields["msg"], fields["time"] = msg, time.Now().UTC().Format(time.RFC3339)
	b, _ := json.Marshal(fields)
	fmt.Println(string(b))
}

func getenv(k, def string) string {
	if v := os.Getenv(k); v != "" {
		return v
	}
	return def
}

# go.mod
module hello

go 1.25

O .dockerignore é o da seção do Dockerfile; o Dockerfile é o do multi-stage e o compose.yaml é o da seção do Compose. Para o contraste da próxima atividade, salve também o Dockerfile ingênuo como Dockerfile.naive.The .dockerignore is the one from the Dockerfile section; the Dockerfile is the multi-stage one and compose.yaml is the one from the Compose section. For the next activity's contrast, also save the naive Dockerfile as Dockerfile.naive.

Atividade 1: build ingênuo × multi-stageActivity 1: naive × multi-stage build

docker build -f Dockerfile.naive -t lab:naive .
docker build -t lab:final .
docker images lab
docker history lab:final            # poucas camadas, nenhuma com compilador

Resultado esperado: lab:naive com centenas de megabytes (452 MB nesta máquina) e lab:final com cerca de 15 MB. Rode o build de novo sem mudar nada e veja as linhas CACHED; depois mude uma linha do main.go e note que o go mod download continua em cache.Expected result: lab:naive at hundreds of megabytes (452 MB on this machine) and lab:final at about 15 MB. Run the build again without changes and watch the CACHED lines; then change one line of main.go and notice that go mod download stays cached.

Atividade 2: rodar, mapear porta, ler logsActivity 2: run, map a port, read logs

docker run -d --name app -p 127.0.0.1:8080:8080 lab:final
curl localhost:8080/                 # ola do container 3f2a...
curl localhost:8080/db               # 502: nao existe "db" nesta rede (ainda)
docker ps                            # STATUS: Up ... (healthy)
docker logs app                      # linhas JSON: start, request, request
docker stats --no-stream app         # poucos MB de memoria
docker stop app && docker rm app

Troque o mapeamento para -p 3000:8080 e acesse localhost:3000; depois use -e PORT=9090 -p 9090:9090 e veja que a porta do contêiner acompanha a variável.Change the mapping to -p 3000:8080 and reach localhost:3000; then use -e PORT=9090 -p 9090:9090 and see that the container port follows the variable.

Atividade 3: tentar abrir um terminalActivity 3: try to open a terminal

docker run -d --name app lab:final
docker exec -it app sh               # falha: "sh": executable file not found
docker exec app id                   # falha tambem: nao ha nem o comando id
docker inspect app --format '{{.Config.User}}'    # 65532 (nao e root)
docker top app -o user,pid,comm      # 65532  ...  server
docker rm -f app

# compare com uma base que tem tudo:
docker run --rm -it ubuntu:24.04 bash    # aqui voce teria shell, apt, e seria root
whoami                                   # root

Resultado esperado: na imagem final não há shell, gerenciador de pacotes nem root. Quem invadir o app encontra um único binário.Expected result: the final image has no shell, no package manager and no root. Whoever breaks into the app finds a single binary.

Atividade 4: app + banco com ComposeActivity 4: app + database with Compose

docker compose up -d --build
docker compose ps                    # db healthy primeiro, depois app healthy
curl localhost:8080/db               # db alcancavel em db:5432
docker compose logs app              # o app resolveu "db" pelo DNS do Docker
docker inspect lab-app-1 --format 'user={{.Config.User}} ro={{.HostConfig.ReadonlyRootfs}} caps={{.HostConfig.CapDrop}}'
# user=65532 ro=true caps=[ALL]

Repare na ordem: o Compose esperou o Postgres ficar healthy antes de iniciar o app (service_healthy). Sem isso, o app subiria antes do banco aceitar conexões.Notice the order: Compose waited for Postgres to be healthy before starting the app (service_healthy). Without it the app would start before the database accepts connections.

Atividade 5: provar o isolamento da redeActivity 5: prove the network isolation

# 1) o banco NAO tem porta publicada: PORTS mostra so "5432/tcp", sem "0.0.0.0:"
docker compose ps db
ss -ltn | grep 5432                  # nada escutando no host

# 2) a rede backend e interna: quem esta so nela nao sai para a internet
docker run --rm --network lab_backend alpine:3.22 wget -qO- -T2 http://example.com
# wget: bad address 'example.com'

# 3) mas dentro da rede os nomes resolvem
docker run --rm --network lab_backend alpine:3.22 wget -qO- -T2 http://app:8080/db
# db alcancavel em db:5432

O nome da rede é <pasta>_<rede>: se sua pasta não se chama lab, veja o nome real em docker network ls.The network name is <folder>_<network>: if your folder is not called lab, see the real name in docker network ls.

Atividade 6: derrubar o banco e observarActivity 6: take the database down and observe

docker compose stop db
curl -i localhost:8080/db            # 502 Bad Gateway: db inacessivel
docker compose logs --no-log-prefix app | jq .     # cada requisicao como JSON
docker compose start db
curl localhost:8080/db               # volta a responder
docker events --since 2m --filter type=container   # start, die, health_status...

Desafio: coloque healthcheck no app que também chama /db (um modo healthcheck que testa o banco) e veja o estado do app virar unhealthy quando o banco cai. Depois discuta: isso é desejável? (Dica: leia o texto sobre liveness e readiness.)Challenge: give the app a healthcheck that also calls /db (a healthcheck mode that tests the database) and watch the app turn unhealthy when the database goes down. Then discuss: is that desirable? (Hint: re-read the liveness and readiness text.)

Atividade 7: limpar tudoActivity 7: clean up

docker compose down -v               # contêineres, redes e o volume dbdata
docker rmi lab:naive lab:final
docker system df                     # confira o que sobrou
docker system prune                  # apaga o que esta parado e sem uso

Para ir alémGoing further

1. Escaneie a imagem: docker run --rm -v /var/run/docker.sock:/var/run/docker.sock aquasec/trivy image lab:final (ou docker scout cves lab:final) e compare o número de vulnerabilidades com a variante Ubuntu. Note que aqui você montou o socket de propósito, num contêiner descartável de ferramenta confiável; é o tipo de exceção que deve ser consciente.Scan the image: docker run --rm -v /var/run/docker.sock:/var/run/docker.sock aquasec/trivy image lab:final (or docker scout cves lab:final) and compare the number of vulnerabilities with the Ubuntu variant. Note that you mounted the socket on purpose here, in a throwaway container of a trusted tool; that is the kind of exception that should be a conscious one.
2. Reverse proxy: adicione um serviço caddy ou nginx na rede frontend, publique só a porta dele e remova o ports do app.Reverse proxy: add a caddy or nginx service on the frontend network, publish only its port and remove the app's ports.
3. Tag por digest: troque o FROM por gcr.io/distroless/static-debian12:nonroot@sha256:… (veja o digest com docker buildx imagetools inspect) e entenda por que isso torna o build reproduzível.Pin by digest: change the FROM to gcr.io/distroless/static-debian12:nonroot@sha256:… (see the digest with docker buildx imagetools inspect) and understand why that makes the build reproducible.
4. Observabilidade: acrescente Prometheus, Grafana e Loki como na nota de observabilidade e leve os logs JSON deste app para o Grafana.Observability: add Prometheus, Grafana and Loki as in the observability note and ship this app's JSON logs to Grafana.
5. Para produção em mais de uma máquina: publique a imagem num registry e rode no ECS ou no Kubernetes; os conceitos de imagem, porta, healthcheck e variáveis são os mesmos.For production on more than one machine: push the image to a registry and run it on ECS or Kubernetes; the concepts of image, port, healthcheck and variables are the same.

Quando algo dá erradoWhen something goes wrong

Cola e revisãoCheat sheet and review

ColaCheat sheet

Perguntas de revisãoReview questions

• Por que um contêiner sobe em milissegundos e uma VM não? O que eles compartilham com o host?Why does a container start in milliseconds and a VM does not? What do they share with the host?
• Apagar o contêiner apaga a imagem? E os dados gravados dentro dele? Onde você os guardaria?Does deleting the container delete the image? And the data written inside it? Where would you keep it?
• Por que CMD ["/server"] é melhor que CMD /server para o docker stop?Why is CMD ["/server"] better than CMD /server for docker stop?
• Quando você escolheria Alpine, -slim, Ubuntu e distroless? Dê um exemplo de dependência que quebra no Alpine.When would you choose Alpine, -slim, Ubuntu and distroless? Give an example of a dependency that breaks on Alpine.
• Por que apagar um arquivo em um RUN posterior não reduz a imagem? Como o multi-stage resolve isso?Why does deleting a file in a later RUN not shrink the image? How does multi-stage solve it?
• Liste cinco medidas que reduzem a superfície de ataque de um contêiner e o que cada uma impede.List five measures that reduce a container's attack surface and what each prevents.
• O que -p 5433:5432 faz? Que porta um outro contêiner usa para falar com esse banco? E por que publicar o banco pode abrir a internet mesmo com o UFW ativo?What does -p 5433:5432 do? Which port does another container use to talk to that database? And why can publishing the database open it to the internet even with UFW enabled?
• Por que DB_HOST=localhost falha dentro de um contêiner? O que usar no lugar?Why does DB_HOST=localhost fail inside a container? What to use instead?
• O que o Docker faz quando um contêiner fica unhealthy? E o que muda num orquestrador?What does Docker do when a container turns unhealthy? And what changes in an orchestrator?
• Seu contêiner morreu com código 137. Quais são as duas causas prováveis e como diferenciá-las?Your container died with exit code 137. What are the two likely causes and how do you tell them apart?