Docker e Compose

Empacote uma aplicação em imagem, rode e investigue containers e suba aplicação e banco juntos com Docker Compose.

Cerca de 16 min · Revisado em

Ao final, você vai conseguir

  • Explicar a diferença entre imagem e container e o problema que os containers resolvem
  • Escrever um Dockerfile em camadas que aproveita o cache
  • Rodar e investigar containers com portas, variáveis de ambiente, docker logs e docker exec
  • Descrever aplicação e banco num compose.yaml com volume para que os dados sobrevivam à recriação
  • Evitar segredos na imagem, a tag latest e containers rodando como root

“Na minha máquina funciona” é provavelmente a frase mais repetida da história da programação. A API roda no seu notebook, mas quebra no servidor porque lá a versão do Python é outra, falta uma biblioteca ou o banco está configurado diferente. Containers resolvem isso empacotando o programa junto com tudo de que ele precisa. Hoje, quase toda vaga de backend, DevOps ou engenharia de dados espera que você saiba subir um projeto com Docker.

O problema do “na minha máquina funciona”

Pense numa API de pedidos escrita em Python. Para rodar, ela precisa do Python 3.12, de cinco bibliotecas em versões específicas, de uma variável com o endereço do banco e de um PostgreSQL 16. No seu notebook está tudo instalado. No notebook da colega, o Python é 3.9. No servidor, o PostgreSQL é 13.

O Docker é a ferramenta mais popular para criar e rodar containers. Um container não é um computador inteiro simulado, como uma máquina virtual: ele compartilha o núcleo do sistema da máquina e isola só o necessário. Por isso liga em segundos e ocupa pouco espaço.

A API funciona no seu notebook e falha no servidor com ModuleNotFoundError: No module named 'fastapi'. Como um container ajudaria?

  • A biblioteca iria dentro do pacote do container, então o servidor não precisaria tê-la instalada
  • O Docker instala automaticamente no servidor tudo o que existe no seu notebook
  • Não ajudaria: erros de biblioteca só se resolvem instalando à mão no servidor

Imagem e container: a receita e o bolo

Imagem
Um pacote somente leitura com sistema básico, linguagem, bibliotecas e o código. Tem nome e tag (versão), como postgres:16 ou api-pedidos:1.0.
Container
Uma imagem em execução. Ganha uma camada própria onde pode escrever, mas essa camada some quando o container é removido.
Registro
Um depósito de imagens na internet. O mais conhecido é o Docker Hub, de onde vêm imagens oficiais como nginx, python e postgres.

Seu primeiro container

Rode um servidor web nginx num container, sem instalar o nginx no computador.

  1. Rode a imagem nginx:1.27 em segundo plano (-d), com o nome web, ligando a porta 8080 do seu computador à porta 80 do container.

    docker run -d --name web -p 8080:80 nginx:1.27
    Unable to find image 'nginx:1.27' locally
    1.27: Pulling from library/nginx
    a2318d6c47ec: Pull complete
    095d327c79ae: Pull complete
    Status: Downloaded newer image for nginx:1.27
    3f9c2a7e81d40b6f5c1e9a2d7b8e4f60a1c3d5e7f9b2a4c6d8e0f1a3b5c7d9e2
  2. Liste os containers em execução.

    docker ps
    CONTAINER ID   IMAGE        COMMAND                  STATUS         PORTS                  NAMES
    3f9c2a7e81d4   nginx:1.27   "/docker-entrypoint.…"   Up 8 seconds   0.0.0.0:8080->80/tcp   web
  3. Acesse o servidor pela porta do seu computador e veja só os cabeçalhos da resposta.

    curl -I localhost:8080
    HTTP/1.1 200 OK
    Server: nginx/1.27.2
    Content-Type: text/html
    Content-Length: 615
  4. Pare e remova o container de uma vez, com rm -f.

    docker rm -f web
    web
  5. Liste as imagens guardadas no seu computador.

    docker images
    REPOSITORY   TAG       IMAGE ID       CREATED       SIZE
    nginx        1.27      9bea9f2796e2   2 weeks ago   192MB

Repare no final: o container foi apagado, mas a imagem continua lá. Na próxima vez, o docker run não precisa baixar nada e liga em menos de um segundo. O bolo foi embora, a receita ficou.

Cada frase descreve a imagem ou o container?

Imagem (a receita) · Container (o bolo)

  • Fica guardada e não muda depois de criada
  • Tem nome e tag, como postgres:16
  • É construída a partir de um Dockerfile
  • Aparece no docker ps com status Up
  • Perde os arquivos escritos quando é removido
  • Pode existir em várias cópias ao mesmo tempo, vindas da mesma origem

O Dockerfile: escrevendo a receita

