Skip to content

Docker Folha de referência

Plataforma para desenvolver, distribuir e executar aplicações em contêineres.

01

Primeiros passos

Comandos básicos

docker run cria e inicia um contêiner. -d roda em segundo plano, -p mapeia a porta do host para a porta do contêiner. pull baixa imagens de um registry (Docker Hub por padrão).

docker
# check version
docker --version

# pull an image
docker pull nginx:latest

# run a container
docker run -d --name mynginx -p 8080:80 nginx

# list running containers
docker ps

# list all containers (including stopped)
docker ps -a

# stop and remove a container
docker stop mynginx
docker rm mynginx

# list images
docker images

Ciclo de vida do contêiner

create + start é o que o run faz por baixo dos panos. stop envia SIGTERM para desligar graciosamente; kill envia SIGKILL imediatamente. pause usa o cgroup freezer — útil para snapshots sem parar o processo.

docker
# create a container without starting it
docker create --name web nginx

# start a created (or stopped) container
docker start web

# stop gracefully (SIGTERM then SIGKILL after 10s)
docker stop web

# force kill immediately
docker kill web

# restart a container
docker restart web

# pause/resume (freezes process with cgroups)
docker pause web
docker unpause web

Básico de imagens

Imagens são camadas somente leitura. rmi falha se um contêiner ainda referencia a imagem — remova o contêiner primeiro. history mostra cada instrução que criou uma camada e seu tamanho, útil para otimizar builds.

docker
# list local images
docker images
docker image ls

# remove an image
docker rmi nginx:latest
docker image rm nginx

# remove all dangling (untagged) images
docker image prune

# remove all unused images
docker image prune -a

# show image history (each layer)
docker history nginx:latest

Informações do sistema

docker info mostra a configuração do daemon: storage driver, runtime, registries, status do swarm. system df revela o espaço recuperável — imagens dangling e contêineres parados desperdiçam disco. A flag --format usa Go templates para saída estruturada.

docker
# docker system-wide info
docker info
docker version

# disk usage breakdown (images, containers, volumes)
docker system df

# detailed disk usage with reclaimable space
docker system df -v

# running containers count
docker ps -q | wc -l

# show docker root directory and storage driver
docker info --format '{{.DockerRootDir}} {{.Driver}}'

Limpeza e prune

prune remove com segurança recursos parados/dangling. system prune -a também remove imagens não referenciadas por nenhum contêiner. Adicionar --volumes apaga volumes não usados por nenhum contêiner — perda de dados irreversível, use com cuidado em produção.

docker
# remove stopped containers
docker container prune

# remove dangling images
docker image prune

# remove unused volumes (CAUTION: data loss)
docker volume prune

# remove unused networks
docker network prune

# remove everything unused at once
docker system prune

# also remove volumes (very aggressive)
docker system prune -a --volumes

Obtendo ajuda

O Docker agrupa comandos em namespaces de gerenciamento (docker image, docker container, docker network, docker volume). Tanto a forma antiga (docker rmi) quanto a nova (docker image rm) funcionam. --help em qualquer subcomando mostra as flags e o uso.

docker
# list all commands
docker --help
docker help

# help for a specific command
docker run --help
docker image --help

# list management commands (grouped)
docker image --help
docker container --help
docker network --help

# show daemon config
docker info

# command reference online
# https://docs.docker.com/reference/
02

Gerenciamento de imagens

Baixando imagens

Tags são rótulos mutáveis — a mesma tag pode apontar para imagens diferentes ao longo do tempo. Para deploys reproduzíveis, fixe pelo digest (@sha256:...). Baixar com --platform permite buscar uma imagem de outra arquitetura, útil para builds ARM em hosts x86.

docker
# pull latest tag
docker pull nginx

# pull specific tag
docker pull nginx:1.25-alpine

# pull all tags of a repository
docker pull -a alpine

# pull from a different registry
docker pull ghcr.io/user/repo:tag

# pull by digest (immutable, reproducible)
docker pull nginx@sha256:abc123...

# pull multiple platforms (multi-arch)
docker pull --platform linux/arm64 nginx

Construindo imagens

O ponto final . é o build context — os arquivos enviados ao daemon. Mantenha-o pequeno com .dockerignore para acelerar os builds. --no-cache força camadas novas ao depurar. O BuildKit habilita cache multi-stage, mounts SSH e montagem de secrets.

docker
# build from Dockerfile in current dir, tag it
docker build -t myapp:1.0 .

# build with a different Dockerfile name
docker build -f Dockerfile.prod -t myapp:prod .

# build with build args
docker build --build-arg VERSION=1.2.3 -t myapp .

# build with no cache
docker build --no-cache -t myapp .

# build for a different platform
docker build --platform linux/arm64 -t myapp:arm .

# build using BuildKit (advanced features)
DOCKER_BUILDKIT=1 docker build -t myapp .

Etiquetando imagens

Tags são aliases que apontam para o mesmo image ID. Um fluxo comum: build com uma tag de versão e depois adicionar as tags latest e de versão principal. Etiquetar com a URL de um registry prepara a imagem para o push para esse registry.

docker
# tag a local image
docker tag myapp:1.0 myapp:latest

# tag for pushing to Docker Hub
docker tag myapp:1.0 username/myapp:1.0

# tag for a private registry
docker tag myapp:1.0 registry.local:5000/myapp:1.0

# tag with multiple tags at once
docker tag myapp:1.0 myapp:stable
docker tag myapp:1.0 myapp:1

# tag by digest reference
docker tag myapp@sha256:abc... myapp:pinned

Enviando imagens

Você precisa etiquetar a imagem com o destino no registry antes do push. push envia apenas as camadas que ainda não existem no registry. Para registries privados com certificados autoassinados, configure o daemon em /etc/docker/daemon.json com insecure-registries.

docker
# login to Docker Hub
docker login

# login to a private registry
docker login registry.local:5000 -u user -p pass

# push to Docker Hub
docker push username/myapp:1.0

# push all tags in a repository
docker push -a username/myapp

# push to private registry
docker push registry.local:5000/myapp:1.0

# logout when done
docker logout

Inspecionando imagens

inspect retorna um JSON detalhado: arquitetura, SO, camadas, env, entrypoint, config. history revela o comando e o tamanho de cada camada — a base da otimização de imagens. manifest inspect consulta um registry remoto sem fazer pull.

docker
# low-level image metadata (JSON)
docker inspect nginx:latest

# specific field via Go template
docker inspect --format '{{.Arch}} {{.Os}}' nginx

# show image layers and sizes
docker history nginx:latest

# no-trunc to see full command for each layer
docker history --no-trunc nginx:latest

# inspect an image in a registry (manifest)
docker manifest inspect nginx:latest

Salvando e carregando imagens

save/load preserva as camadas e o histórico da imagem — a escolha certa para transferir imagens offline. export/import achata tudo numa única camada, perdendo o histórico. Para transferência online, prefira push/pull no registry a arquivos tar.

docker
# save an image to a tar file
docker save -o myapp.tar myapp:1.0

# save multiple images
docker save -o bundle.tar myapp:1.0 nginx:latest

# load an image from a tar file
docker load -i myapp.tar

# pipe between hosts (no intermediate file)
docker save myapp:1.0 | gzip | ssh host 'gunzip | docker load'

# export a container filesystem (not an image)
docker export mycontainer | gzip > fs.tar.gz
03

Gerenciamento de contêineres

Executando contêineres

-it combina -i (mantém o stdin aberto) e -t (aloca um tty) para sessões interativas. --rm faz a limpeza após a saída — ideal para comandos pontuais. --restart unless-stopped sobrevive a reinicializações mas respeita paradas manuais.

docker
# run in background with a name and port mapping
docker run -d --name web -p 8080:80 nginx

# run interactively with a terminal
docker run -it --name shell alpine sh

# run and auto-remove on exit
docker run --rm alpine echo hello

# run with a volume
docker run -d -v mydata:/data alpine

# run with environment variables
docker run -d -e MYSQL_ROOT_PASSWORD=secret mysql

# run with a restart policy
docker run -d --restart unless-stopped nginx

Executando comandos (exec)

exec roda um novo processo dentro de um contêiner já em execução — o entrypoint original continua rodando. Use para depurar, tarefas administrativas ou scripts pontuais. O usuário padrão é o USER da imagem; sobrescreva com -u.

docker
# open an interactive shell in a running container
docker exec -it web sh

# run a command and return
docker exec web ls /usr/share/nginx/html

# run as a specific user
docker exec -u root web whoami

# set environment variables for the command
docker exec -e DEBUG=1 web env

# run with a working directory
docker exec -w /tmp web pwd

# run as detached (rarely useful)
docker exec -d web touch /tmp/marker

Vendo logs

logs mostra o stdout/stderr capturado pelo logging driver do contêiner. As aplicações devem logar no stdout, não em arquivos, para integrar com docker logs. --since/--until aceitam timestamps RFC3339 ou durações Go (30m, 2h).

docker
# follow (tail) logs
docker logs -f web

# show last 100 lines
docker logs --tail 100 web

# show logs since a timestamp
docker logs --since 2024-01-01T00:00:00 web

# show logs from the last 30 minutes
docker logs --since 30m web

# add timestamps to each line
docker logs -t web

# show logs for a specific timeframe
docker logs --since 10m --until 5m web

Inspeção de contêineres

inspect retorna um JSON rico cobrindo config, state, network e mounts. Go templates extraem campos específicos — extremamente útil para scripts. O LogPath revela onde o driver json-file guarda os logs no host.

docker
# full JSON metadata
docker inspect web

# container IP address
docker inspect --format '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' web

# container log path (json-file driver)
docker inspect --format '{{.LogPath}}' web

# mounts and volumes
docker inspect --format '{{json .Mounts}}' web

# container state (running, exited, etc.)
docker inspect --format '{{.State.Status}} {{.State.ExitCode}}' web

# all container ports
docker inspect --format '{{json .NetworkSettings.Ports}}' web

Iniciando, parando e reiniciando

start retoma um contêiner parado com sua configuração original. update modifica as restrições e a política de reinício de um contêiner em execução sem recriá-lo — útil para apertar limites de recursos em produção.

docker
# start a stopped container
docker start web

# stop with a custom timeout (seconds)
docker stop -t 30 web

# restart (keeps container intact)
docker restart web

# rename a container
docker rename web webserver

# update container config (e.g. restart policy)
docker update --restart unless-stopped web

# pause/resume (cgroup freezer)
docker pause web
docker unpause web

Copiando arquivos

cp funciona nos dois sentidos e em contêineres parados — prático para injetar hotfixes ou extrair logs. Não foi feito para sincronização de alta frequência; use bind mount ou volume para fluxos de desenvolvimento. O truque tar+exec transfere árvores grandes com eficiência.

docker
# copy a file from host to container
docker cp file.txt web:/tmp/

# copy from container to host
docker cp web:/etc/nginx/nginx.conf ./nginx.conf

# copy a directory
docker cp ./app web:/usr/src/app

# copy with archive mode (preserves perms)
docker cp -a ./config web:/etc/app

# copy to a stopped container (works too)
docker cp script.sh web:/script.sh

# tar stream from host to container stdin
docker exec -i web tar xzf - -C /app < app.tar.gz
04

Básico do Dockerfile

FROM — imagem base

FROM é a primeira instrução e define a camada base. Escolha bases mínimas (alpine, distroless, scratch) para reduzir a superfície de ataque e o tamanho. Fixar pelo digest garante builds reproduzíveis, já que tags podem mudar.

docker
# use an official base image
FROM ubuntu:22.04

# pin a specific digest for reproducibility
FROM ubuntu@sha256:abc123def...

