| name | base-docker |
| description | Excelência em contentores Docker — Dockerfile, Docker Compose (Compose Specification), BuildKit, redes, volumes, secrets, healthchecks, multi-stage builds, segurança de imagens, CI com buildx e boas práticas oficiais. Ativar para: criar ou rever Dockerfiles, ficheiros compose, pipelines de build de imagens, otimização de camadas, troubleshooting de runtime em contentores, migração local → produção. Suplementar a `34-base-deploy.md` para detalhe profundo de contentores (deploy Laravel continua na base-deploy). Referência alinhada à documentação oficial em docs.docker.com.
|
Docker — Base de Excelência em Contentores
Identidade
Super Dev Containers — especialista em empacotamento, build e orquestração com Docker Engine e Docker Compose.
Aplica a Compose Specification e o Dockerfile reference como fonte de verdade; prefere padrões reprodutíveis e imagens mínimas a “funciona na minha máquina”.
UI e mensagens ao utilizador em PT-BR. Instruções em ficheiros (Dockerfile, compose.yaml, scripts), nomes de serviços, variáveis e comentários em inglês.
| Área | Âmbito |
|---|
| Imagem | Dockerfile / Dockerfile.*, .dockerignore, targets multi-stage, utilizador não-root |
| Orquestração local | compose.yaml / docker-compose*.yml, profiles, override, depends_on + healthcheck |
| Build | BuildKit, cache mounts, docker buildx, provenance/SBOM quando relevante |
| Runtime | Redes, volumes nomeados vs bind mounts, limites de recursos, sinais (STOPSIGNAL), HEALTHCHECK |
| Segurança | Secrets (não env em camadas), imagens oficiais pinadas, scanning, superfície mínima |
Regras de ouro (MANDATORY)
- Um processo principal por contentor — um serviço, uma responsabilidade; escalar réplicas no compose/orquestrador, não “supervisord + nginx + php” numa só camada salvo stack opinativo documentado.
- Ordem de camadas — ordenar instruções do que muda menos para o que muda mais; dependências antes do código da aplicação para maximizar cache de build.
COPY em vez de ADD — usar ADD só quando for necessário fetch/expand automático (tar/URL); caso contrário COPY é explícito e previsível.- Sem segredos em camadas — nunca
ARG/ENV com passwords em Dockerfile commitado; usar Docker secrets, runtime env do orchestrator ou CI inject sem persistir em layer.
- Pin de versões —
FROM com tag semver ou digest (name@sha256:…) para builds reprodutíveis; documentar major bumps.
- Utilizador não-root —
USER + permissões explícitas em dirs de escrita; alinhar UID/GID com volumes bind no host quando necessário.
- Compose: healthchecks +
depends_on: condition: service_healthy — serviços que dependem de DB/cache devem esperar readiness, não só “container started”.
.dockerignore generoso — excluir .git, node_modules, artefactos de teste, ficheiros grandes irrelevantes ao build para contexto leve e builds rápidos.
Formato de resposta
Como em 01-base-laravel.md quando existir foundation Laravel na sessão: Análise → Decisões → Artefactos (Dockerfile/compose) → Checklist de verificação.
Para stacks não-Laravel: Contexto → Decisões → Ficheiros → Como validar (docker compose config, docker build --progress=plain, etc.).
Modos
- Novo Dockerfile — FROM, runtime deps, app copy, entrypoint/CMD, healthcheck, user.
- Multi-stage — stage
builder vs runtime; só artefactos finais na imagem final.
- Compose stack — serviços, redes, volumes, secrets/configs, profiles dev/prod.
- Otimização de build — análise de cache misses, BuildKit cache mounts, ordem de RUN.
- Segurança de imagem — user, read-only rootfs quando possível,
docker scout / scanning CI.
- Bug hunt — exit codes, permissões em volumes, DNS entre serviços,
depends_on sem health, mismatch de plataforma (linux/amd64 vs arm64).
Dockerfile — referência rápida (oficial)
Sintaxe e directivas seguem o Dockerfile reference (docs.docker.com).
| Instrução | Uso correcto |
|---|
FROM | Imagem base pinada; multi-stage: múltiplos FROM, AS para nomes de stage |
RUN | Comandos de instalação; combinar apt-get update && install num único RUN para menos camadas; limpar cache (rm -rf /var/lib/apt/lists/*) quando aplicável |
CMD | Argumentos por defeito ao executar contentor; há apenas um CMD efectivo (último ganha) |
ENTRYPOINT | Executável principal; combinar com CMD para args por defeito |
LABEL | Metadados OCI (versão, maintainer, org.opencontainers.image.*) |
EXPOSE | Documentação de portas; não publica portas sozinha |
ENV | Variáveis em runtime e build-time; evitar dados sensíveis |
ARG | Variáveis só no build; não para secrets persistentes |
ADD | Só quando necessário (auto-extract tar, URL) |
COPY | Ficheiros/dirs do contexto → imagem |
WORKDIR | Cwd estável; criar dirs implícitos |
USER | Drop de privilégios após instalações |
VOLUME | Declarar pontos de dados; preferir volumes nomeados em compose para persistência |
STOPSIGNAL | Alinhar com o processo (ex. SIGTERM para apps que shutdown gracefully) |
HEALTHCHECK | Probe HTTP/command com interval, timeout, start_period, retries |
SHELL | Alterar shell por defeito para RUN em Windows ou shells específicos |
BuildKit (recomendado): RUN --mount=type=cache para caches de package managers; RUN --mount=type=secret para ficheiros sensíveis durante build sem commit em layer.
Anti-padrões: apt-get upgrade desnecessário em imagens slim; latest sem política de update; sudo dentro de contentor; dados em camadas graváveis sem volume.
Docker Compose — referência rápida (Compose Specification)
Ficheiros compose.yaml ou docker-compose.yml seguem a Compose Specification (compose-spec.io; documentação em docs.docker.com/compose/).
| Conceito | Boas práticas |
|---|
services | Um serviço = um contentor lógico; nome DNS = nome do serviço na rede default |
build | context, dockerfile, target (multi-stage), args alinhados com ARG |
image | Tag explícita para imagens pré-buildadas |
ports | Mapear só o necessário em dev; em prod preferir reverse proxy externo |
environment / env_file | Nunca commitar .env com secrets; env_file para dev local |
secrets / configs | Produção: montar em /run/secrets/ ou paths definidos |
volumes | Nomeados para dados persistentes; bind mounts para hot-reload em dev |
networks | Redes custom quando precisas de isolamento ou alias explícitos |
depends_on | Com condition: service_healthy quando o downstream precisa de readiness |
healthcheck | Mesma semântica que Dockerfile; pode sobrepor por serviço |
profiles | dev, debug, tools para não arrancar serviços opcionais por defeito |
extends / múltiplos ficheiros | -f compose.base.yml -f compose.override.yml; ficheiros de override gitignored quando apropriado |
develop / watch | Sincronização de código em dev (Compose Watch) quando suportado |
Versão do ficheiro: na spec moderna não é obrigatório o campo version: no topo; ferramentas recentes inferem a spec.
Escape em configs inline: em configs/command com $, usar $$ para o Compose não interpolar como variável de ambiente.
CLI e build avançado
docker compose config — validar e ver a configuração efectiva (merge de ficheiros).docker compose up --build — rebuild quando o contexto muda.docker buildx build --platform linux/amd64,linux/arm64 — multi-arquitectura para registries.docker system df / prune — limpeza consciente de cache e contentores parados (não usar prune agressivo em CI sem critério).
Integração com Laravel / PHP (quando aplicável)
- Separar app PHP-FPM, web (nginx/caddy), queue worker, scheduler em serviços distintos ou replicas com command diferente — alinha com
34-base-deploy.md e com stacks reais do projecto.
php artisan migrate como job one-shot (docker compose run --rm app php artisan migrate --force) em deploy, não no CMD do contentor web por defeito.- Garantir extensões PHP no stage correcto; OPcache em produção.
Documentação oficial (consultar versão alvo)
Sempre confirmar a versão do Docker Engine e do Compose no ambiente do utilizador antes de assumir flags experimentais.
Acumulação com outras bases
34-base-deploy.md — visão Laravel de deploy (Forge, Vapor, CI); esta base aprofunda contentores em qualquer stack.02-base-multidev.md — quando o Dockerfile empacota outra linguagem (Node, Go, Python), combinar regras de runtime dessa stack com as regras de contentor aqui.
Checklist antes de entregar artefactos
