Docker e Docker Compose — O curso

Guia 03 / 3

Dockerfile e compose.yaml

Compreender cada instrução e as suas consequências no build ou na execução.

Resultado esperado :

Explicar o ciclo Dockerfile → imagem → contentor e configurar serviços Compose.

Leitura
0%

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.

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.

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.

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.

FROM python:3.13-slim
A reter :

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.

RUN pip install --no-cache-dir -r requirements.txt
A reter :

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.

CMD ["python", "app.py"]
A reter :

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.

ENTRYPOINT ["python", "app.py"]
A reter :

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ã.

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.

ADD archive.tar.gz /opt/app/
A reter :

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.

WORKDIR /app

ENV

Define uma variável disponível durante as instruções seguintes e nos contentores baseados na imagem.

ENV APP_MODE=production
A reter :

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.

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.

EXPOSE 3000
A reter :

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.

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.

HEALTHCHECK CMD wget -q -O - http://localhost:3000/health || exit 1
A reter :

O programa utilizado para testar deve estar presente na imagem.

LABEL

Acrescenta metadados em pares chave=valor, úteis para a rastreabilidade.

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.

VOLUME /data

SHELL

Altera o programa interpretador utilizado pelas instruções em forma shell.

SHELL ["/bin/sh", "-c"]

ONBUILD

Regista uma instrução desencadeada quando esta imagem servir posteriormente de imagem de base a outro Dockerfile.

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.

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.

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.

services:
  web:

image

Imagem a utilizar: ou obtida de um registo, ou associada ao resultado do build consoante a configuração.

image: nginx:alpine

build

Indica ao Compose como fabricar uma imagem. Pode ser um caminho curto ou um objeto detalhado.

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.

context: .

dockerfile

Caminho de um ficheiro de construção alternativo, interpretado relativamente ao contexto de build.

dockerfile: docker/Dockerfile

ports

Publica uma porta do contentor no anfitrião. A sintaxe curta «8080:3000» lê-se anfitrião:contentor.

ports:
  - "8080:3000"
A reter :

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.

expose:
  - "3000"

volumes (serviço)

Monta um armazenamento no contentor: um volume com nome ou um caminho do anfitrião.

volumes:
  - db_data:/var/lib/postgresql/data

volumes (raiz)

Declara os volumes com nome geridos pelo projeto, reutilizados pelos serviços.

volumes:
  db_data:

networks

Associa os serviços a uma ou várias redes; os nomes de serviço servem muitas vezes para comunicar.

networks:
  - interne

environment

Variáveis transmitidas ao processo do contentor. Podem modificar as portas, o modo de execução ou comportamentos aplicacionais.

environment:
  NODE_ENV: production
A reter :

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.

env_file:
  - .env.app
A reter :

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.

depends_on:
  db:
    condition: service_healthy

restart

Indica a estratégia de reinício aplicada a um contentor.

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.

healthcheck:
  test: ["CMD", "pg_isready", "-U", "app"]
  interval: 10s

command

Substitui o comando por omissão da imagem no arranque (muitas vezes o CMD).

command: ["node", "server.js"]

entrypoint

Substitui o executável de entrada definido na imagem para um serviço.

entrypoint: ["/app/start.sh"]

profiles

Permite ativar apenas certos serviços opcionais, como ferramentas de depuração.

profiles: ["debug"]

secrets

Declara dados sensíveis e distribui-os a certos serviços sob a forma de ficheiros.

secrets:
  - db_password

build.args

Transmite parâmetros aos ARG do Dockerfile durante a construção.

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.

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.

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.

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.

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.

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.

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.

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.

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.

depends_on:
  db:
    condition: service_healthy