🐳 Docker — Folha de Consulta para Iniciantes

Referência de uma página com os conceitos, comandos e erros comuns do Docker. Versão de referência: v27 · 2025

---

📑 Índice

• Conceitos principais
• Ciclo de vida do container
• Comandos essenciais
  • Containers
  • Images
  • Limpeza
• Dockerfile
• Docker Compose
• Referência rápida — 30 segundos
• Erros comuns
• Dica de ouro
• Links úteis

---

🧩 Conceitos principais

Conceito	O que é
Image	Template somente-leitura. Receita para criar containers. Armazenada em layers.
Container	Instância em execução de uma image. Isolado e efêmero por padrão.
Volume	Persistência de dados fora do container. Sobrevive ao rm.
Network	Rede virtual que permite containers se falarem por nome.
Dockerfile	Script de build. Define como a image é construída em layers.
Registry	Repositório de images. O Docker Hub é o padrão público.
Compose	Orquestra múltiplos containers com um único arquivo YAML.
Layer	Camada cacheada da image. Cada instrução no Dockerfile = 1 layer.

---

🔄 Ciclo de vida do container

created  →  running  →  paused  →  stopped  →  deleted

Estado	Significado
created	Container criado, mas ainda não iniciado.
running	Em execução.
paused	Processos congelados temporariamente.
stopped	Parado, mas ainda existe no disco.
deleted	Removido do sistema.

---

⚡ Comandos essenciais

Containers

docker run -d -p 8080:80 nginx     # roda em background mapeando porta
docker run -it ubuntu bash         # modo interativo
docker ps                          # containers ativos
docker ps -a                       # todos (incluindo parados)
docker stop <id>                   # para o container
docker rm <id>                     # remove (precisa estar parado)
docker rm -f <id>                  # força a remoção
docker exec -it <id> sh            # entra no container
docker logs -f <id>                # logs em tempo real
docker stats                       # uso de CPU/RAM

Images

docker pull nginx:alpine           # baixa uma image
docker build -t app:1.0 .          # constrói a partir do Dockerfile
docker images                      # lista imagens locais
docker rmi <image>                 # remove uma image
docker push user/app:1.0           # envia ao Hub

Limpeza

docker system prune                # remove tudo que está parado/sem uso
docker volume prune                # remove volumes sem uso

⚠️ prune apaga recursos de forma definitiva. Use com atenção.

---

📦 Dockerfile

Instruções mais usadas:

Instrução	Função
FROM	Imagem base (sempre primeiro).
WORKDIR	Define o diretório de trabalho.
COPY	Copia arquivos do host para a image.
RUN	Executa comandos durante o build.
ENV	Define variável de ambiente.
EXPOSE	Documenta a porta (não abre sozinha).
CMD	Comando padrão ao iniciar o container.
ENTRYPOINT	Ponto de entrada fixo.
USER	Define usuário não-root (segurança).

Exemplo real

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./        # cache layer: só reinstala se mudar
RUN npm ci --only=production
COPY . .
USER node                    # não rode como root
EXPOSE 3000
CMD ["node", "server.js"]

---

🐙 Docker Compose

Comandos

docker compose up -d               # sobe os serviços em background
docker compose down                # para e remove os containers
docker compose -f arquivo.yml up   # usa um arquivo específico
docker compose exec app sh         # entra em um serviço
docker compose build --no-cache    # rebuild ignorando o cache

Exemplo de docker-compose.yml

services:
  app:
    build: .
    ports: ["3000:3000"]
    environment:
      - DB_URL=${DB_URL}
    depends_on: [db]
    volumes:
      - ./src:/app/src
  db:
    image: postgres:16
    volumes: [pgdata:/data]
    environment:
      POSTGRES_PASSWORD: ${PASS}

volumes:
  pgdata:

---

🚀 Referência rápida — 30 segundos

Rodar container (docker run)

Flag	Efeito
(padrão)	docker run nginx — execução básica.
-d	Roda em background.
-p 8080:80	Mapeia porta host:container.
-v vol:/path	Monta um volume.
-e KEY=val	Define variável de ambiente.
--rm	Remove o container ao sair.
--name meu	Dá um nome ao container.
--network net	Conecta a uma rede.

Inspecionar

docker inspect <id>    # tudo sobre o container
docker top <id>        # processos internos
docker diff <id>       # arquivos alterados
docker history img     # layers da imagem
docker port <id>       # mapeamentos de porta

Volumes

docker volume ls           # lista
docker volume inspect v    # detalhes
docker volume rm v         # remove

Redes

docker network ls              # lista redes
docker network create n        # cria rede
docker network connect n c     # conecta container à rede
docker network inspect n       # quem está na rede

Compose rápido

up -d              # sobe os serviços
down -v            # para e apaga volumes
ps                 # status dos serviços
restart <svc>      # reinicia um serviço
scale web=3        # múltiplas instâncias

---

🐛 Erros comuns

Problema	Causa	Solução
Dados somem ao reiniciar	Container é efêmero.	Use um volume: -v mydata:/data.
localhost não conecta entre containers	localhost aponta para o próprio container.	Use o nome do serviço como host no Compose.
Senhas no Dockerfile / Compose	Segredos versionados.	Use .env + adicione ao .gitignore.
Sem .dockerignore	node_modules, .git etc. entram na imagem.	Sempre crie o arquivo .dockerignore.
Container em loop de restart	Erro na inicialização.	Veja docker logs <id> antes de qualquer coisa.
Cache de build desatualizado	Layers reaproveitadas indevidamente.	Force com docker build --no-cache.
Rodar como root dentro do container	Risco de segurança.	Adicione USER node (ou seu usuário) no Dockerfile.
Porta não abre no host	EXPOSE apenas documenta.	Mapeie de fato com -p 8080:80.
Imagem enorme	Muitas layers e dependências.	Use tag :alpine e combine RUN com &&.

---

💡 Dica de ouro

Combine atualização, instalação e limpeza em um único RUN para manter as layers pequenas:

RUN apt update && apt install -y curl \
    && rm -rf /var/lib/apt/lists/*

Cada RUN cria uma layer — juntar tudo evita carregar lixo de cache na imagem final.

---

🔗 Links úteis

• 📚 Documentação oficial
• 🐳 Docker Hub
• 📝 Referência do Dockerfile
• ⚙️ Referência do Compose

---

📄 Licença

Distribuído sob a licença MIT. Sinta-se livre para usar, adaptar e compartilhar.

---

_{Folha de consulta Docker — uma página · feito para iniciantes 🐳}