Para empacotar a sua aplicação, você escreve um Dockerfile: um arquivo de texto, chamado exatamente assim, sem extensão, com as instruções para montar a imagem. Cada instrução vira uma camada, como as camadas de um bolo.

O Dockerfile da API de pedidos

FROM python:3.12-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

USER 1000
EXPOSE 8000
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
  • FROM: A imagem de partida. Aqui, um Linux enxuto com Python 3.12 já instalado. Fixar a versão evita surpresas quando sair uma nova.
  • WORKDIR: Cria e entra na pasta /app dentro da imagem. Os comandos seguintes acontecem nela, como um cd.
  • COPY das dependências: Copia só a lista de bibliotecas do seu computador para a imagem. Vem antes do resto do código de propósito, por causa do cache.
  • RUN: Executa um comando durante a construção da imagem. Instalar bibliotecas é a etapa mais lenta, e o resultado fica guardado numa camada.
  • COPY do código: Copia o resto do projeto. Como o código muda o tempo todo, essa camada é refeita quase sempre, mas é rápida.
  • USER: Daqui em diante, tudo roda como uma conta comum, não como root. Se alguém invadir a aplicação, encontra menos poder nas mãos.
  • EXPOSE: Documenta em que porta a aplicação escuta dentro do container. Não abre nada sozinho: quem liga a porta ao computador é o -p do docker run.
  • CMD: O comando que roda quando um container nasce dessa imagem. O 0.0.0.0 é essencial: como você viu na aula de redes, ouvir só em 127.0.0.1 deixaria a API inacessível de fora do container.
Por que copiar o requirements.txt e instalar as bibliotecas antes de copiar o resto do código?

Por causa do cache de camadas. O Docker reaproveita uma camada se nada mudou nela nem antes dela. Você muda o código dez vezes por dia, mas a lista de bibliotecas quase nunca. Com essa ordem, a instalação lenta fica no cache e cada nova construção leva segundos. Com COPY . . antes do pip install, qualquer vírgula alterada reinstalaria tudo.

Construindo a imagem e vendo o cache

Construa a imagem da API, altere uma linha do código e construa de novo.

  1. Construa a imagem a partir do Dockerfile desta pasta (o ponto final), com o nome e a tag api-pedidos:1.0.

    docker build -t api-pedidos:1.0 .
    [+] Building 21.6s (10/10) FINISHED
     => [internal] load build definition from Dockerfile        0.0s
     => [1/5] FROM docker.io/library/python:3.12-slim            6.3s
     => [2/5] WORKDIR /app                                       0.1s
     => [3/5] COPY requirements.txt .                            0.0s
     => [4/5] RUN pip install --no-cache-dir -r requirements.txt 13.9s
     => [5/5] COPY . .                                           0.1s
     => exporting to image                                       1.1s
     => => naming to docker.io/library/api-pedidos:1.0           0.0s
  2. Você corrigiu um texto em main.py. Construa de novo, agora com a tag 1.1.

    docker build -t api-pedidos:1.1 .
    [+] Building 1.4s (10/10) FINISHED
     => [internal] load build definition from Dockerfile        0.0s
     => [1/5] FROM docker.io/library/python:3.12-slim            0.0s
     => CACHED [2/5] WORKDIR /app                                0.0s
     => CACHED [3/5] COPY requirements.txt .                     0.0s
     => CACHED [4/5] RUN pip install --no-cache-dir -r requirements.txt 0.0s
     => [5/5] COPY . .                                           0.1s
     => exporting to image                                       0.6s
     => => naming to docker.io/library/api-pedidos:1.1           0.0s

De 21,6 segundos para 1,4. As linhas com CACHED foram reaproveitadas, e só a cópia do código foi refeita. Em projetos grandes, essa diferença é de minutos a cada construção.

Coloque as instruções de um Dockerfile na ordem que aproveita melhor o cache.

  • FROM python:3.12-slim
  • WORKDIR /app
  • COPY requirements.txt .
  • RUN pip install -r requirements.txt
  • COPY . .
  • CMD ["python", "main.py"]

Portas, variáveis, logs e volumes

Um container é isolado: tem rede, pastas e processos próprios. Para usá-lo de verdade, você abre portas de propósito com -p, passa configurações com -e e, quando algo falha, olha os logs e entra nele para investigar.

-p 8080:8000
Liga a porta 8080 do seu computador à porta 8000 do container. A ordem é sempre computador:container.
-e NOME=valor
Cria uma variável de ambiente dentro do container. É assim que a mesma imagem recebe o endereço do banco de teste ou de produção.
docker logs nome
Mostra tudo o que a aplicação escreveu na tela. Com -f, acompanha ao vivo, como o tail -f.
docker exec -it nome sh
Abre um terminal dentro do container em execução, para olhar arquivos e variáveis por dentro.

