Guia de Comandos Docker, do básico ao avançado, estruturado para funcionar tanto no onboarding de novos devs quanto como referência rápida no dia a dia.

Guia-de-Comandos-Docker.md

🐳 Guia de Comandos Docker

Este arquivo contém uma lista organizada e comentada dos comandos mais utilizados no Docker, cobrindo do nível básico ao avançado. Ideal para onboarding de novos desenvolvedores e consulta rápida de profissionais experientes.

---

⚙️ Configuração e Informações do Ambiente

Comando	Descrição
docker --version	Exibe a versão instalada do Docker.
docker info	Mostra informações detalhadas sobre o daemon Docker: containers ativos, imagens, runtime, storage driver e configurações do sistema.
docker login	Autentica no Docker Hub (ou outro registry configurado).
docker login registry.example.com	Autentica em um registry privado específico.
docker logout	Encerra a sessão autenticada no registry.
docker system df	Exibe o espaço em disco utilizado por imagens, containers e volumes.

---

🖼️ Imagens

Comando	Descrição
docker pull nome_imagem	Baixa uma imagem do registry (Docker Hub por padrão).
docker pull nome_imagem:tag	Baixa uma versão específica da imagem pela tag (ex: node:18-alpine).
docker images	Lista todas as imagens disponíveis localmente.
docker images -a	Lista todas as imagens, incluindo intermediárias.
docker build -t nome:tag .	Constrói uma imagem a partir do Dockerfile no diretório atual.
docker build -f caminho/Dockerfile -t nome:tag .	Constrói uma imagem usando um Dockerfile em caminho alternativo.
docker tag nome_imagem:tag usuario/repositorio:tag	Cria um alias para uma imagem, preparando-a para envio ao registry.
docker push usuario/repositorio:tag	Envia a imagem para o registry remoto.
docker rmi nome_imagem	Remove uma imagem local. ⚠️ Falha se houver containers usando a imagem.
docker rmi -f nome_imagem	⚠️ Força a remoção da imagem, mesmo que referenciada por containers parados.
docker image inspect nome_imagem	Exibe metadados detalhados da imagem em formato JSON.
docker history nome_imagem	Mostra as camadas que compõem a imagem e seus tamanhos.
docker save -o arquivo.tar nome_imagem	Exporta uma imagem para um arquivo .tar.
docker load -i arquivo.tar	Importa uma imagem a partir de um arquivo .tar.

---

📦 Containers

Comando	Descrição
docker run nome_imagem	Cria e inicia um container a partir da imagem.
docker ps	Lista os containers em execução.
docker ps -a	Lista todos os containers, incluindo os parados.
docker start id_ou_nome	Inicia um container previamente parado.
docker stop id_ou_nome	Envia sinal de parada graceful (SIGTERM) ao container.
docker kill id_ou_nome	⚠️ Encerra o container imediatamente via SIGKILL, sem aguardar finalização.
docker restart id_ou_nome	Reinicia um container em execução.
docker rm id_ou_nome	Remove um container parado.
docker rm -f id_ou_nome	⚠️ Força a remoção de um container, mesmo que esteja em execução.
docker exec -it id_ou_nome bash	Abre um terminal interativo dentro do container em execução.
docker exec id_ou_nome comando	Executa um comando pontual dentro do container sem abrir terminal.
docker logs id_ou_nome	Exibe os logs gerados pelo container.
docker logs -f id_ou_nome	Acompanha os logs em tempo real (modo follow).
docker logs --tail 100 id_ou_nome	Exibe apenas as últimas 100 linhas de log.
docker cp origem destino	Copia arquivos entre o host e o container (ex: docker cp app.log meu_container:/tmp/).
docker rename nome_antigo novo_nome	Renomeia um container existente.
docker pause id_ou_nome	Suspende todos os processos do container sem encerrá-lo.
docker unpause id_ou_nome	Retoma a execução de um container suspenso.
docker wait id_ou_nome	Bloqueia até o container encerrar e retorna o código de saída.

