Guia 03 / 3
Dockerfile e compose.yaml
Compreender cada instrução e as suas consequências no build ou na execução.
Explicar o ciclo Dockerfile → imagem → contentor e configurar serviços Compose.
01 · Como os ficheiros trabalham em conjunto
Um Dockerfile descreve como fabricar uma imagem; compose.yaml descreve como executar os serviços. Não são linguagens de programação nem, a rigor, a API HTTP do Docker Engine.
Dockerfile
Receita de construção da imagem. As suas instruções são tratadas principalmente durante docker build.
Exemplo
Dockerfile → docker build → image
compose.yaml
Declaração YAML de serviços, volumes e redes. O Compose interpreta esta configuração para criar e fazer funcionar os contentores.
Exemplo
compose.yaml → docker compose up → services
API do Docker Engine
Interface HTTP do daemon Docker utilizada pelos clientes para comandar o Engine. As palavras FROM, RUN e CMD são instruções do Dockerfile, e não chamadas a esta API.
Exemplo
La CLI peut interroger l’API du démon pour lister des conteneurs.
02 · Instruções do Dockerfile
As instruções são lidas por ordem durante a construção; umas preparam a imagem, outras definem valores utilizados no arranque.
FROM
Escolhe a imagem de base e inicia uma etapa de build. Uma imagem de base já contém um sistema mínimo ou ferramentas.
Exemplo
FROM python:3.13-slim
Privilegiar uma referência explícita e mantida.
RUN
Executa um comando no momento de construir a imagem: instalar uma biblioteca, gerar um ficheiro, preparar uma pasta. O seu resultado integra a imagem.
Exemplo
RUN pip install --no-cache-dir -r requirements.txt
RUN não inicia o servidor quando se lança o contentor.
CMD
Define o comando por omissão executado no lançamento do contentor, ou argumentos para ENTRYPOINT. Um comando de docker run pode substituí-lo.
Exemplo
CMD ["python", "app.py"]
Apenas o último CMD do Dockerfile produz efeito.
ENTRYPOINT
Determina o programa a executar quando o contentor arranca. Esse programa torna-se geralmente o processo principal (PID 1), por exemplo o servidor web ou o script da aplicação.
Exemplo
ENTRYPOINT ["python", "app.py"]
CMD pode completar ENTRYPOINT com argumentos.
COPY
Copia ficheiros do contexto de construção para a imagem. O destino é um caminho no interior da imagem, e não na máquina anfitriã.
Exemplo
COPY ./src /app/src
ADD
Acrescenta ficheiros e oferece funcionalidades suplementares (fontes remotas, arquivos locais consoante o caso). Para uma simples cópia, privilegiar COPY.
Exemplo
ADD archive.tar.gz /opt/app/
ADD não é um comando genérico de transferência.
WORKDIR
Define a pasta de trabalho para as instruções seguintes e o comando por omissão. É criada se necessário.
Exemplo
WORKDIR /app
ENV
Define uma variável disponível durante as instruções seguintes e nos contentores baseados na imagem.
Exemplo
ENV APP_MODE=production
Não inscrever segredos nela.
ARG
Define um valor utilizado durante o build, eventualmente transmitido por --build-arg; não é automaticamente uma variável de ambiente de execução.
Exemplo
ARG APP_VERSION=1.0
EXPOSE
Documenta a porta ou as portas de rede em que a aplicação deve escutar. Isto informa os leitores e algumas ferramentas, mas não torna o serviço acessível a partir do anfitrião.
Exemplo
EXPOSE 3000
Para aceder a partir do seu computador: docker run -p 8080:3000 ...
USER
Define o utilizador usado para as instruções ou o arranque seguintes. Fazer funcionar uma aplicação sem direitos de root limita certos riscos.
Exemplo
USER app
HEALTHCHECK
Define um teste periódico que indica se a aplicação funciona realmente, para além da simples presença do seu processo.
Exemplo
HEALTHCHECK CMD wget -q -O - http://localhost:3000/health || exit 1
O programa utilizado para testar deve estar presente na imagem.
LABEL
Acrescenta metadados em pares chave=valor, úteis para a rastreabilidade.
Exemplo
LABEL org.opencontainers.image.title="Mon API"
VOLUME
Declara um ponto de montagem previsto para dados. Na prática, a persistência configura-se muitas vezes no Docker Compose.
Exemplo
VOLUME /data
SHELL
Altera o programa interpretador utilizado pelas instruções em forma shell.
Exemplo
SHELL ["/bin/sh", "-c"]
ONBUILD
Regista uma instrução desencadeada quando esta imagem servir posteriormente de imagem de base a outro Dockerfile.
Exemplo
ONBUILD COPY . /app
.dockerignore
Ficheiro ao lado do contexto de build que retira ficheiros do contexto transmitido ao construtor; permite excluir caches, dependências locais e dados sensíveis.
Exemplo
node_modules
.git
.env
03 · Chaves de compose.yaml
A indentação YAML constrói uma hierarquia: services contém web e db; cada serviço contém os seus parâmetros. Os nomes indicados abaixo são chaves de configuração, e não comandos.
name
Nome lógico do projeto Compose, utilizado para distinguir os seus recursos dos de outros projetos.
Exemplo
name: demo-web
services
Secção raiz que contém todos os serviços da aplicação. Um serviço descreve a imagem e a configuração dos seus contentores.
Exemplo
services:
web:
image
Imagem a utilizar: ou obtida de um registo, ou associada ao resultado do build consoante a configuração.
Exemplo
image: nginx:alpine
build
Indica ao Compose como fabricar uma imagem. Pode ser um caminho curto ou um objeto detalhado.
Exemplo
build:
context: .
dockerfile: Dockerfile
context
Caminho dos ficheiros enviados ao construtor. O ponto representa o diretório do projeto Compose. É distinto de WORKDIR na imagem.
Exemplo
context: .
dockerfile
Caminho de um ficheiro de construção alternativo, interpretado relativamente ao contexto de build.
Exemplo
dockerfile: docker/Dockerfile
ports
Publica uma porta do contentor no anfitrião. A sintaxe curta «8080:3000» lê-se anfitrião:contentor.
Exemplo
ports:
- "8080:3000"
Sem ports, os contentores de uma mesma rede podem frequentemente comunicar diretamente entre si.
expose
Documenta as portas internas de um serviço, sem as publicar no anfitrião.
Exemplo
expose:
- "3000"
volumes (serviço)
Monta um armazenamento no contentor: um volume com nome ou um caminho do anfitrião.
Exemplo
volumes:
- db_data:/var/lib/postgresql/data
volumes (raiz)
Declara os volumes com nome geridos pelo projeto, reutilizados pelos serviços.
Exemplo
volumes:
db_data:
networks
Associa os serviços a uma ou várias redes; os nomes de serviço servem muitas vezes para comunicar.
Exemplo
networks:
- interne
environment
Variáveis transmitidas ao processo do contentor. Podem modificar as portas, o modo de execução ou comportamentos aplicacionais.
Exemplo
environment:
NODE_ENV: production
Para credenciais, privilegiar um mecanismo de segredos.
env_file
Carrega as variáveis de ambiente a partir de um ficheiro de texto de pares chave=valor.
Exemplo
env_file:
- .env.app
Evitar fazer commit de segredos reais no Git.
depends_on
Controla as dependências e a ordem de criação dos serviços. Não garante que a aplicação dependente esteja pronta sem uma condição de saúde.
Exemplo
depends_on:
db:
condition: service_healthy
restart
Indica a estratégia de reinício aplicada a um contentor.
Exemplo
restart: unless-stopped
healthcheck
Teste periódico de saúde de um serviço; permite ao Compose reconhecer o estado healthy e condicionar dependências.
Exemplo
healthcheck:
test: ["CMD", "pg_isready", "-U", "app"]
interval: 10s
command
Substitui o comando por omissão da imagem no arranque (muitas vezes o CMD).
Exemplo
command: ["node", "server.js"]
entrypoint
Substitui o executável de entrada definido na imagem para um serviço.
Exemplo
entrypoint: ["/app/start.sh"]
profiles
Permite ativar apenas certos serviços opcionais, como ferramentas de depuração.
Exemplo
profiles: ["debug"]
secrets
Declara dados sensíveis e distribui-os a certos serviços sob a forma de ficheiros.
Exemplo
secrets:
- db_password
build.args
Transmite parâmetros aos ARG do Dockerfile durante a construção.
Exemplo
build:
args:
APP_VERSION: "1.0"
deploy
Agrupa opções de implementação, como certos limites de recursos ou réplicas, consoante o modo de execução e o seu suporte.
Exemplo
deploy:
resources:
limits:
memory: 512M
version (herança)
Antigo campo de compatibilidade que se tornou obsoleto. O Docker Compose moderno baseia-se na especificação atual.
Exemplo
Ne pas ajouter version: "3" dans un nouveau compose.yaml.
04 · As confusões frequentes
Convém compreender estas associações antes de modificar um projeto existente.
RUN ≠ CMD
RUN trabalha durante docker build e deixa um resultado na imagem. CMD define o que deve arrancar mais tarde, no docker run.
Exemplo
RUN npm ci
CMD ["node", "server.js"]
CMD ≠ ENTRYPOINT
ENTRYPOINT escolhe o programa principal. CMD pode fornecer o seu comando por omissão ou os seus argumentos; os seus valores são mais facilmente substituídos no lançamento.
Exemplo
ENTRYPOINT ["python"]
CMD ["app.py"]
ARG ≠ ENV
ARG diz respeito à construção; ENV torna um valor disponível na imagem e no contentor. Nenhum dos dois deve servir de cofre de palavras-passe.
Exemplo
ARG VERSION=1.0
ENV MODE=production
EXPOSE ≠ ports
EXPOSE num Dockerfile documenta a porta interna. ports no Compose estabelece o acesso através da porta do anfitrião.
Exemplo
EXPOSE 3000
ports: ["8080:3000"]
image ≠ build
image indica uma referência de imagem; build fornece uma receita para a fabricar. Os dois podem aparecer em conjunto, com regras de transferência e de build que convém conhecer.
Exemplo
image: monapp:dev
build: .
context ≠ WORKDIR
context determina os ficheiros acessíveis ao build a partir do anfitrião; WORKDIR é o diretório atual no interior da imagem e do contentor.
Exemplo
context: .
WORKDIR /app
depends_on ≠ pronto
depends_on garante uma sequência de criação; para aguardar a disponibilidade de uma base de dados, associar um healthcheck e condition: service_healthy.
Exemplo
depends_on:
db:
condition: service_healthy