Guia de Referência Docker
Guia de Comandos Docker
Referência prática e direta para empacotar, executar, versionar e orquestrar aplicações em containers — do Dockerfile ao docker compose.
Dockerfile
O Dockerfile é um arquivo de texto com as instruções, executadas de cima para baixo, que descrevem como construir uma imagem. Cada instrução gera uma camada (layer) cacheada.
Estrutura de um Dockerfile
FROM node:20-alpine # imagem base
WORKDIR /app # diretório de trabalho
COPY package*.json ./ # copia só os manifestos (cache)
RUN npm install # instala dependências
COPY . . # copia o restante do código
ENV NODE_ENV=production # variável de ambiente
EXPOSE 3000 # porta documentada
CMD ["node", "server.js"] # comando padrão ao iniciarPrincipais instruções
| Instrução | Função |
|---|---|
FROM | Define a imagem base (sempre a primeira instrução). |
WORKDIR | Define/cria o diretório de trabalho dentro da imagem. |
COPY / ADD | Copia arquivos do host para a imagem (ADD também extrai .tar e baixa URLs). |
RUN | Executa comandos durante o build (gera camada). |
CMD | Comando padrão de execução do container (pode ser sobrescrito). |
ENTRYPOINT | Define o executável fixo do container. |
ENV | Define variáveis de ambiente. |
ARG | Variável disponível apenas durante o build. |
EXPOSE | Documenta a porta usada pela aplicação. |
VOLUME | Cria ponto de montagem para dados persistentes. |
LABEL | Adiciona metadados (autor, versão, etc). |
Dica de cache: copie package.json e rode o install antes de copiar o código todo. Assim o Docker reaproveita a camada de dependências quando só o código muda.
Boas práticas: .dockerignore
node_modules
.git
.env
*.log
Dockerfile
distCriação de Imagens
Uma imagem é o modelo imutável e empacotado da aplicação. O comando docker build lê o Dockerfile e produz essa imagem.
# Build a partir do diretório atual ( . = contexto )
docker build -t minha-app:1.0 .
# Especificando outro nome de Dockerfile
docker build -f Dockerfile.prod -t minha-app:prod .
# Passando argumentos de build (ARG)
docker build --build-arg VERSION=2.1 -t minha-app .
# Build sem usar cache
docker build --no-cache -t minha-app .Gerenciando imagens
docker images # lista imagens locais
docker image ls # equivalente moderno
docker image inspect minha-app # detalhes em JSON
docker history minha-app:1.0 # camadas da imagem
docker rmi minha-app:1.0 # remove uma imagem
docker image prune -a # remove imagens não usadasMulti-stage build: use mais de um FROM para compilar em um estágio e copiar só o resultado final para uma imagem enxuta — reduz drasticamente o tamanho final.
Execução de Containers
Um container é uma instância em execução de uma imagem. O docker run cria e inicia o container.
# Executar em segundo plano (-d) mapeando porta (-p host:container)
docker run -d -p 8080:3000 --name web minha-app:1.0
# Modo interativo com terminal (-it)
docker run -it ubuntu bash
# Variáveis de ambiente e volume
docker run -e NODE_ENV=dev -v $(pwd):/app minha-app
# Remover o container automaticamente ao parar (--rm)
docker run --rm minha-app npm testFlags mais usadas no run
| Flag | O que faz |
|---|---|
-d | Detached: roda em segundo plano. |
-p 8080:3000 | Mapeia porta do host → container. |
-it | Interativo + terminal (TTY). |
--name | Define um nome para o container. |
-e | Define variável de ambiente. |
-v | Monta volume / bind mount. |
--rm | Remove o container ao finalizar. |
--restart | Política de reinício (ex: always). |
Ciclo de vida e inspeção
docker ps # containers em execução
docker ps -a # inclui os parados
docker stop web # para o container
docker start web # inicia novamente
docker restart web # reinicia
docker rm web # remove o container
docker logs -f web # acompanha os logs
docker exec -it web bash # abre shell dentro do container
docker stats # uso de CPU/memória em tempo real
docker cp web:/app/log.txt . # copia arquivo do containerTags & Versionamento
Tags identificam versões de uma imagem no formato repositorio:tag. Sem tag explícita, o Docker assume :latest.
# Criar uma nova tag a partir de uma imagem existente
docker tag minha-app:1.0 minha-app:latest
# Taguear apontando para um usuário do Docker Hub
docker tag minha-app:1.0 usuario/minha-app:1.0
# Versionamento semântico recomendado
docker tag minha-app:1.0 minha-app:1.0.3
docker tag minha-app:1.0 minha-app:stableBoa prática: evite confiar só em :latest em produção. Use SemVer (MAJOR.MINOR.PATCH) — ex.: 2.4.1 — para builds reproduzíveis e rollback seguro.
Inspecionando versões
docker images minha-app # todas as tags do repositório
docker inspect --format '{{.Id}}' minha-app:1.0 # ID exato (digest)Docker Hub
O Docker Hub é o registro público padrão para armazenar e compartilhar imagens. Você também pode usar registries privados (GHCR, ECR, etc).
# Autenticar no Docker Hub
docker login
# Enviar (publicar) sua imagem
docker push usuario/minha-app:1.0
# Baixar uma imagem do registro
docker pull nginx:alpine
# Procurar imagens públicas
docker search postgres
# Sair / encerrar sessão
docker logoutFluxo completo: build → tag com usuario/imagem:versao → login → push. Para registries privados, prefixe a URL: ghcr.io/usuario/app:1.0.
Comunicação entre Containers
Containers na mesma rede bridge personalizada se enxergam pelo nome, sem precisar expor portas para o host. Esse é o mecanismo de DNS interno do Docker.
# Criar uma rede
docker network create minha-rede
# Listar e inspecionar redes
docker network ls
docker network inspect minha-rede
# Subir containers na mesma rede
docker run -d --name db --network minha-rede postgres
docker run -d --name api --network minha-rede minha-app
# Conectar um container existente a uma rede
docker network connect minha-rede web
# Remover uma rede
docker network rm minha-redeResolução por nome: com os containers acima na mesma rede, a api conecta ao banco usando o host db (ex.: postgres://db:5432) — sem IPs fixos.
Tipos de rede (driver)
- bridge — padrão; isola containers em uma rede virtual no host.
- host — usa diretamente a rede do host (sem isolamento de porta).
- none — sem rede, container totalmente isolado.
- overlay — conecta containers em hosts diferentes (Swarm).
Docker Compose
O Compose define e orquestra múltiplos containers (serviços) por meio de um único arquivo compose.yaml. Ideal para apps com banco, API, cache, etc.
Exemplo de compose.yaml
services:
api:
build: .
ports:
- "8080:3000"
environment:
- NODE_ENV=production
depends_on:
- db
networks:
- app-net
db:
image: postgres:16
environment:
- POSTGRES_PASSWORD=secret
volumes:
- dbdata:/var/lib/postgresql/data
networks:
- app-net
volumes:
dbdata:
networks:
app-net:Comandos do Compose
docker compose up -d # sobe todos os serviços em background
docker compose up --build # reconstrói as imagens antes de subir
docker compose ps # status dos serviços
docker compose logs -f api # logs de um serviço
docker compose exec api bash # shell dentro do serviço
docker compose stop # para os serviços
docker compose down # remove containers e redes
docker compose down -v # remove também os volumesAtenção: a partir do Docker moderno o comando é docker compose (plugin V2, sem hífen). O antigo docker-compose (com hífen) é a V1 legada.
Comandos Úteis & Limpeza
Comandos do dia a dia para diagnóstico, manutenção e liberação de espaço.
Volumes e persistência
docker volume create meus-dados
docker volume ls
docker run -v meus-dados:/app/data minha-app
docker volume prune # remove volumes órfãosDiagnóstico e sistema
docker version # versão do cliente e do engine
docker info # estado geral do Docker
docker system df # uso de disco
docker top web # processos do containerLimpeza geral (cuidado!)
docker container prune # remove containers parados
docker image prune -a # remove imagens não usadas
docker system prune -a --volumes # LIMPA TUDO que não está em usoAtenção: system prune -a --volumes apaga imagens, containers parados, redes e volumes não usados de uma vez. Confira o que está em uso antes de executar.