# multi-arch build (buildx picks the host arch)
FROM --platform=$BUILDPLATFORM golang:1.21 AS builder

# use a minimal image
FROM alpine:3.18

# scratch = empty image, for static binaries
FROM scratch

# use a previous build stage
FROM builder AS final

RUN — executar comandos

Cada RUN cria uma camada. Combine comandos relacionados com && e limpe na mesma camada para manter as imagens pequenas. A forma exec (array JSON) não invoca um shell, então sem expansão de variáveis ou encadeamento — mas lida corretamente com sinais.

docker
# install packages
RUN apt-get update && apt-get install -y curl

# clean up in the same layer to reduce size
RUN apt-get update && apt-get install -y --no-install-recommends curl \
    && rm -rf /var/lib/apt/lists/*

# combine commands with && to reduce layers
RUN mkdir -p /app/config && chown 1000:1000 /app/config

# use exec form (preferred) to ensure signals
RUN ["npm", "install"]

# use a shell for variables and chaining
RUN VERSION=1.0 && wget https://example.com/v${VERSION}.tar.gz

COPY e ADD

COPY é o preferido para arquivos locais — é explícito e previsível. ADD adiciona mágicas: buscar URLs e autoextração de arquivos tar/zip. Essas mágicas podem surpreender; recorra ao ADD só quando precisar de extração. Ambos criam uma camada.

docker
# copy a file into the image
COPY package.json /app/

# copy a directory
COPY src/ /app/src/

# copy with ownership
COPY --chown=node:node package.json /app/

# copy from a previous build stage
COPY --from=builder /app/dist /app/dist

# ADD can fetch URLs and extract archives
ADD https://example.com/app.tar.gz /tmp/

# ADD extracts local tar archives automatically
ADD app.tar.gz /usr/src/

WORKDIR

WORKDIR define o diretório de trabalho para as instruções seguintes e o padrão do contêiner. Ele cria o diretório se não existir. Sempre prefira WORKDIR a cd no RUN — cd não persiste entre camadas. Use caminhos absolutos para clareza.

docker
# set the working directory
WORKDIR /usr/src/app

# subsequent RUN, CMD, COPY use this dir
COPY . .
RUN npm install

# WORKDIR creates the directory if it does not exist
WORKDIR /opt/data/logs

# use a relative path (relative to previous WORKDIR)
WORKDIR sub

# avoid this anti-pattern (use absolute paths)
WORKDIR /app
RUN cd /app && do_something   # cd is lost after RUN

USER

USER define o usuário (e opcionalmente o grupo) para RUN, CMD e ENTRYPOINT. Rodar como não-root é uma prática essencial de segurança. O usuário precisa existir na imagem. UIDs numéricos são portáveis entre imagens e evitam problemas de busca por nome.

docker
# create a non-root user and switch to it
RUN groupadd -r app && useradd -r -g app appuser
USER appuser

# run subsequent instructions as this user
RUN whoami   # appuser

# use a numeric UID for portability
USER 1000

# USER in compose/runtime overrides this
USER 1000:1000

# common pattern: node image ships a 'node' user
FROM node:20-alpine
USER node

.dockerignore

.dockerignore reduz o build context enviado ao daemon — builds mais rápidos, contexto menor e evita que secrets como .env vazem para as camadas da imagem. Usa sintaxe parecida com a do .gitignore. Sempre exclua node_modules e artefatos de build que são recriados durante o build.

docker
# .dockerignore — exclude files from the build context

# version control
.git
.gitignore

# dependencies (fetched inside the image)
node_modules
npm-debug.log

# build artifacts
dist
build
*.log

# local env files (NEVER bake secrets)
.env
.env.local

# docker files themselves
Dockerfile
docker-compose*.yml

# OS files
.DS_Store
Thumbs.db
05

Dockerfile avançado

CMD vs ENTRYPOINT

ENTRYPOINT define o executável; CMD fornece argumentos padrão que podem ser sobrescritos. Use a forma exec (array JSON) para que o processo receba os sinais diretamente — a forma shell embrulha o comando em /bin/sh -c, quebrando o desligamento gracioso. Padrão comum: script no ENTRYPOINT + args padrão no CMD.

docker
# CMD: default command, easily overridden
CMD ["nginx", "-g", "daemon off;"]

# override at runtime
# docker run myimage nginx -v

# ENTRYPOINT: fixed command, CMD becomes args
ENTRYPOINT ["nginx"]
CMD ["-g", "daemon off;"]

# runtime args append to ENTRYPOINT
# docker run myimage -v  ->  nginx -v

# shell form (avoid — no signal handling)
CMD nginx -g "daemon off;"

# script as entrypoint that accepts args
ENTRYPOINT ["./entrypoint.sh"]
CMD ["--help"]

ENV — variáveis de ambiente

ENV cria variáveis no nível da imagem, visíveis no build e em runtime. Use ARG para valores só de build e evite vazar configuração para a imagem final. Em CMD/ENTRYPOINT na forma exec, ${VAR} não é expandido pelo shell — embrulhe com sh -c para expandir.

docker
# set a persistent env var (baked into image)
ENV NODE_ENV=production
ENV PATH=/app/node_modules/.bin:$PATH

# use in subsequent RUN instructions
ENV VERSION=1.2.3
RUN wget https://example.com/v${VERSION}.tar.gz

# multiple in one line
ENV NODE_ENV=production PORT=3000 LOG_LEVEL=info

# override at runtime
# docker run -e NODE_ENV=development myapp

# view env vars of a container
docker exec web env

# reference env vars in CMD
ENV APP_PORT=3000
CMD ["sh", "-c", "node server.js ${APP_PORT}"]

ARG — argumentos de build

Valores de ARG existem só durante o build do stage que os declara. Não persistem no contêiner em runtime — use ENV para levar um valor ao runtime. ARGs declarados antes do FROM são 'globais' mas precisam ser redeclarados em cada stage para serem usados lá.

docker
# declare a build argument with a default
ARG VERSION=latest
FROM base:${VERSION}

# use ARG only during build (not at runtime)
ARG NODE_ENV=production
RUN echo "Building for ${NODE_ENV}"

# multi-stage: ARG must be redeclared per stage
ARG VERSION
FROM base:${VERSION}
ARG VERSION
RUN echo ${VERSION}

# pass at build time
# docker build --build-arg VERSION=1.0 .

# ARG not available in CMD (use ENV to pass through)
ARG PORT=3000
ENV PORT=${PORT}
CMD ["sh", "-c", "serve --port ${PORT}"]

EXPOSE

EXPOSE é documentação — não publica portas. A publicação acontece com -p (host:container) em runtime ou ports: no Compose. EXPOSE ajuda as ferramentas a entender as portas pretendidas e habilita link automático em redes legadas.

docker
# document which port the container listens on
EXPOSE 80

# expose multiple ports
EXPOSE 80 443

# expose with protocol
EXPOSE 53/udp

# EXPOSE does NOT publish the port
# you still need -p at runtime
# docker run -p 8080:80 myapp

# in compose, expose vs ports
# expose: only to linked services
# ports: published to the host

# view exposed ports
docker inspect --format '{{json .Config.ExposedPorts}}' myapp

LABEL e metadados

LABEL anexa metadados chave-valor às imagens. Adote os labels OCI org.opencontainers.image.* para interoperabilidade com registries e ferramentas. Labels são úteis para rastrear versão, fonte, licenciamento e informações de build de CI.

docker
# add a label (key=value metadata)
LABEL maintainer="[email protected]"
LABEL version="1.0"
LABEL description="My web app"

# multiple labels in one instruction
LABEL org.opencontainers.image.title="myapp" \
      org.opencontainers.image.version="1.0" \
      org.opencontainers.image.source="https://github.com/me/myapp"

# view labels
docker inspect --format '{{json .Config.Labels}}' myapp

# filter images by label
docker images --filter "label=version=1.0"

# deprecated: MAINTAINER (use LABEL maintainer instead)
# MAINTAINER Alice <[email protected]>

VOLUME no Dockerfile

VOLUME declara um ponto de montagem; o Docker cria um volume anônimo na primeira execução, a menos que você monte um caminho do host. Sinaliza que o diretório guarda dados com estado. Uma pegadinha: declarar VOLUME depois do COPY pode sombrear seus arquivos copiados com um volume vazio.

docker
# declare an anonymous volume mount point
VOLUME /data

# multiple mount points
VOLUME /data /config /logs

# at runtime, Docker creates an anonymous volume
# docker run -v mydata:/data myapp  (named instead)

# VOLUME in Dockerfile: any files copied to /data
# are copied into the new anonymous volume on first run

# inspect volumes
docker inspect --format '{{json .Mounts}}' myapp

# avoid: VOLUME after COPY can hide your data
COPY ./config /config
VOLUME /config   # new empty volume shadows /config
06

Builds multi-stage

Multi-stage básico

Builds multi-stage copiam apenas os artefatos finais para a imagem de runtime — ferramentas de build, código-fonte e dependências de dev ficam no stage de builder. Resultado: uma imagem de runtime minúscula e segura. Nomeie os stages com AS para referenciá-los em COPY --from.

docker
# stage 1: build
FROM node:20 AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# stage 2: runtime (small)
FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

Selecionando um stage de build

--target faz o build só até o stage nomeado, pulando os stages seguintes. Isso permite um único Dockerfile para dev, teste e produção: target 'test' para CI, 'final' para produção. O BuildKit paraleliza stages independentes automaticamente.

docker
# build only up to a named stage
# docker build --target builder -t myapp:dev .

FROM node:20 AS builder
RUN npm ci && npm run build

FROM node:20-alpine AS test
COPY --from=builder /app /app
RUN npm test

FROM nginx:alpine AS final
COPY --from=builder /app/dist /usr/share/nginx/html

# target a specific stage
# docker build --target test .

Imagens de runtime enxutas

Para binários estáticos (Go, Rust), scratch produz a menor imagem possível, com zero superfície de ataque. Adicione certificados CA para HTTPS. Distroless oferece uma base mínima com CAs raiz e usuário não-root, ideal para linguagens dinâmicas ou quando você quer um runtime sem shell.

docker
# build stage
FROM golang:1.21 AS builder
WORKDIR /src
COPY . .
RUN CGO_ENABLED=0 go build -o app -ldflags="-s -w" .

# scratch = empty image, only the static binary
FROM scratch
COPY --from=builder /src/app /app
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
ENTRYPOINT ["/app"]

# result: ~10MB image
# or use distroless for a minimal OS base
FROM gcr.io/distroless/static
COPY --from=builder /src/app /app
ENTRYPOINT ["/app"]

Padrão builder para linguagens compiladas

Compile numa imagem completa de SDK e copie o artefato para uma imagem só de runtime (JRE). Isso encolhe drasticamente a imagem (JDK ~600MB vs JRE ~200MB) e remove as ferramentas de build da produção. Pré-baixar dependências antes do COPY melhora o cache de camadas.

docker
# stage 1: compile
FROM maven:3.9 AS builder
WORKDIR /build
COPY pom.xml .
RUN mvn dependency:go-offline
COPY src ./src
RUN mvn package -DskipTests

# stage 2: runtime with only the JRE
FROM eclipse-temurin:21-jre-alpine
COPY --from=builder /build/target/*.jar /app/app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "/app/app.jar"]

# benefits: no JDK, no source, no Maven cache in runtime

Copiando de imagens externas

COPY --from pode puxar de qualquer imagem — útil para montar ferramentas de várias bases sem um stage de build. Stages também podem ser referenciados por índice (base 0), mas nomear com AS é mais claro. Fixe imagens externas por digest para reprodutibilidade.

docker
# copy a binary from another image (no build stage needed)
FROM alpine:3.18
COPY --from=nginx:alpine /usr/sbin/nginx /usr/sbin/nginx
COPY --from=nginx:alpine /etc/nginx /etc/nginx
RUN apk add --no-cache libpcre2
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

# use a specific digest for reproducibility
COPY --from=redis:7@sha256:abc... /usr/local/bin/redis-server /usr/local/bin/

# copy from a built stage referenced by index
COPY --from=0 /build/output /app

Recursos do BuildKit

O BuildKit habilita cache mounts (caches de npm/pip persistem entre builds sem inflar a imagem), secret mounts (credenciais nunca tocam uma camada), encaminhamento SSH para repositórios privados e sintaxe heredoc para RUN multilinha mais limpos. Adicione a diretiva # syntax para fixar a versão do frontend do Dockerfile.

docker
# enable BuildKit
# DOCKER_BUILDKIT=1 docker build .

# syntax directive for latest frontend
# syntax=docker/dockerfile:1
FROM alpine

# mount a cache (persists across builds, not in image)
RUN --mount=type=cache,target=/root/.npm npm ci

# mount a secret (never written to layers)
RUN --mount=type=secret,id=npmrc,target=/root/.npmrc npm ci

# mount an SSH socket for private repos
RUN --mount=type=ssh git clone [email protected]:me/repo.git

# heredoc for multi-line scripts
RUN <<EOF
set -ex
apk add --no-cache curl
mkdir -p /app/data
EOF
07

Volumes

Criando e usando volumes

Volumes nomeados são gerenciados pelo Docker e são a forma recomendada de persistir dados. Sobrevivem à remoção do contêiner e são independentes do layout do sistema de arquivos do host. O sufixo :ro monta somente leitura. inspect revela o caminho em disco em /var/lib/docker/volumes.

docker
# create a named volume
docker volume create mydata

# use it in a container
docker run -d -v mydata:/data alpine sh -c "sleep 1h"

# inspect the volume
docker volume inspect mydata

# mount read-only
docker run -v mydata:/data:ro alpine ls /data

# mount with a different filesystem (e.g. tmpfs)
docker run --tmpfs /cache alpine

# default volume driver: local
docker volume create --driver local mydata

Listando e inspecionando volumes

ls lista os volumes nomeados; inspect mostra o driver e o mountpoint. Para descobrir quais contêineres usam um volume, filtre o ps por volume. Volumes ficam em /var/lib/docker/volumes/<name>/_data em hosts Linux — acesse via docker exec, não editando o host diretamente.

docker
# list all volumes
docker volume ls

# filter by name
docker volume ls -q --filter name=mydata

# show volume details (driver, mountpoint, options)
docker volume inspect mydata

# find the on-disk path
docker volume inspect --format '{{.Mountpoint}}' mydata

# find containers using a volume
docker ps -a --filter volume=mydata --format '{{.Names}}'

# check volume disk usage
docker system df -v | grep mydata

Drivers de volume

O driver local suporta NFS, dispositivos de bloco e tmpfs via opções de mount. Para armazenamento em nuvem (EBS, Azure Disk), use um driver plugin. Drivers abstraem o armazenamento, então contêineres se movem entre hosts sem mudar o comando run — chave para Swarm/Kubernetes.

docker
# local driver (default, on host disk)
docker volume create --driver local mydata

# NFS volume
docker volume create --driver local \
  --opt type=nfs \
  --opt o=addr=10.0.0.5,rw \
  --opt device=:/export/data nfsvol

# tmpfs (in-memory, ephemeral)
docker run --tmpfs /cache alpine

# block device
docker volume create --driver local \
  --opt type=ext4 \
  --opt device=/dev/sdb1 blockvol

# third-party drivers (e.g. cloud)
docker volume create --driver rexray/ebs ebsvol

Fazendo backup de volumes

Faca backup de um volume montando o volume e um diretório do host num contêiner temporário e depois gerando um tar do conteúdo. A restauração inverte o processo. Esse padrão funciona para qualquer driver de volume e é a base de scripts de backup automatizados.

docker
# back up a volume to a tar file
docker run --rm -v mydata:/data -v $(pwd):/backup alpine \
  tar czf /backup/mydata.tar.gz -C /data .

# restore a volume from a tar file
docker volume create mydata2
docker run --rm -v mydata2:/data -v $(pwd):/backup alpine \
  tar xzf /backup/mydata.tar.gz -C /data

# migrate data between volumes
docker run --rm -v src:/src -v dst:/dst alpine \
  cp -a /src/. /dst/

# snapshot using a temporary container
docker run --rm -v mydata:/data alpine ls -la /data

Removendo volumes

Um volume não pode ser removido enquanto um contêiner o referencia (remova o contêiner primeiro). prune remove apenas volumes não usados. A exclusão de volume é irreversível — os dados são perdidos para sempre. Sempre faça backup de volumes de produção antes do prune.

docker
# remove a named volume (must not be in use)
docker volume rm mydata

# remove all unused volumes
docker volume prune

# remove volumes older than 24h not used
docker volume prune --filter "until=24h"

# force remove (even if a stopped container referenced it)
docker volume rm -f mydata

# remove with a label filter
docker volume prune --filter "label=temporary"

# CAUTION: data is gone permanently
docker volume rm mydata

Compartilhando volumes entre contêineres

Vários contêineres podem montar o mesmo volume para compartilhar estado. --volumes-from clona os mounts de volume de outro contêiner — prático para padrões sidecar. Adicione :ro para consumidores somente leitura. Coordene escritas concorrentes para evitar corrupção; algumas aplicações precisam de lock.

docker
# share a volume between two containers
docker run -d --name db -v shared:/data alpine sleep 1h
docker run -d --name app -v shared:/data alpine sleep 1h

# use --volumes-from to copy a container's mounts
docker run -d --name helper --volumes-from db alpine sleep 1h

# read-only shared volume
docker run -d --name reader -v shared:/data:ro alpine sleep 1h

# compose: shared volume across services
# volumes:
#   shared:
# services share 'shared' via volumes: ['shared:/data']

# verify both see the same data
docker exec db sh -c "echo hi > /data/msg"
docker exec app cat /data/msg
08

Bind mounts

Bind mount básico

Bind mounts mapeiam um caminho do host diretamente para o contêiner — ideal para desenvolvimento ao vivo, onde edições no host refletem instantaneamente. Use caminhos absolutos do host. O sufixo :ro impede que o contêiner escreva de volta no host. A sintaxe moderna usa --mount por clareza.

docker
# bind mount a host directory (modern syntax)
docker run -d --type bind --source $(pwd)/app --target /app nginx

# short form (-v)
docker run -d -v $(pwd)/app:/app nginx

# absolute host path required
docker run -v /home/me/app:/app nginx

# mount a single file
docker run -v /home/me/app.conf:/etc/app/app.conf:ro nginx

# mount read-only
docker run -v $(pwd)/app:/app:ro nginx

# compose equivalent
# volumes:
#   - ./app:/app

Bind mount somente leitura

Mounts somente leitura protegem a configuração do host de escritas do contêiner — crítico para segurança. --read-only torna o sistema de arquivos raiz imutável, exigindo mounts graváveis explícitos para /tmp e diretórios de log. Isso endurece os contêineres contra comprometimento.

docker
# mount config read-only
docker run -v /etc/myapp:/etc/myapp:ro myapp

# --mount equivalent with explicit type
docker run --mount type=bind,source=/etc/myapp,target=/etc/myapp,readonly myapp

# read-only root filesystem (extra security)
docker run --read-only -v /tmp myapp

# combine read-only root with a writable tmpfs
docker run --read-only --tmpfs /tmp --tmpfs /var/cache myapp

# verify the mount is read-only
docker exec myapp touch /etc/myapp/test  # should fail

Fluxo de desenvolvimento

Monte o código-fonte para que edições no host reflam instantaneamente no contêiner. O truque do 'volume anônimo para node_modules' evita que o node_modules vazio do host sombreie as dependências instaladas na imagem. Pode ser preciso usar polling no Windows/Mac para o file-watch funcionar de forma confiável.

docker
# live-reload: mount source, run dev server
docker run -d -p 3000:3000 -v $(pwd)/src:/app/src node:20 \
  sh -c "cd /app && npm run dev"

# mount node_modules separately (avoid host override)
docker run -d -v $(pwd):/app -v /app/node_modules node:20 npm start

# compose dev workflow
# services:
#   web:
#     volumes:
#       - ./src:/app/src
#       - /app/node_modules  # anonymous, isolates deps

# hot reload with file watching (polling for Windows/Mac)
docker run -e CHOKIDAR_USEPOLLING=true -v $(pwd):/app node:20 npm start

Labels SELinux e AppArmor

Em hosts com SELinux (RHEL/CentOS/Fedora), bind mounts precisam do sufixo :z ou :Z para reetiquetar o caminho do host e o contêiner acessar. :z compartilha o caminho entre contêineres; :Z o torna privado. Esquecer o sufixo causa erros de 'permission denied'.

docker
# SELinux: :z (shared) or :Z (private) suffix
docker run -v /host/path:/container/path:z myapp
docker run -v /host/path:/container/path:Z myapp

# :z labels the host path as shared among containers
# :Z labels it private to this container

# disable SELinux isolation (NOT recommended)
docker run --security-opt label=disable myapp

# AppArmor profile
docker run --security-opt apparmor=docker-default myapp

# custom AppArmor profile
docker run --security-opt apparmor=myprofile myapp

Mount vs Volume vs tmpfs

Volumes: gerenciados pelo Docker, portáveis, melhores para dados persistentes. Bind mounts: caminhos do host, melhores para dev e injeção de configuração. tmpfs: em memória, melhores para secrets e caches efêmeros. A sintaxe --mount é mais explícita e autoexplicativa que -v.

docker
# named volume (Docker-managed, portable)
docker run -v mydata:/data nginx

# bind mount (host path, host-dependent)
docker run -v /home/me/data:/data nginx

# --mount explicit syntax (recommended)
docker run --mount type=volume,source=mydata,target=/data nginx
docker run --mount type=bind,source=/home/me/data,target=/data nginx
docker run --mount type=tmpfs,target=/cache nginx

# tmpfs (in-memory, ephemeral, fast)
docker run --tmpfs /cache nginx

# tmpfs with size limit
docker run --mount type=tmpfs,target=/cache,tmpfs-size=64m nginx

Bind mounts no Compose

No Compose, um caminho relativo (./html) cria um bind mount, enquanto um nome (logs) que referencia a seção volumes: cria um volume nomeado. Um caminho absoluto (/cache) cria um volume anônimo. A sintaxe longa torna opções como read_only explícitas.

docker
# docker-compose.yml
services:
  web:
    image: nginx
    volumes:
      # relative host path = bind mount
      - ./html:/usr/share/nginx/html:ro
      # named volume
      - logs:/var/log/nginx
      # anonymous volume
      - /cache
volumes:
  logs:   # declare named volumes here

# use ~ (tilde) — Compose expands it
volumes:
  - ~/config:/etc/app:ro

# long-form syntax with options
volumes:
  - type: bind
    source: ./html
    target: /usr/share/nginx/html
    read_only: true
09

Redes

Rede bridge (padrão)

A rede bridge padrão não tem DNS automático — os contêineres precisam usar IPs. Redes bridge personalizadas oferecem descoberta de serviços por DNS: os contêineres se resolvem uns aos outros pelo nome. É por isso que o Compose cria uma rede personalizada para cada projeto automaticamente.

docker
# the default bridge network (named 'bridge')
docker run -d --name web nginx

# create a custom bridge network (recommended)
docker network create mynet

# attach a container to a custom network
docker run -d --name web --network mynet nginx
docker run -d --name db --network mynet postgres

# containers on the same custom network can resolve by name
docker exec web ping db   # DNS resolves 'db'

# the default bridge does NOT support DNS names
# always use a custom bridge for multi-container apps

Rede host

A rede host remove o namespace de rede — o contêiner compartilha as interfaces e portas do host. Oferece o melhor desempenho, mas sacrifica isolamento e mapeamento de portas. Disponível só no Linux; no Mac/Windows mapeia para uma rede de VM, não para o host.

docker
# use the host's network stack directly (no isolation)
docker run --network host nginx

# host network disables port mapping
# -p is ignored when --network host is used

# useful for performance-sensitive apps
docker run --network host -d myapp

# only works on Linux (not Docker Desktop on Mac/Windows)
# inspect host network
docker network inspect host

# bound to host interfaces — be careful with privileged ports
docker run --network host --cap-add NET_ADMIN myapp

Rede overlay (Swarm)

Redes overlay atravessam múltiplos nós do Swarm, permitindo comunicação segura entre hosts com DNS embutido. --attachable permite que contêineres avulsos entrem numa overlay (útil para depuração). Criptografia protege o tráfego entre nós; habilite para workloads sensíveis.

docker
# create an overlay network (requires Swarm mode)
docker network create -d overlay myoverlay

# overlay with encryption
docker network create -d overlay -o encrypted myoverlay

# deploy a service on the overlay
docker service create --network myoverlay --name web nginx

# multi-host communication for Swarm services
# containers on different nodes resolve by service name

# node-local network bridged to overlay
docker network create -d overlay --attachable myoverlay
docker run -d --network myoverlay alpine   # standalone container

Redes personalizadas

Redes personalizadas permitem controlar sub-redes, gateways e isolamento. --internal bloqueia acesso à internet de saída. macvlan dá aos contêineres presença real na LAN física (cada um ganha seu próprio MAC) — útil para apps legados, mas quebra a comunicação host-contêiner por padrão.

docker
# create a bridge network with a subnet
docker network create --subnet 172.20.0.0/16 mynet

# assign a static IP
docker run -d --network mynet --ip 172.20.0.10 nginx

# set a custom gateway
docker network create --subnet 172.20.0.0/16 \
  --gateway 172.20.0.1 mynet

# restrict to internal only (no external access)
docker network create --internal mynet

# specify a driver and options
docker network create -d bridge \
  -o com.docker.network.bridge.name=br0 mynet

# macvlan (container gets a MAC on the physical network)
docker network create -d macvlan \
  --subnet 192.168.1.0/24 -o parent=eth0 mymacvlan

DNS de contêineres

O DNS embutido do Docker (127.0.0.11) resolve nomes de contêineres em redes definidas pelo usuário. A bridge padrão não tem DNS. --dns adiciona resolvers externos; --add-host injeta entradas estáticas. Use nomes de serviço (não IPs) para comunicação entre contêineres para que redeploys não quebrem o DNS.

docker
# containers on custom networks resolve by name
docker network create mynet
docker run -d --name db --network mynet postgres
docker run -it --network mynet alpine nslookup db

# the embedded DNS server is at 127.0.0.11
docker exec web cat /etc/resolv.conf

# add custom DNS servers
docker run --dns 8.8.8.8 alpine nslookup example.com

# add DNS search domains
docker run --dns-search example.com alpine nslookup myhost

# add a host entry (like /etc/hosts)
docker run --add-host myservice:10.0.0.5 alpine ping myservice

# extra hosts in compose
# extra_hosts:
#   - "myservice:10.0.0.5"

Inspeção e gerenciamento de redes

network connect/disconnect permite anexar um contêiner em execução a redes adicionais sem reiniciar — útil para sidecars. inspect mostra os contêineres conectados, a sub-rede e o driver. prune remove redes não usadas por nenhum contêiner.

docker
# list all networks
docker network ls

# inspect a network (containers, IPAM, driver)
docker network inspect mynet

# see which containers are on a network
docker network inspect --format '{{range .Containers}}{{.Name}} {{end}}' mynet

# connect a running container to another network
docker network connect mynet2 web

# disconnect a container from a network
docker network disconnect mynet web

# remove an unused network
docker network rm mynet
docker network prune
10

Mapeamento de portas

Mapeamento básico de portas

-p host:container mapeia uma porta do host para uma porta do contêiner. Se omitir a porta do host, o Docker escolhe uma (use docker port para descobrir). Cada porta do host só pode mapear para um contêiner — use um proxy reverso ou portas de host diferentes para múltiplas instâncias.

docker
# map host:container
docker run -d -p 8080:80 nginx

# map to a random host port
docker run -d -p 80 nginx
docker port $(docker ps -lq) 80   # find the assigned port

# map multiple ports
docker run -d -p 8080:80 -p 8443:443 nginx

# map the same port on host and container
docker run -d -p 80:80 nginx

# explicit protocol (default tcp)
docker run -d -p 53:53/udp dns

# long form
docker run -d --publish 8080:80 nginx

Vinculando a um IP específico

Prefixar com um IP controla a qual interface a porta se vincula. 127.0.0.1 mantém o serviço apenas local — essencial para bancos de dados que você não quer expor. 0.0.0.0 (padrão) vincula a todas as interfaces. Sempre vincule bancos de dados ao localhost em produção.

docker
# bind to a specific host IP
docker run -d -p 127.0.0.1:8080:80 nginx

# bind to localhost only (not exposed externally)
docker run -d -p 127.0.0.1:5432:5432 postgres

# bind to all interfaces (default)
docker run -d -p 0.0.0.0:8080:80 nginx

# bind to an IPv6 address
docker run -d -p [::1]:8080:80 nginx

# multiple bindings
docker run -d -p 127.0.0.1:8080:80 -p 0.0.0.0:8443:443 nginx

# compose: specify IP
# ports:
#   - "127.0.0.1:5432:5432"

Portas UDP e SCTP

O sufixo /udp ou /sctp seleciona o protocolo; TCP é o padrão. Para serviços como DNS que precisam de ambos, declare os dois mapeamentos. Faixas de portas mapeiam 1:1 entre host e contêiner — útil para WebRTC, RTP ou FTP passivo. Garanta que as regras de firewall correspondam aos protocolos.

docker
# UDP port (DNS, syslog, statsd)
docker run -d -p 53:53/udp coredns

# both TCP and UDP
docker run -d -p 53:53/tcp -p 53:53/udp coredns

# SCTP (e.g. telecom signaling)
docker run -d -p 3868:3868/sctp myapp

# range of ports (host range maps to container range)
docker run -d -p 8000-8100:8000-8100 myapp

# UDP range
docker run -d -p 50000-50010:50000-50010/udp myapp

# compose with protocol
# ports:
#   - "53:53/udp"

Faixa de portas

Faixas de portas mapeiam 1:1 (host 8000-8005 para o contêiner 8000-8005). -P (maiúsculo) publica automaticamente cada porta EXPOSE numa porta alta aleatória do host — prático para testes rápidos. Use docker ps para ver os mapeamentos reais quando as portas forem aleatórias.

docker
# map a range of host ports to container ports
docker run -d -p 8000-8005:8000-8005 myapp

# map host range to a single container port (NOT supported)
# this maps range-to-range only

# random port for each (useful for testing)
docker run -d -p 80 -p 443 nginx
docker port $(docker ps -lq)

# expose a range with EXPOSE (documentation only)
# EXPOSE 8000-8005

# publish all exposed ports at once
docker run -d -P nginx   # capital P publishes all EXPOSE ports

# view the random mappings
docker ps --format '{{.Names}} {{.Ports}}'

Expor vs publicar

EXPOSE documenta a intenção; -p de fato publica. No Compose, expose compartilha a porta apenas com outros serviços da mesma rede, enquanto ports publica no host. Essa distinção importa para bancos de dados: exponha internamente, nunca publique no host em produção.

docker
# Dockerfile: EXPOSE is documentation, NOT a publish
EXPOSE 80 443

# runtime: -p PUBLISHES the port to the host
docker run -d -p 8080:80 nginx

# -P publishes all EXPOSE ports to random host ports
docker run -d -P nginx

# compose: expose vs ports
services:
  web:
    image: nginx
    expose:
      - "80"      # only to linked services, NOT to host
    ports:
      - "8080:80" # published to the host

# view exposed (not published) ports
docker inspect --format '{{json .Config.ExposedPorts}}' nginx

Mapeamento de porta aleatória

Omitir a porta do host deixa o Docker escolher uma porta efêmera aleatória (32768-60999 por padrão). Use docker port ou docker ps para descobri-la. Isso é útil para escalar serviços idênticos num mesmo host. Ajuste a faixa efêmera em /proc/sys/net/ipv4/ip_local_port_range no Linux.

docker
# publish to a random high host port
docker run -d -p 80 nginx

# publish all EXPOSE ports randomly
docker run -d -P nginx

# find the assigned port
docker port <container> 80
docker port <container>

# see mappings in ps output
docker ps --format 'table {{.Names}}	{{.Ports}}'

# prefer a range for random allocation
docker run -d -p 30000-40000:80 nginx

# compose: random host port
# ports:
#   - "80"   # random host port, container port 80
11

Variáveis de ambiente

Definindo variáveis de ambiente

-e (ou --env) define variáveis de ambiente no contêiner. -e VAR (sem valor) herda a variável do shell do host. Para valores sensíveis, prefira --env-file ou Docker secrets a um -e simples, que fica visível em docker inspect e nas listagens de processos.

docker
# single variable
docker run -d -e MYSQL_ROOT_PASSWORD=secret mysql

# multiple variables
docker run -d \
  -e MYSQL_ROOT_PASSWORD=secret \
  -e MYSQL_DATABASE=mydb \
  -e MYSQL_USER=app \
  mysql

# pass from the host environment
docker run -d -e HOST_PWD mysql
# HOST_PWD in the container = $HOST_PWD on host

# set a variable without a value (passes host value or empty)
docker run -e DEBUG alpine env

# long form
docker run --env MYSQL_ROOT_PASSWORD=secret mysql

Arquivos de env

--env-file carrega variáveis de um arquivo, mantendo o comando run limpo e os secrets fora do histórico do shell. O Compose carrega automaticamente um .env de nível superior para substituição de variáveis no próprio arquivo compose. Comentários (#) e linhas em branco são ignorados; aspas são preservadas literalmente.

docker
# .env file
# DB_HOST=db
# DB_USER=app
# DB_PASSWORD=secret

# load variables from a file
docker run --env-file .env myapp

# load multiple env files
docker run --env-file .env --env-file .env.local myapp

# Compose reads .env automatically for variable substitution
# and supports env_file per service:
# services:
#   web:
#     env_file:
#       - .env
#       - .env.local

# env file with comments and blank lines
docker run --env-file config.env myapp

Variáveis de ambiente no Dockerfile

ENV grava as variáveis na imagem, visíveis no build e em runtime. ARG existe só em tempo de build — converta para ENV se o runtime precisar. Sobrescreva valores gravados com -e em runtime. Atenção: variáveis de ambiente ficam visíveis em docker inspect, então não guarde secrets nelas.

docker
# ENV sets a persistent variable
ENV NODE_ENV=production
ENV PATH=/app/bin:$PATH

# use ARG for build-time only, ENV for runtime
ARG BUILD_VERSION=1.0
ENV APP_VERSION=${BUILD_VERSION}

# view all env vars
docker exec web env

# inspect a specific variable
docker exec web printenv NODE_ENV

# override at runtime
docker run -e NODE_ENV=development myapp

# set via Compose
# environment:
#   - NODE_ENV=development
#   - DEBUG=true

Variáveis de ambiente dinâmicas e substituição

A expansão do shell ($(...) ou ${VAR}) acontece no host antes de o Docker ver o valor. No Compose, ${VAR} é substituído pelo arquivo .env. Em CMD na forma exec, ${VAR} NÃO é expandido — embrulhe com sh -c. Passe o UID do host para propriedade de arquivos correta em bind mounts.

docker
# pass a computed value at runtime
docker run -e STARTUP_TIME=$(date +%s) myapp

# use host shell expansion
docker run -e USER_ID=$(id -u) myapp

# Compose variable substitution from .env
# services:
#   web:
#     environment:
#       DB_HOST: ${DB_HOST}
# .env file:
#   DB_HOST=db

# Compose with default values
#   DB_HOST: ${DB_HOST:-localhost}

# pass the current user for permission matching
docker run -u $(id -u):$(id -g) -e HOME=/tmp myapp

# resolve env at runtime with sh -c (not in exec form)
ENV PORT=3000
CMD ["sh", "-c", "node server.js --port ${PORT}"]

Environment no Compose

O environment do Compose aceita sintaxe de lista ou mapa. env_file carrega valores para o contêiner; .env (de nível superior) fornece variáveis para substituição ${} no próprio arquivo compose. Use a forma de mapa para legibilidade com muitas variáveis.

docker
# docker-compose.yml
services:
  web:
    image: myapp
    environment:
      - NODE_ENV=production
      - DEBUG=false
      - DB_HOST=db
    # map form (cleaner for many vars)
    environment:
      NODE_ENV: production
      DB_HOST: db

  db:
    image: postgres
    env_file:
      - .env.db
    environment:
      POSTGRES_DB: ${DB_NAME}   # from .env

# top-level .env for substitution
# DB_NAME=mydb

Gerenciamento de secrets

Secrets são montados como arquivos em /run/secrets, nunca como variáveis de ambiente, e são criptografados em trânsito e em repouso no Swarm. Evite gravar secrets em imagens (ENV) ou passá-los via -e — ambos vazam via docker inspect e camadas de imagem. Secret mounts do BuildKit mantêm credenciais de build fora das camadas.

docker
# Docker Swarm secrets (encrypted, mounted as files)
echo "supersecret" | docker secret create db_password -
docker service create --secret db_password myapp

# read in the app
# cat /run/secrets/db_password

# Compose secrets (v3.1+)
# services:
#   web:
#     secrets:
#       - db_password
# secrets:
#   db_password:
#     file: ./secrets/db_password.txt

# BuildKit secret mount (build-time, not in layers)
# RUN --mount=type=secret,id=npmrc,target=/root/.npmrc npm ci

# avoid: baking secrets in ENV or -e (visible in inspect)
docker run -e API_KEY=xxx myapp  # NOT recommended
12

Básico do Docker Compose

docker-compose.yml básico

O Compose define uma aplicação multi-contêiner em um único arquivo YAML. services descreve cada contêiner; volumes e networks são declarados no nível superior. depends_on controla a ordem de inicialização. docker compose up -d inicia tudo em segundo plano.

docker
# docker-compose.yml (Compose spec v2)
services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"
    volumes:
      - ./html:/usr/share/nginx/html:ro
    depends_on:
      - db
    restart: unless-stopped

  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret
    volumes:
      - dbdata:/var/lib/postgresql/data

volumes:
  dbdata:

# run: docker compose up -d

Comandos do Compose

up cria e inicia, down para e remove. Adicione -v ao down para apagar volumes (perda de dados). exec roda um comando num serviço em execução; run inicia um novo contêiner para uma tarefa pontual. --scale lança múltiplas réplicas de um serviço no mesmo host.

docker
# start all services (foreground)
docker compose up

# start in background (detached)
docker compose up -d

# rebuild images before starting
docker compose up -d --build

# stop and remove containers (keeps volumes)
docker compose down

# also remove volumes (data loss)
docker compose down -v

# view logs (all services)
docker compose logs -f

# scale a service
docker compose up -d --scale worker=3

# run a one-off command in a service
docker compose exec web sh
docker compose run --rm web python manage.py migrate

Dependências entre serviços

depends_on controla a ordem de inicialização, mas a dependência pode não estar 'pronta' — use condition: service_healthy com um healthcheck para esperar até o banco aceitar conexões. service_completed_successfully espera contêineres de inicialização. As aplicações ainda devem tentar reconectar.

docker
services:
  web:
    image: myapp
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
    restart: on-failure

  db:
    image: postgres
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "postgres"]
      interval: 5s
      retries: 5

  redis:
    image: redis

# conditions: service_started | service_healthy | service_completed_successfully

Build no Compose

build define como construir uma imagem a partir do código; image etiqueta o resultado. context é enviado ao builder (mantenha pequeno). target seleciona um stage de build multi-stage. --build força o rebuild no up. Build args passam valores em tempo de build.

docker
services:
  web:
    build:
      context: ./app
      dockerfile: Dockerfile.prod
      args:
        VERSION: 1.0
      target: final
    image: myapp:1.0
    ports:
      - "8080:80"

  worker:
    build: ./worker   # shorthand: context only
    image: myworker:1.0

# build and tag
docker compose build
docker compose build --no-cache web
docker compose up -d --build

Volumes no Compose

Um caminho relativo (./html) é um bind mount; um nome (logs) declarado em volumes: de nível superior é um volume nomeado; um caminho absoluto (/cache) é anônimo. Volumes nomeados podem especificar driver e opções (por exemplo, NFS). O Compose prefixa os nomes dos volumes com o nome do projeto.

docker
services:
  web:
    image: nginx
    volumes:
      # named volume
      - logs:/var/log/nginx
      # bind mount (relative path)
      - ./html:/usr/share/nginx/html:ro
      # anonymous volume
      - /cache

  db:
    image: postgres
    volumes:
      - dbdata:/var/lib/lib/postgresql/data

volumes:
  logs:
  dbdata:
    driver: local
    driver_opts:
      type: nfs
      device: ":/export/data"
      o: addr=10.0.0.5,rw

Redes no Compose

O Compose cria uma rede padrão para os serviços, mas definir redes personalizadas permite isolar camadas. web faz a ponte entre frontend e backend. internal: true bloqueia acesso à internet para o backend. Serviços na mesma rede se resolvem pelo nome via DNS.

docker
services:
  web:
    image: nginx
    networks:
      - frontend
      - backend

  db:
    image: postgres
    networks:
      - backend

  proxy:
    image: traefik
    networks:
      - frontend

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge
    internal: true   # no external access

# custom subnet
networks:
  backend:
    ipam:
      config:
        - subnet: 172.28.0.0/16
13

Docker Compose avançado

Profiles do Compose

Profiles agrupam serviços opcionais. Serviços sem profile sempre iniciam; serviços com profile só iniciam quando o profile é ativado com --profile. Isso permite que um único arquivo compose atenda dev, teste e produção: ative profiles seletivamente por ambiente.

docker
services:
  web:
    image: nginx
    profiles: ["default", "prod"]

  debug:
    image: nginx
    profiles: ["debug"]
    ports:
      - "8080:80"

  test:
    image: myapp-test
    profiles: ["test"]

# start only default services
docker compose up -d

# start with the debug profile
docker compose --profile debug up -d

# run tests
docker compose --profile test run test

# start multiple profiles
docker compose --profile prod --profile debug up -d

Overrides do Compose

O Compose carrega automaticamente docker-compose.override.yml sobre o docker-compose.yml para personalização local de dev. Para outros ambientes, passe vários arquivos -f em ordem — os arquivos posteriores sobrescrevem os anteriores. Isso separa limparamente a config base dos ajustes por ambiente.

docker
# docker-compose.yml (base)
services:
  web:
    image: myapp:latest
    environment:
      NODE_ENV: production

# docker-compose.override.yml (auto-loaded for dev)
services:
  web:
    build: ./app
    environment:
      NODE_ENV: development
      DEBUG: "true"
    volumes:
      - ./src:/app/src
    command: npm run dev

# explicit override file
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

# merge order: later files override earlier ones
# docker compose -f base.yml -f dev.yml -f local.yml up

Healthchecks no Compose

Healthchecks no Compose espelham o HEALTHCHECK do Dockerfile. start_period concede tempo de carência na inicialização. Combinar healthcheck com depends_on: condition: service_healthy faz um serviço esperar até as dependências estarem realmente prontas, não apenas iniciadas.

docker
services:
  web:
    image: nginx
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s

  db:
    image: postgres
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

  app:
    image: myapp
    depends_on:
      db:
        condition: service_healthy

Escalonamento e réplicas

--scale lança N contêineres idênticos num host — o serviço não pode vincular uma porta de host fixa (use porta aleatória ou sem mapeamento). A chave deploy.replicas é respeitada pelo Swarm; para Compose puro use --scale. Um balanceador fica à frente dos serviços escalados.

docker
# scale at startup (single host)
docker compose up -d --scale worker=4

# docker-compose.yml with replicas (Compose spec)
services:
  worker:
    image: myworker
    deploy:
      replicas: 4
      resources:
        limits:
          cpus: "0.5"
          memory: 512M

  web:
    image: nginx
    deploy:
      replicas: 2
      update_config:
        parallelism: 1
        delay: 10s

# note: replicas deploy key is for Swarm;
# plain Compose uses --scale

# prevent port conflicts when scaling
docker compose up -d --scale web=3   # web must use random ports

Config e validação do Compose

config valida e renderiza o arquivo compose mesclado (incluindo overrides e substituição do .env), o que é valioso para depurar. --services, --images e --volumes inventariam os recursos. Use -q no CI para falhar rápido em arquivos compose malformados.

docker
# validate and print the merged compose file
docker compose config

# check for errors only
docker compose config -q

# list all services
docker compose config --services

# list all images used
docker compose config --images

# list all volumes
docker compose config --volumes

# render with variable substitution (resolve .env)
docker compose config > rendered.yml

# validate before deploying
docker compose config -q && docker compose up -d

Múltiplos arquivos Compose

Empilhar arquivos compose separa responsabilidades: config base, overrides de ambiente, ajustes locais. COMPOSE_FILE (separado por dois-pontos no Linux/Mac, ponto e vírgula no Windows) evita repetir -f. Listas como ports são anexadas; mapas como environment são mesclados por chave.

docker
# base, dev, and prod files
docker compose -f docker-compose.yml -f docker-compose.dev.yml up
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

# COMPOSE_FILE env var (avoids -f repetition)
export COMPOSE_FILE=docker-compose.yml:docker-compose.dev.yml
docker compose up -d

# docker-compose.prod.yml
services:
  web:
    image: registry.com/myapp:${TAG}
    environment:
      NODE_ENV: production
    deploy:
      replicas: 3

# difference files: add/override specific keys
# lists (ports, volumes) are merged; maps (environment) are merged
14

Registry do Docker

Rodando um registry local

A imagem registry:2 roda um registry privado na porta 5000. Monte um volume para persistir imagens. Para hosts remotos ou HTTPS, configure certificados TLS ou adicione o registry em insecure-registries em /etc/docker/daemon.json. A API v2 permite catalogar repositórios via curl.

docker
# run the official registry image
docker run -d -p 5000:5000 --name registry \
  -v registrydata:/var/lib/registry \
  --restart always \
  registry:2

# tag and push to it
docker tag myapp:1.0 localhost:5000/myapp:1.0
docker push localhost:5000/myapp:1.0

# pull from it
docker pull localhost:5000/myapp:1.0

# list repositories in the registry
curl http://localhost:5000/v2/_catalog

# list tags for a repository
curl http://localhost:5000/v2/myapp/tags/list

Enviando para um registry privado

As imagens precisam ser etiquetadas com o host do registry antes do push. Para registries com certificados autoassinados, adicione o host em insecure-registries e reinicie o daemon (não recomendado em produção — use uma CA real ou CA interna). push -a envia todas as tags do repositório.

docker
# tag with the registry URL
docker tag myapp:1.0 registry.local:5000/myapp:1.0

# login
docker login registry.local:5000

# push
docker push registry.local:5000/myapp:1.0

# push all tags
docker push -a registry.local:5000/myapp

# verify it landed
curl http://registry.local:5000/v2/myapp/tags/list

# self-signed cert: configure the daemon
# /etc/docker/daemon.json:
# { "insecure-registries": ["registry.local:5000"] }
# then: systemctl restart docker

Baixando de um registry privado

Faça pull de um registry privado especificando o nome completo da imagem. As credenciais de login ficam em ~/.docker/config.json (use um credential helper por segurança). Para CI/CD, guarde credenciais como secrets e faça login antes do pull. Fixe pelo digest para deploys reproduzíveis.

docker
# login first (credentials cached in ~/.docker/config.json)
docker login registry.local:5000

# pull by full name
docker pull registry.local:5000/myapp:1.0

# pull by digest (immutable)
docker pull registry.local:5000/myapp@sha256:abc123...

# use in Compose
# services:
#   web:
#     image: registry.local:5000/myapp:1.0

# logout
docker logout registry.local:5000

# check stored credentials
cat ~/.docker/config.json

Autenticação do registry

Proteja um registry com basic auth htpasswd ou um servidor de tokens (OAuth). Para TLS, monte os certs e escute na 443. Credential helpers (credsStore) guardam senhas no keychain do sistema operacional em vez do config.json em texto puro — essencial para máquinas compartilhadas ou de CI.

docker
# htpasswd-based auth
mkdir -p auth
docker run --entrypoint htpasswd httpd:2 -Bbn user password > auth/htpasswd

# run registry with auth
docker run -d -p 5000:5000 --name registry \
  -v $(pwd)/auth:/auth \
  -e REGISTRY_AUTH=htpasswd \
  -e REGISTRY_AUTH_HTPASSWD_REALM=Registry \
  -e REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd \
  registry:2

# login now required
docker login localhost:5000

# token-based auth (OAuth, JWT) for enterprise
# configure REGISTRY_AUTH=token with an auth server

# credential helpers (avoid storing in config.json)
# "credsStore": "secretservice" (Linux)
# "credsStore": "osxkeychain" (Mac)
# "credsStore": "wincred" (Windows)

API do registry

A Registry HTTP API v2 permite scriptar o gerenciamento do registry. _catalog lista os repositórios; manifests descrevem as camadas da imagem. A exclusão exige REGISTRY_STORAGE_DELETE_ENABLED=true e remove manifests — os blobs são limpos pela garbage collection (registry garbage-collect).

docker
# list all repositories
curl http://localhost:5000/v2/_catalog

# list tags for a repo
curl http://localhost:5000/v2/myapp/tags/list

# get a manifest
curl -H "Accept: application/vnd.docker.distribution.manifest.v2+json" \
  http://localhost:5000/v2/myapp/manifests/1.0

# delete a manifest (by digest)
curl -X DELETE \
  http://localhost:5000/v2/myapp/manifests/sha256:abc123...

# enable delete API
# -e REGISTRY_STORAGE_DELETE_ENABLED=true

# check if a blob exists
curl -I http://localhost:5000/v2/myapp/blobs/sha256:abc...

Garbage collection

Excluir um manifest deixa blobs órfãos até que a garbage collection rode. Pare o registry (ou use --dry-run) para evitar coletar camadas em uso. Agende o GC regularmente em produção para recuperar disco de imagens excluídas ou substituídas. O caminho config.yml é o arquivo de configuração do registry.

docker
# run garbage collection on a registry
docker exec -it registry \
  garbage-collect --dry-run /etc/docker/registry/config.yml

# actual collection (stop the registry first for consistency)
docker stop registry
docker run --rm -v registrydata:/var/lib/registry \
  -v /path/config.yml:/etc/docker/registry/config.yml \
  registry:2 garbage-collect /etc/docker/registry/config.yml
docker start registry

# delete unreferenced blobs after manifest deletion
# schedule GC as a cron job for production registries

# view disk usage
docker exec registry du -sh /var/lib/registry
15

Docker Hub

Login e logout

Prefira tokens de acesso a senhas — são revogáveis e com escopo. --password-stdin lê do stdin, evitando a senha no histórico do shell e nas listas de processos. Configure um credential helper para guardar credenciais no keychain do sistema em vez do config.json em texto puro.

docker
# interactive login (prompts for username/password)
docker login

# login with a token (recommended over password)
docker login -u username -p dckr_pat_xxxxx

# login via stdin (avoids shell history)
echo "dckr_pat_xxxxx" | docker login -u username --password-stdin

# logout
docker logout

# credentials stored in ~/.docker/config.json
# or OS keychain via credential helper

# create an access token on Docker Hub
# Account Settings -> Security -> New Access Token

Buscando imagens

docker search consulta o Docker Hub pela CLI, com filtros para estrelas, status oficial e builds automatizados. Imagens oficiais (library/nginx) são verificadas pelo Docker — prefira-as como base. A interface web oferece filtros mais ricos por SO, arquitetura e categoria.

docker
# search Docker Hub from the CLI
docker search nginx

# filter by stars
docker search --filter stars=100 nginx

# only official images
docker search --filter is-official nginx

# only automated builds
docker search --filter is-automated nginx

# limit results
docker search --limit 5 nginx

# show full description (no truncation)
docker search --no-trunc nginx

# search on the web for richer filtering
# https://hub.docker.com/search?q=nginx

Enviando para o Docker Hub

Etiquete as imagens como username/repo:tag e faça push para publicar no Docker Hub. O repositório é criado automaticamente no primeiro push (público por padrão). push -a envia todas as tags. Contas gratuitas têm um repositório privado; planos pagos oferecem mais. Defina a visibilidade do repositório na web do Hub.

docker
# tag with your username
docker tag myapp:1.0 username/myapp:1.0

# also tag as latest
docker tag username/myapp:1.0 username/myapp:latest

# login
docker login

# push (creates the repo if it doesn't exist)
docker push username/myapp:1.0
docker push username/myapp:latest

# push all tags
docker push -a username/myapp

# make the repo private on Docker Hub
# (Hub web UI -> Repository -> Settings -> Make Private)

Builds automatizados

Os autobuilds do Docker Hub vinculam um repositório git e fazem build a cada push. Fluxos modernos preferem GitHub Actions com buildx e push, que oferecem mais controle, cache e builds multi-arquitetura. Os autobuilds do Hub continuam sendo uma opção de baixo esforço para projetos simples.

docker
# connect a GitHub/Bitbucket repo to Docker Hub
# Hub web UI -> Create -> Build Rule

# build rule examples:
# Source: github.com/me/myapp  Branch: main
# Dockerfile location: /Dockerfile
# Image tag: latest

# trigger a build via webhook
curl -H "Content-Type: application/json" \
  --data '{"build": true}' \
  https://hub.docker.com/api/build/v1/source/.../trigger/.../call/

# build context with multiple tags and stages
# Source: Branch main  -> Tag: branch-main
# Source: Tag v1.0     -> Tag: 1.0, latest

# Autobuild triggers on git push
# (deprecated in favor of GitHub Actions)

Organizações e equipes

Organizações compartilham repositórios pela equipe com acesso baseado em papéis. Teams recebem permissões por repositório (read, write, admin). Contas de serviço fornecem tokens não pessoais para CI/CD — revogue e troque sem afetar pessoas. Use namespacing orgname/repo.

docker
# create an organization on Docker Hub
# (web UI: Create Organization)

# create a team and add members
# Org -> Teams -> Create Team -> Add Members

# assign repository permissions per team
# Repository -> Permissions -> Add Team
#   Read-only, Read-write, Admin

# create a service account token for CI
# Org -> Service Accounts -> New Service Account
# use the token in CI: docker login -u tokenname -p token

# team namespaces: orgname/repo
docker tag myapp orgname/myapp:1.0
docker push orgname/myapp:1.0

Confiança em imagens (DCT)

Docker Content Trust (DCT) usa o Notary para assinar tags de imagens, garantindo que a imagem que você puxa é a que o publicador enviou. Habilite via DOCKER_CONTENT_TRUST=1. Com DCT ativo, só imagens assinadas podem ser puxadas ou enviadas. Gerencie as chaves de assinatura com cuidado — perdê-las pode bloquear seu acesso às imagens.

docker
# enable Docker Content Trust (signing)
export DOCKER_CONTENT_TRUST=1

# push signs the image automatically
docker push username/myapp:1.0

# pull refuses unsigned images when DCT is on
docker pull username/myapp:1.0

# disable for a single command
DOCKER_CONTENT_TRUST=0 docker pull unsigned/myapp:1.0

# generate delegation keys
docker trust key generate alice

# add a signer to a repository
docker trust signer add --key alice.pub alice username/myapp

# view signatures
docker trust inspect username/myapp:1.0

# revoke and rotate keys via the notary CLI
16

Healthcheck

Healthcheck básico

Um healthcheck roda um comando periodicamente; exit 0 é saudável, não-zero é insalubre. O contêiner começa em 'starting' e vira 'healthy' após as retentativas succeeding, ou 'unhealthy' após as falhas. start_period dá tempo de carência na inicialização. O health guia as decisões de reinício do Swarm.

docker
# add a healthcheck at runtime
docker run -d --name web \
  --health-cmd="curl -f http://localhost/ || exit 1" \
  --health-interval=30s \
  --health-timeout=5s \
  --health-retries=3 \
  --health-start-period=10s \
  nginx

# check health status
docker inspect --format '{{.State.Health.Status}}' web

# view health check log (last 5 results)
docker inspect --format '{{json .State.Health.Log}}' web | jq

# states: starting | healthy | unhealthy | none

Healthcheck no Dockerfile

HEALTHCHECK num Dockerfile grava a checagem na imagem. Use a checagem mais leve que confirme que a app realmente atende — curl -f ou wget --spider para HTTP, pg_isready para Postgres. HEALTHCHECK NONE desabilita uma checagem herdada. Checagens abrangentes demais causam flapping falso de 'unhealthy'.

docker
FROM nginx:alpine

# basic healthcheck (exec form)
HEALTHCHECK --interval=30s --timeout=5s --retries=3 --start-period=10s \
  CMD curl -f http://localhost/ || exit 1

# using wget (alpine)
HEALTHCHECK CMD wget --spider -q http://localhost/ || exit 1

# postgres ships a ready check
HEALTHCHECK CMD pg_isready -U postgres

# disable a healthcheck inherited from the base image
HEALTHCHECK NONE

# verify
docker inspect --format '{{.Config.Healthcheck}}' myapp

Opções do healthcheck

interval define a frequência das checagens; timeout limita cada checagem; retries é o limiar de falhas consecutivas. start_period ignora falhas durante a inicialização, evitando 'unhealthy' falso enquanto a app aquece. Ajuste para detectar interrupções reais rápido sem flapping sob carga.

docker
# full set of options
HEALTHCHECK \
  --interval=30s      \  # time between checks (default 30s)
  --timeout=5s        \  # max time per check (default 30s)
  --retries=3         \  # failures to mark unhealthy (default 3)
  --start-period=30s  \  # boot grace period (default 0s)
  CMD curl -f http://localhost/

# interval: how often to run
# timeout: if a check exceeds this, it's a failure
# retries: consecutive failures before unhealthy
# start-period: failures during this don't count

# compose form
healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost"]
  interval: 30s
  timeout: 5s
  retries: 3
  start_period: 30s

Inspecionando o status de saúde

ps mostra (healthy)/(unhealthy) ao lado do status. O Health.Log registra as últimas 5 saídas de checagem — valioso para depurar por que uma checagem falha. Rode o comando da checagem manualmente via exec para ver o erro real. Filtre o ps por health para achar contêineres doentes rápido.

docker
# current status
docker inspect --format '{{.State.Health.Status}}' web

# last 5 check results
docker inspect --format '{{range .State.Health.Log}}\
{{.ExitCode}} {{.Output}}{{end}}' web

# show in ps (status column shows (healthy)/(unhealthy))
docker ps

# filter containers by health
docker ps --filter "health=unhealthy"

# troubleshoot a failing check
docker inspect --format '{{json .State.Health.Log}}' web | jq

# run the check command manually
docker exec web curl -f http://localhost/

Healthcheck no Compose

O healthcheck do Compose espelha o do Dockerfile. test aceita um array (forma exec) ou uma string CMD-SHELL. disable: true remove uma checagem herdada. Combine healthcheck com depends_on: condition: service_healthy para que um serviço espere as dependências realmente prontas, não apenas iniciadas.

docker
services:
  web:
    image: nginx
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s

  db:
    image: postgres
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      retries: 5

  app:
    image: myapp
    depends_on:
      db:
        condition: service_healthy
      web:
        condition: service_healthy

# disable a healthcheck
  debug:
    image: nginx
    healthcheck:
      disable: true

Boas práticas de healthcheck

Cheque um endpoint /healthz real que verifique dependências críticas (DB, cache) — uma checagem TCP simples pode passar com a app quebrada. Mantenha as checagens leves e rápidas; elas rodam a cada intervalo. Use start_period para runtimes de inicialização lenta (JVM, Rails) para não marcá-los como unhealthy durante o boot.

docker
# check the actual app endpoint, not just TCP
HEALTHCHECK CMD curl -f http://localhost/healthz || exit 1

# include a /healthz endpoint in your app
# that verifies DB and cache connectivity

# keep checks fast (under timeout)
HEALTHCHECK --timeout=3s CMD curl -f http://localhost/healthz

# avoid heavy checks — they run every interval
# don't run migrations or full DB queries

# use start-period for slow starters (Java, Rails)
HEALTHCHECK --start-period=60s CMD ...

# for Swarm, health enables auto-restart of unhealthy tasks
# combine with restart policies and update_config

# example app endpoint (Express)
# app.get('/healthz', (req, res) => res.send('ok'))
17

Limites de recursos

Limites de memória

--memory define um limite rígido; excedê-lo dispara OOM kill. --memory-swap limita memória+swap combinadas; igualar à memória desabilita o swap. --memory-reservation é uma dica suave para o kernel. Desabilite o swap para desempenho previsível em workloads sensíveis à latência.

docker
# limit to 512MB of memory
docker run -d --memory="512m" nginx

# memory + swap (swap = memory + swap allowance)
docker run -d --memory="512m" --memory-swap="1g" nginx

# soft limit (hint to the kernel, may be exceeded)
docker run -d --memory-reservation="256m" nginx

# disable swap (swap = memory, no extra)
docker run -d --memory="512m" --memory-swap="512m" nginx

# OOM behavior: kill the container (default)
docker run -d --memory="512m" --oom-kill-disable nginx

# verify limits
docker inspect --format '{{.HostConfig.Memory}}' <container>

Limites de CPU

--cpus define o limite de CPU como fração de núcleos (1.5 = 1.5 núcleos). --cpu-shares é um peso relativo usado em contenção, não um teto rígido. --cpuset-cpins fixa um contêiner a núcleos específicos, útil para isolamento de desempenho. Quota/period é a forma de baixo nível do cgroup.

docker
# limit to 1 CPU (1.0 = one full core)
docker run -d --cpus="1.0" nginx

# limit to 1.5 CPUs
docker run -d --cpus="1.5" nginx

# CPU shares (relative weight, default 1024)
docker run -d --cpu-shares=512 nginx

# pin to specific CPU cores (0,1)
docker run -d --cpuset-cpus="0,1" nginx

# pin to cores 0-3
docker run -d --cpuset-cpus="0-3" nginx

# quota/period form (100000us per 100000us = 1 CPU)
docker run -d --cpu-quota=50000 --cpu-period=100000 nginx

Comportamento de memória e swap

memory-swap é o total de memória + swap. Igualar à memória desabilita o swap. -1 permite swap ilimitado. Swappiness (0-100) controla a tendência do kernel de usar swap; valores menores favorecem manter páginas na RAM. Limites de memória de kernel são avançados e raramente necessários.

docker
# memory limit, swap disabled
docker run -d -m 512m --memory-swap 512m nginx

# memory limit, 512m extra swap
docker run -d -m 512m --memory-swap 1g nginx

# unlimited swap (limited memory)
docker run -d -m 512m --memory-swap -1 nginx

# swappiness (0-100, lower = less swapping)
docker run -d -m 512m --memory-swappiness=10 nginx

# kernel memory limit (advanced, rarely needed)
docker run -d --kernel-memory="100m" nginx

# verify swap settings
docker inspect --format '{{.HostConfig.MemorySwap}}' <container>

Limites de recursos no Compose

deploy.resources.limits define tetos rígidos; reservations define garantias suaves (usadas para agendamento). O Swarm honra isso nativamente. Para Compose puro (não Swarm), use mem_limit e cpus de nível superior no formato v2. Reservations permitem que um contêiner reivindique um mínimo mesmo ocioso.

docker
services:
  web:
    image: nginx
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 512M
        reservations:
          cpus: "0.25"
          memory: 256M

  worker:
    image: myworker
    mem_swappiness: 10
    memswap_limit: 1g
    cpus: 2.0

# limits = hard caps; reservations = soft guarantees
# Swarm honors deploy.resources
# plain Compose: use top-level mem_limit, cpus (v2 compat)

Comportamento de OOM e reinício

Quando a memória se esgota, o OOM-killer do kernel escolhe uma vítima. oom-kill-disable protege um contêiner mas pode derrubar o host — use só com limites de memória no host. oom-score-adj enviesa a seleção: positivo = morto primeiro, negativo = protegido. Verifique OOMKilled para diagnosticar reinícios.

docker
# default: OOM kills the container, restart policy restarts it
docker run -d --memory=512m --restart unless-stopped nginx

# disable OOM kill for this container (risky)
docker run -d --memory=512m --oom-kill-disable nginx

# set OOM score adjustment (higher = killed first)
docker run -d --oom-score-adj=500 nginx

# protect a critical container (killed last)
docker run -d --oom-score-adj=-500 nginx

# verify restart count
docker inspect --format '{{.RestartCount}}' <container>

# check if OOM-killed
docker inspect --format '{{.State.OOMKilled}}' <container>

Inspecionando o uso de recursos

docker stats transmite CPU, memória, rede e disco IO ao vivo por contêiner — o ponto de partida para triagem rápida. --no-stream dá um único snapshot para scripts. Para análise mais profunda, colete /sys/fs/cgroup ou exponha métricas Prometheus via cAdvisor. Compare o uso com os limites para dimensionar corretamente.

docker
# live resource stats (CPU, memory, network, IO)
docker stats

# specific container
docker stats web

# one snapshot (no streaming)
docker stats --no-stream

# custom format
docker stats --format "table {{.Name}}	{{.CPUPerc}}	{{.MemUsage}}"

# container cgroup details
docker exec web cat /sys/fs/cgroup/memory/memory.usage_in_bytes
docker exec web cat /sys/fs/cgroup/cpu/cpu.stat

# inspect configured limits
docker inspect --format '{{.HostConfig.Memory}} {{.HostConfig.NanoCpus}}' web
18

Segurança

Usuário não-root

Rodar como não-root limita o raio de dano se a app for comprometida. Crie um usuário dedicado no Dockerfile e alterne para ele com USER. Se precisar vincular uma porta privilegiada, use um proxy reverso (nginx) ou conceda a capability NET_BIND_SERVICE em vez de rodar como root.

docker
# Dockerfile: create and use a non-root user
FROM node:20-alpine
RUN addgroup -S app && adduser -S app -G app
USER app
WORKDIR /app
COPY --chown=app:app . .
CMD ["node", "server.js"]

# at runtime, override the user
docker run -u 1000:1000 myapp

# verify the current user
docker exec web id

# bind to privileged ports? Use capabilities or a reverse proxy
# non-root cannot bind to ports < 1024 without NET_BIND_SERVICE

# distroless images ship a non-root user by default
FROM gcr.io/distroless/nodejs20
USER nonroot

Sistema de arquivos raiz somente leitura

Um sistema de arquivos raiz somente leitura impede atacantes de escrever malware ou modificar configs em caso de comprometimento. Combine com tmpfs para diretórios de rascunho (/tmp, /cache) e volumes para dados persistentes. As apps precisam ser projetadas para isso — alguns frameworks escrevem em caminhos inesperados e precisam de mounts tmpfs.

docker
# make the root filesystem read-only
docker run --read-only nginx

# allow writes only to specific dirs via tmpfs
docker run --read-only --tmpfs /tmp --tmpfs /var/cache nginx

# combine with a writable volume for persistent data
docker run --read-only -v appdata:/data --tmpfs /tmp myapp

# compose form
services:
  web:
    image: nginx
    read_only: true
    tmpfs:
      - /tmp
      - /var/cache/nginx

# apps must be designed to not write outside allowed paths

Capabilities do Linux

Por padrão, o Docker concede um conjunto limitado de capabilities do Linux. Remova ALL e adicione de volta só o que a app precisa — o princípio do menor privilégio. --privileged concede todas as capabilities e acesso a dispositivos do host; evite totalmente, exceto para runtimes de contêiner confiáveis. Remova NET_RAW por padrão.

docker
# drop all capabilities, add only what's needed
docker run --cap-drop=ALL --cap-add=NET_BIND_SERVICE nginx

# add a specific capability
docker run --cap-add=SYS_PTRACE myapp

# common capabilities to drop (rarely needed by apps)
# CHOWN, DAC_OVERRIDE, FOWNER, KILL, NET_RAW, SETGID, SETUID

# NET_RAW is often safe to drop (prevents raw sockets/ping)
docker run --cap-drop=NET_RAW myapp

# privileged = all capabilities + host access (AVOID)
docker run --privileged myapp  # DANGEROUS

# inspect capabilities
docker inspect --format '{{json .HostConfig.CapAdd}}' <container>

Seccomp e AppArmor

Seccomp filtra quais syscalls um contêiner pode fazer — o perfil padrão bloqueia ~44 syscalls perigosas. AppArmor restringe acesso a arquivos e capabilities. no-new-privileges impede que binários setuid concedam novos privilégios — um endurecimento barato e de alto valor para qualquer contêiner.

docker
# default seccomp profile blocks dangerous syscalls
docker run --security-opt seccomp=default.json nginx

# custom seccomp profile
docker run --security-opt seccomp=/path/to/profile.json nginx

# disable seccomp (NOT recommended)
docker run --security-opt seccomp=unconfined nginx

# AppArmor profile
docker run --security-opt apparmor=docker-default nginx

# custom AppArmor profile
docker run --security-opt apparmor=myprofile nginx

# no-new-privileges (prevents setuid escalation)
docker run --security-opt no-new-privileges nginx

Escaneamento de imagens

Escaneie imagens em busca de vulnerabilidades conhecidas (CVEs) antes do push. docker scout (antes docker scan baseado no snyk) vem embutido. Trivy e Grype são alternativas populares. Integre o escaneamento ao CI para bloquear imagens com CVEs de severidade alta. Reescaneie imagens base periodicamente conforme novos CVEs são divulgados.

docker
# docker scout (built-in, replaces docker scan)
docker scout cves myapp:1.0

# scan a local image
docker scout cves --format json myapp:1.0

# compare two images
docker scout compare myapp:1.0 --to myapp:1.1

# Trivy (third-party, popular)
trivy image myapp:1.0

# Grype (third-party)
grype myapp:1.0

# scan a Dockerfile for bad practices
docker scout policy myapp --only-stream-default

# integrate scanning in CI
# - build image
# - scan
# - fail the pipeline on HIGH/CRITICAL CVEs

Docker Content Trust e hardening

Content Trust garante que você puxa imagens assinadas. Endureça o daemon: desabilite a comunicação entre contêineres (icc=false), habilite live-restore para que contêineres sobrevivam a reinícios do daemon e habilite namespaces de usuário (userns-remap) para mapear o root do contêiner a um UID de host não-root, com isolamento mais forte.

docker
# enable content trust (image signing)
export DOCKER_CONTENT_TRUST=1
docker pull myapp:1.0   # refuses unsigned

# sign on push
docker push myapp:1.0   # signs with your key

# daemon hardening in /etc/docker/daemon.json
# {
#   "userland-proxy": false,
#   "live-restore": true,
#   "no-new-privileges": true,
#   "icc": false   # disable inter-container communication on default bridge
# }

# restrict registry access
# "registry-mirrors": [],
# "insecure-registries": []

# audit the daemon
docker info --format '{{json .SecurityOptions}}'

# use user namespaces for host UID isolation
# /etc/docker/daemon.json: "userns-remap": "default"
19

Logs e monitoramento

Vendo logs

docker logs lê o stdout/stderr capturado pelo logging driver. As apps devem logar no stdout — não em arquivos — para integrar com docker logs. --tail e --since limitam a saída. Compose logs agrega entre serviços. O driver json-file padrão cresce sem limite se você não o limitar.

docker
# follow logs
docker logs -f web

# last 100 lines
docker logs --tail 100 web

# since a timestamp
docker logs --since 30m web

# with timestamps
docker logs -t web

# a specific time range
docker logs --since 1h --until 30m web

# write logs to a file
docker logs web > web.log 2>&1

# logs for all containers (compose)
docker compose logs -f
docker compose logs -f web db

Log drivers

O driver json-file cresce sem limite sem rotação — defina max-size e max-file para evitar esgotar o disco. Em produção, envie os logs para um sistema central (fluentd, splunk, awslogs, gelf). Defina um padrão global no daemon.json para que cada contêiner tenha rotação por padrão.

docker
# default: json-file
docker run -d --log-driver=json-file nginx

# cap log size and rotate (json-file)
docker run -d \
  --log-driver=json-file \
  --log-opt max-size=10m \
  --log-opt max-file=3 \
  nginx

# syslog
docker run -d --log-driver=syslog nginx

# journald
docker run -d --log-driver=journald nginx

# fluentd / splunk / gelf / awslogs
docker run -d --log-driver=fluentd nginx

# global default in /etc/docker/daemon.json
# { "log-driver": "json-file",
#   "log-opts": { "max-size": "10m", "max-file": "3" } }

Tags e atributos de log

O template tag personaliza os identificadores de log — usar {{.Name}} produz nomes de contêiner legíveis em vez de IDs truncados. Para fluentd/splunk, labels e variáveis de env são anexados aos registros de log para filtragem. Defina templates de tag no nível do daemon para que os contêineres sejam etiquetados de forma consistente.

docker
# tag logs with container name instead of ID
docker run -d \
  --log-driver=json-file \
  --log-opt tag="{{.Name}}" \
  nginx

# tag with image name and tag
--log-opt tag="{{.ImageName}}/{{.Name}}"

# fluentd: add labels and attributes
docker run -d \
  --log-driver=fluentd \
  --log-opt fluentd-address=localhost:24224 \
  --log-opt tag="docker.{{.Name}}" \
  --log-opt labels=app,env \
  --label app=web --label env=prod \
  nginx

# syslog with facility
docker run -d --log-driver=syslog \
  --log-opt syslog-facility=daemon nginx

Stats e monitoramento de recursos

stats transmite CPU, memória, rede e block IO. docker events é um fluxo em tempo real de eventos do daemon — útil para scripts de alerta. docker top mostra os processos dentro de um contêiner; docker diff mostra mudanças no sistema de arquivos (A=adicionado, C=alterado, D=excluído) desde a criação da imagem.

docker
# live stats for all containers
docker stats

# specific container, one snapshot
docker stats --no-stream web

# custom format
docker stats --format "table {{.Name}}	{{.CPUPerc}}	{{.MemUsage}}	{{.NetIO}}"

# events stream (start, stop, die, etc.)
docker events

# filter events
docker events --filter type=container --filter event=die

# container process list (like top)
docker top web

# container file changes since creation
docker diff web

Docker events

docker events é um fluxo em tempo real de eventos de ciclo de vida: create, start, stop, pause, die, destroy, além de eventos de imagem e rede. Filtre por type, event ou contêiner. É a base para scripts de alerta que reagem a mortes de contêineres ou reiniciam automaticamente serviços que falham.

docker
# stream all events
docker events

# container events only
docker events --filter type=container

# specific event types
docker events --filter event=start --filter event=die

# events for a specific container
docker events --filter container=web

# events since a timestamp
docker events --since 1h

# format output
docker events --format '{{.Time}} {{.Action}} {{.Actor.Attributes.name}}'

# pipe to a monitoring script
docker events --filter event=die | while read event; do
  echo "Container died: $event"
done

Stack Prometheus e Grafana

O cAdvisor expõe métricas por contêiner (CPU, memória, rede, filesystem) em formato Prometheus. O Prometheus coleta e armazena; o Grafana visualiza. É a stack de monitoramento open-source de fato para Docker. Adicione node-exporter para métricas do host e alertmanager para alertas.

docker
# run cAdvisor (container metrics exporter)
docker run -d --name cadvisor \
  -v /:/rootfs:ro -v /var/run:/var/run:ro \
  -v /sys:/sys:ro -v /var/lib/docker/:/var/lib/docker:ro \
  -p 8080:8080 gcr.io/cadvisor/cadvisor

# run Prometheus
docker run -d -p 9090:9090 \
  -v ./prometheus.yml:/etc/prometheus/prometheus.yml \
  prom/prometheus

# run Grafana
docker run -d -p 3000:3000 grafana/grafana

# scrape cAdvisor in prometheus.yml
# scrape_configs:
#   - job_name: cadvisor
#     static_configs:
#       - targets: ['cadvisor:8080']

# view dashboards in Grafana at http://localhost:3000
20

Docker Swarm

Inicializando o Swarm

swarm init transforma um host Docker em um manager do Swarm. O join token permite que workers e managers adicionais entrem. Mantenha os tokens de manager em segredo — eles podem controlar o cluster. Rode um número ímpar de managers (3 ou 5) para tolerância de consenso Raft. Workers executam tarefas; managers agendam.

docker
# initialize a Swarm (this node becomes a manager)
docker swarm init --advertise-addr 10.0.0.5

# get a join token for workers
docker swarm join-token worker

# get a join token for managers
docker swarm join-token manager

# on a worker node
docker swarm join --token SWMTKN-... 10.0.0.5:2377

# list nodes
docker node ls

# promote a worker to manager
docker node promote <node>

# demote a manager
docker node demote <node>

# leave the Swarm (worker)
docker swarm leave

Implantando serviços

Services são a abstração do Swarm sobre contêineres. Um serviço replicado roda N tarefas idênticas; um serviço global roda uma tarefa por nó. update lança uma nova imagem com zero downtime por padrão. scale muda a contagem de réplicas ao vivo. O Swarm remarca automaticamente se um nó falhar.

docker
# deploy a service
docker service create --name web -p 80:80 nginx

# with replicas
docker service create --name web --replicas 3 -p 80:80 nginx

# with a constraint (e.g. only on worker nodes)
docker service create --name web --replicas 3 \
  --constraint node.role==worker nginx

# with a global service (one per node)
docker service create --name log --mode global fluentd

# update the image
docker service update --image nginx:1.25 web

# scale a service
docker service scale web=5

# remove a service
docker service rm web

Escalonamento e atualizações

scale muda a contagem de réplicas instantaneamente. update faz atualizações rolling — parallelism controla quantas tarefas atualizam de uma vez, delay espaça as atualizações e failure-action=rollback reverte automaticamente em erros. O Swarm mantém as tarefas antigas rodando até as novas ficarem saudáveis, permitindo deploys sem downtime.

docker
# scale up
docker service scale web=10

# scale multiple services
docker service scale web=5 worker=8

# rolling update
docker service update --image myapp:2.0 web

# update with parallelism and delay
docker service update \
  --image myapp:2.0 \
  --update-parallelism 2 \
  --update-delay 30s \
  --update-failure-action rollback \
  web

# environment or port update without redeploy
docker service update --env-add DEBUG=true web
docker service update --publish-rm 80:80 --publish-add 8080:80 web

# rollback to previous version
docker service rollback web

Deploy de stack

Uma stack é um arquivo Compose implantado no Swarm. A chave deploy: configura réplicas, políticas de update/rollback, restrições de placement e recursos — tudo específico do Swarm. docker stack deploy aplica a especificação de forma declarativa. Stacks agrupam serviços, redes e secrets relacionados.

docker
# docker-compose.yml as a Swarm stack
docker stack deploy -c docker-compose.yml mystack

# the compose file uses deploy: for Swarm config
services:
  web:
    image: nginx
    deploy:
      replicas: 3
      update_config:
        parallelism: 1
        delay: 10s
      restart_policy:
        condition: on-failure
      placement:
        constraints: [node.role == worker]
    ports:
      - "80:80"

# list stacks and services
docker stack ls
docker stack services mystack

# remove a stack
docker stack rm mystack

Gerenciamento de nós

Coloque um nó em drain antes da manutenção para remarcad as tarefas dele graciosamente em outro lugar. Active/pause/drain controlam o agendamento. Labels permitem restrições de placement (por exemplo, rodar o DB só em nós com label tier=db). Remova um nó só depois de sair do Swarm com docker swarm leave.

docker
# list nodes
docker node ls

# node details (status, role, labels, resources)
docker node inspect <node>

# drain a node (reschedule tasks off it, for maintenance)
docker node update --availability drain <node>

# activate a drained node
docker node update --availability active <node>

# pause a node (no new tasks, existing stay)
docker node update --availability pause <node>

# add a label (for placement constraints)
docker node update --label-add tier=db <node>

# remove a node from the Swarm
docker node rm <node>
# (node must have left via 'docker swarm leave' first)

Secrets e configs

Secrets são criptografados em repouso e em trânsito, montados como arquivos em /run/secrets e nunca escritos em camadas de imagem ou variáveis de env. São imutáveis — para rotacionar, crie um novo secret e atualize o serviço. Configs são parecidos, mas para dados não sensíveis como arquivos de configuração. Ambos são exclusivos do Swarm.

docker
# create a secret from a file
docker secret create db_password ./db_password.txt

# create from stdin
echo "supersecret" | docker secret create db_password -

# use in a service
docker service create --name app --secret db_password myapp

# read in the app
# cat /run/secrets/db_password

# update a secret (immutable — create a new one)
echo "newsecret" | docker secret create db_password_v2 -
docker service update --secret-rm db_password --secret-add source=db_password_v2 app

# configs (non-sensitive, e.g. nginx.conf)
echo "server {...}" | docker config create nginx_conf -
docker service create --config nginx_conf nginx

# list and remove
docker secret ls
docker config ls

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.