A API que liga e cai

Rode a imagem da API e descubra por que ela não fica de pé.

  1. Rode api-pedidos:1.1 em segundo plano com o nome api, ligando a porta 8000 do computador à 8000 do container.

    docker run -d --name api -p 8000:8000 api-pedidos:1.1
    b71e04c9d3a25f8e6b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a
  2. Liste todos os containers, inclusive os que pararam (-a).

    docker ps -a
    CONTAINER ID   IMAGE             COMMAND                  STATUS                     NAMES
    b71e04c9d3a2   api-pedidos:1.1   "uvicorn main:app --…"   Exited (1) 4 seconds ago   api
  3. O container saiu com código 1. Leia os logs dele.

    docker logs api
    INFO:     Started server process [1]
    INFO:     Waiting for application startup.
    ERROR:    Traceback (most recent call last):
      File "/app/main.py", line 9, in <module>
        DATABASE_URL = os.environ["DATABASE_URL"]
    KeyError: 'DATABASE_URL'
    ERROR:    Application startup failed. Exiting.
  4. Faltou a variável DATABASE_URL. Remova o container quebrado.

    docker rm api
    api
  5. Rode de novo passando -e DATABASE_URL=postgresql://loja:segredo@db:5432/loja.

    docker run -d --name api -p 8000:8000 -e DATABASE_URL=postgresql://loja:segredo@db:5432/loja api-pedidos:1.1
    5c2d8e1f0a9b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a1b0c9d
  6. Entre no container e confira a variável por dentro.

    docker exec api env | grep DATABASE
    DATABASE_URL=postgresql://loja:segredo@db:5432/loja

A variável chegou e a API ligou. Mas o nome db no endereço ainda não existe, e o primeiro pedido vai falhar: falta um banco de dados para a API conversar. Para investigar por dentro com calma, docker exec -it api sh abre um terminal no container (saia com exit). O banco entra com o Compose, na próxima seção. Antes, um ponto crucial sobre dados.

Você roda docker run -d -p 3000:8000 api-pedidos:1.1. Qual endereço abre a API no navegador do seu computador?

  • http://localhost:3000
  • http://localhost:8000
  • http://localhost:3000:8000

Docker Compose: a aplicação inteira num arquivo

Uma aplicação real tem várias peças: a API, o banco, às vezes um cache ou um job de dados. Subir cada uma com um docker run enorme é fácil de errar. O Docker Compose descreve todas as peças num arquivo YAML, compose.yaml, e sobe tudo com um comando. Ele também cria uma rede onde cada serviço encontra o outro pelo nome.

compose.yaml com a API e um PostgreSQL

services:
  api:
    build: .
    ports:
      - "8000:8000"
    environment:
      DATABASE_URL: postgresql://loja:${DB_SENHA}@db:5432/loja
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16
    environment:
      POSTGRES_USER: loja
      POSTGRES_PASSWORD: ${DB_SENHA}
      POSTGRES_DB: loja
    volumes:
      - dados-pg:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "loja"]
      interval: 5s
      retries: 5

volumes:
  dados-pg:
  • services: A lista das peças da aplicação. Cada nome logo abaixo vira um serviço e também um nome na rede interna.
  • build: O serviço api é construído a partir do Dockerfile desta pasta, igual ao docker build.
  • ports: O mesmo -p do docker run: computador à esquerda, container à direita.
  • environment: Variáveis de ambiente. Repare no db: é o nome do outro serviço. Dentro da rede do Compose, ele funciona como um endereço. A senha vem de ${DB_SENHA}, lida de um arquivo .env que não vai para o Git.
  • depends_on: Só liga a API depois que o banco estiver saudável, conforme o health check dele. Sem isso, a API pode tentar conectar antes de o banco aceitar conexões.
  • image: O banco usa a imagem oficial pronta, com versão fixa. Não há nada para construir.
  • volumes: Liga o volume dados-pg à pasta onde o PostgreSQL guarda os dados. Recriar o container não apaga os pedidos.
  • healthcheck: Um teste que o Docker roda de tempos em tempos para saber se o serviço está pronto de verdade, não só ligado.
  • Declaração do volume: Os volumes nomeados precisam ser declarados no fim do arquivo.

Subindo, investigando e recriando