---

🚩 Flags Essenciais do docker run

As flags abaixo são combinadas ao comando docker run para controlar o comportamento do container.

Flag	Descrição
-d	Executa o container em background (modo detached).
-it	Combina terminal interativo (-i) com pseudo-TTY (-t). Usado para sessões de shell.
--name nome	Atribui um nome ao container em vez de usar o gerado automaticamente.
-p host:container	Mapeia uma porta do host para uma porta do container (ex: -p 8080:80).
-P	Mapeia automaticamente todas as portas expostas da imagem para portas aleatórias do host.
-v /host:/container	Monta um diretório do host como volume no container (bind mount).
--mount	Forma explícita e recomendada para montagem de volumes, com suporte a opções avançadas.
-e VAR=valor	Define uma variável de ambiente no container.
--env-file arquivo.env	Carrega variáveis de ambiente a partir de um arquivo.
--rm	Remove o container automaticamente ao encerrar. Útil para execuções pontuais.
--network nome	Conecta o container a uma rede Docker específica.
--restart always	Reinicia o container automaticamente em caso de falha ou reinicialização do daemon.
--restart unless-stopped	Reinicia automaticamente, exceto quando parado manualmente.
--memory 512m	Limita o uso de memória RAM do container.
--cpus 1.5	Limita o uso de CPU (número de cores).
--read-only	Monta o sistema de arquivos do container em modo somente leitura.
--user usuario	Define o usuário que executará os processos dentro do container.
--entrypoint comando	Sobrescreve o entrypoint definido na imagem.

---

💾 Volumes

Comando	Descrição
docker volume create nome_volume	Cria um volume gerenciado pelo Docker.
docker volume ls	Lista todos os volumes existentes.
docker volume inspect nome_volume	Exibe detalhes do volume: ponto de montagem, driver e metadados.
docker volume rm nome_volume	Remove um volume específico. ⚠️ Dados são perdidos permanentemente.
docker volume prune	⚠️ Remove todos os volumes não utilizados por nenhum container.

Volumes são a forma recomendada para persistência de dados em produção. Prefira volumes gerenciados a bind mounts sempre que possível.

---

🌐 Redes (Networks)

Comando	Descrição
docker network ls	Lista todas as redes Docker disponíveis.
docker network create nome_rede	Cria uma rede do tipo bridge (padrão).
docker network create --driver overlay nome_rede	Cria uma rede overlay para comunicação entre hosts (usado com Swarm).
docker network inspect nome_rede	Exibe detalhes da rede: containers conectados, gateway, sub-rede e configurações.
docker network connect nome_rede id_ou_nome	Conecta um container em execução a uma rede existente.
docker network disconnect nome_rede id_ou_nome	Desconecta um container de uma rede.
docker network rm nome_rede	Remove uma rede. ⚠️ Falha se houver containers conectados a ela.
docker network prune	⚠️ Remove todas as redes não utilizadas por nenhum container.

---

🧩 Docker Compose

Os comandos abaixo devem ser executados no diretório contendo o arquivo docker-compose.yml.

Comando	Descrição
docker compose up	Cria e inicia todos os serviços definidos no arquivo Compose.
docker compose up -d	Inicia os serviços em background (modo detached).
docker compose up --build	Reconstrói as imagens antes de iniciar os serviços.
docker compose down	Para e remove os containers e redes criados pelo Compose.
docker compose down -v	⚠️ Para e remove containers, redes e volumes. Dados persistidos nos volumes serão perdidos.
docker compose ps	Lista os containers gerenciados pelo Compose e seus estados.
docker compose logs	Exibe os logs de todos os serviços.
docker compose logs -f nome_servico	Acompanha os logs de um serviço específico em tempo real.
docker compose build	Constrói (ou reconstrói) as imagens dos serviços sem iniciá-los.
docker compose pull	Baixa as imagens definidas no Compose sem iniciar os serviços.
docker compose exec nome_servico bash	Abre terminal interativo dentro de um container do Compose em execução.
docker compose run nome_servico comando	Executa um comando pontual em um novo container do serviço.
docker compose stop	Para os containers sem removê-los.
docker compose restart nome_servico	Reinicia um serviço específico.
docker compose config	Valida e exibe a configuração final do arquivo Compose após merge de variáveis.
docker compose scale nome_servico=3	Escala um serviço para o número de réplicas informado.

