Docker: imagem, container e Compose

Os conceitos que mais confundem no começo, um Dockerfile comentado e os comandos do dia a dia.

8 min de leitura · Iniciante · Revisado em

Os conceitos que mais confundem

Docker empacota uma aplicação com tudo o que ela precisa para rodar: sistema base, bibliotecas e configuração. Assim, ela roda igual no seu computador, na CI e no servidor.

Imagem
Um pacote somente leitura com o sistema de arquivos e o comando de início. Como uma receita pronta, ou uma classe.
Container
Um processo em execução, isolado, criado a partir de uma imagem. Como uma instância da classe. Pode haver vários da mesma imagem.
Dockerfile
O arquivo de texto com os passos para construir uma imagem.
Registro
Onde as imagens são publicadas e baixadas, como Docker Hub ou GitHub Container Registry.
Volume
Uma pasta que sobrevive ao container. Sem volume, os dados somem quando o container é removido.
Compose
Um arquivo YAML que descreve vários containers que trabalham juntos.

Um Dockerfile comentado

API em Node.js

# Imagem base pequena, com versão fixa
FROM node:22-alpine

WORKDIR /app

# Copie só os manifestos primeiro: a instalação fica em cache
COPY package.json package-lock.json ./
RUN npm ci --omit=dev

# Depois, o código
COPY . .

# Não rode como root
USER node

EXPOSE 3000
CMD ["node", "server.js"]

.dockerignore: o que não deve ir para a imagem

node_modules
.git
.env
coverage

Comandos do dia a dia

O ciclo de vida de uma imagem e de um container
ComandoO que faz
docker build -t api:dev .Constrói a imagem a partir do Dockerfile da pasta atual.
docker run --rm -p 3000:3000 api:devCria e inicia um container. -p porta-da-máquina:porta-do-container.
docker psLista os containers em execução. Com -a, inclui os parados.
docker logs -f <container>Acompanha a saída do processo.
docker exec -it <container> shAbre um terminal dentro do container.
docker stop <container>Para o container.
docker compose up -dSobe todos os serviços do compose.yaml em segundo plano.
docker compose downPara e remove os containers. Os volumes nomeados continuam.

API e banco com Compose

compose.yaml

services:
  api:
    build: .
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgres://app:app@db:5432/app
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: app
      POSTGRES_DB: app
    volumes:
      - dados:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app"]
      interval: 5s
      retries: 5

volumes:
  dados:
  • Dentro da rede do Compose, cada serviço é encontrado pelo nome. Por isso a API acessa o banco em db:5432.
  • depends_on com service_healthy espera o banco aceitar conexões antes de iniciar a API.
  • O volume dados guarda o banco entre reinicializações.

Problemas comuns

Roda, mas o navegador não abre

A aplicação provavelmente escuta em 127.0.0.1. Dentro do container, ela precisa escutar em 0.0.0.0, e a porta precisa estar publicada com -p.

Os dados do banco sumiram

Faltou um volume. Sem ele, remover o container apaga tudo o que estava dentro.

O build demora sempre

Uma instrução que muda com frequência está antes da instalação de dependências e invalida o cache.

A imagem tem 1 GB

Use imagens base alpine ou slim, um .dockerignore e builds em múltiplos estágios.

Referências

Trilhas relacionadas