Suba a aplicação, confira os serviços, leia os logs e prove que os dados sobrevivem à recriação.

  1. Suba todos os serviços em segundo plano.

    docker compose up -d
    [+] Running 4/4
     ✔ Network api-pedidos_default     Created   0.1s
     ✔ Volume "api-pedidos_dados-pg"   Created   0.0s
     ✔ Container api-pedidos-db-1      Healthy   6.2s
     ✔ Container api-pedidos-api-1     Started   6.4s
  2. Veja o estado dos serviços.

    docker compose ps
    NAME                IMAGE             SERVICE   STATUS                    PORTS
    api-pedidos-api-1   api-pedidos-api   api       Up 12 seconds             0.0.0.0:8000->8000/tcp
    api-pedidos-db-1    postgres:16       db        Up 18 seconds (healthy)   5432/tcp
  3. Leia os logs só do serviço api.

    docker compose logs api
    api-1  | INFO:     Started server process [1]
    api-1  | INFO:     Conectado ao banco em db:5432
    api-1  | INFO:     Uvicorn running on http://0.0.0.0:8000
  4. Crie um pedido de teste pela API, com um POST.

    curl -X POST localhost:8000/pedidos -d '{"item":"pao de queijo","qtd":6}'
    {"id":1,"item":"pao de queijo","qtd":6}
  5. Derrube tudo: containers e rede. Sem -v, os volumes ficam.

    docker compose down
    [+] Running 3/3
     ✔ Container api-pedidos-api-1   Removed   0.4s
     ✔ Container api-pedidos-db-1    Removed   0.3s
     ✔ Network api-pedidos_default   Removed   0.1s
  6. Suba tudo de novo e confira se o pedido sobreviveu.

    docker compose up -d && curl localhost:8000/pedidos
    [+] Running 3/3
     ✔ Network api-pedidos_default   Created   0.1s
     ✔ Container api-pedidos-db-1    Healthy   5.8s
     ✔ Container api-pedidos-api-1   Started   6.0s
    [{"id":1,"item":"pao de queijo","qtd":6}]

Dentro do container da API, a configuração do banco está como localhost:5432 e a conexão falha. O banco está de pé no serviço db. O que corrigir?

  • Trocar localhost por db, o nome do serviço no Compose
  • Publicar a porta 5432 do banco com ports
  • Rodar a API como root

Os erros que todo mundo comete no começo

Segredo na imagem

Senhas no Dockerfile ou copiadas com o código

Qualquer pessoa com acesso à imagem consegue extrair o que está dentro dela, mesmo de camadas antigas. Passe segredos por variáveis de ambiente na hora de rodar e coloque .env no .dockerignore e no .gitignore.

Tag latest

Usar latest ou nenhuma tag

latest não quer dizer “estável”, só “a mais recente que alguém publicou”. Hoje é a 16, amanhã é a 17 e seu banco não sobe. Fixe versões, como postgres:16.

Root

Rodar a aplicação como root

Por padrão, o processo dentro do container é root. Se a aplicação for invadida, o atacante começa com poder máximo. Use USER no Dockerfile com uma conta comum.

Boa prática ou risco?

Boa prática · Risco

  • FROM python:3.12-slim
  • FROM python:latest
  • ENV DB_SENHA=minhasenha123 no Dockerfile
  • Senha passada com -e ou num .env fora do Git
  • USER 1000 antes do CMD
  • Banco sem volume, “porque é só um teste”
  • .dockerignore com .env e .git

Fechamento

  • Containers acabam com o “na minha máquina funciona” ao empacotar a aplicação com tudo de que ela precisa.
  • A imagem é a receita, guardada e imutável; o container é o bolo, criado, executado e descartável.
  • O Dockerfile monta a imagem em camadas: FROM, WORKDIR, COPY, RUN e CMD, das que mudam menos para as que mudam mais, para aproveitar o cache.
  • -p computador:container abre portas, -e passa configurações, docker logs e docker exec investigam e volumes guardam dados além da vida do container.
  • O Compose descreve a aplicação inteira num compose.yaml, onde os serviços se encontram pelo nome; evite segredos na imagem, a tag latest e rodar como root.

Recrie seu ambiente a partir dos arquivos

A prática pedida nas trilhas de DevOps, Backend e Engenharia de Dados é a mesma no fundo: subir aplicação e banco com Compose, investigar uma falha pelos logs e provar que os dados sobrevivem. Use uma API sua, a de um tutorial ou um script de dados simples.

  1. Escreva um Dockerfile para a aplicação com versão fixa no FROM, dependências antes do código e USER sem root
  2. Crie um compose.yaml com a aplicação e um postgres:16 com volume e health check, e a senha vinda de um .env fora do Git
  3. Suba com docker compose up -d, provoque uma falha (como apagar uma variável de ambiente) e encontre a causa com docker compose logs
  4. Grave um dado, rode docker compose down e up -d de novo e confirme que ele continua lá
  5. Clone o repositório numa pasta nova e suba tudo só com os arquivos versionados, anotando no README os comandos usados

Referências

Cursos relacionados