---

🔍 Diagnóstico e Monitoramento

Comando	Descrição
docker stats	Exibe métricas em tempo real de todos os containers: CPU, memória, rede e I/O de disco.
docker stats id_ou_nome	Exibe métricas em tempo real de um container específico.
docker top id_ou_nome	Lista os processos em execução dentro do container.
docker inspect id_ou_nome	Retorna metadados completos do container em formato JSON: rede, volumes, configurações de runtime.
docker port id_ou_nome	Lista os mapeamentos de portas ativos do container.
docker diff id_ou_nome	Mostra as alterações feitas no sistema de arquivos do container desde sua criação.
docker events	Exibe eventos do daemon Docker em tempo real (start, stop, pull, etc.).
docker events --filter type=container	Filtra eventos por tipo de recurso (container, image, network, volume).

---

🧹 Limpeza e Manutenção

Comando	Descrição
docker container prune	⚠️ Remove todos os containers parados.
docker image prune	⚠️ Remove imagens intermediárias (dangling) sem tag associada.
docker image prune -a	⚠️ Remove todas as imagens não utilizadas por nenhum container ativo.
docker volume prune	⚠️ Remove todos os volumes não referenciados por containers.
docker network prune	⚠️ Remove todas as redes sem containers conectados.
docker system prune	⚠️ Remove containers parados, redes, imagens dangling e cache de build.
docker system prune -a	⚠️ Remove tudo que não estiver em uso ativo: containers, imagens, redes e volumes órfãos. Use com cautela em ambientes compartilhados.
docker system prune --volumes	⚠️ Inclui volumes na limpeza geral do sistema.
docker builder prune	⚠️ Remove o cache do build do Docker (camadas intermediárias armazenadas).

---

✅ Boas Práticas e Observações Importantes

• Prefira imagens baseadas em alpine ou slim para reduzir a superfície de ataque e o tamanho das imagens em produção.
• Nunca execute aplicações dentro de containers como usuário root em produção. Use a flag --user ou defina o USER no Dockerfile.
• Use .dockerignore para excluir arquivos desnecessários do contexto de build (como node_modules, .git e arquivos de ambiente).
• Evite armazenar segredos (senhas, tokens, chaves de API) como variáveis de ambiente em imagens. Prefira Docker Secrets ou soluções de vault.
• Em repositórios compartilhados, prefira docker revert a operações destrutivas de histórico. Aplique o mesmo princípio ao ciclo de vida de containers: prefira docker stop a docker kill.
• Sempre defina tags explícitas nas imagens (ex: node:18-alpine). Evite a tag latest em ambientes de produção por ser imprevisível.
• Utilize multi-stage builds no Dockerfile para separar o ambiente de build do artefato final, reduzindo significativamente o tamanho da imagem gerada.
• Volumes gerenciados pelo Docker (docker volume create) são mais portáveis e recomendados em relação a bind mounts para persistência de dados em produção.
• Redes bridge customizadas permitem resolução de nomes entre containers (DNS interno). Evite usar a rede bridge padrão em ambientes com múltiplos serviços.
• Execute docker system df periodicamente para monitorar o consumo de disco e programe limpezas regulares com docker system prune em ambientes de CI/CD.
• Valide o docker-compose.yml antes de subir os serviços com docker compose config. Isso evita falhas silenciosas por variáveis não resolvidas.

---

🙋 Autor

Moisés Tedeschi de Melo [MOA]

---

📁 Este material pode ser expandido com novos comandos e cenários conforme a evolução do ambiente. Contribuições são bem-vindas!