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:16ouapi-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,pythonepostgres.
Seu primeiro container
Rode um servidor web nginx num container, sem instalar o nginx no computador.
Rode a imagem
nginx:1.27em segundo plano (-d), com o nomeweb, ligando a porta 8080 do seu computador à porta 80 do container.docker run -d --name web -p 8080:80 nginx:1.27Unable 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 3f9c2a7e81d40b6f5c1e9a2d7b8e4f60a1c3d5e7f9b2a4c6d8e0f1a3b5c7d9e2Liste os containers em execução.
docker psCONTAINER ID IMAGE COMMAND STATUS PORTS NAMES 3f9c2a7e81d4 nginx:1.27 "/docker-entrypoint.…" Up 8 seconds 0.0.0.0:8080->80/tcp webAcesse o servidor pela porta do seu computador e veja só os cabeçalhos da resposta.
curl -I localhost:8080HTTP/1.1 200 OK Server: nginx/1.27.2 Content-Type: text/html Content-Length: 615Pare e remova o container de uma vez, com
rm -f.docker rm -f webwebListe as imagens guardadas no seu computador.
docker imagesREPOSITORY 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 pscom statusUp - 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
/appdentro da imagem. Os comandos seguintes acontecem nela, como umcd. - 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
-pdodocker 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ó em127.0.0.1deixaria 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.
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.0sVocê corrigiu um texto em
main.py. Construa de novo, agora com a tag1.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-slimWORKDIR /appCOPY requirements.txt .RUN pip install -r requirements.txtCOPY . .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
8080do seu computador à porta8000do 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 otail -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é.
Rode
api-pedidos:1.1em segundo plano com o nomeapi, ligando a porta 8000 do computador à 8000 do container.docker run -d --name api -p 8000:8000 api-pedidos:1.1b71e04c9d3a25f8e6b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2aListe todos os containers, inclusive os que pararam (
-a).docker ps -aCONTAINER ID IMAGE COMMAND STATUS NAMES b71e04c9d3a2 api-pedidos:1.1 "uvicorn main:app --…" Exited (1) 4 seconds ago apiO container saiu com código 1. Leia os logs dele.
docker logs apiINFO: 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.Faltou a variável
DATABASE_URL. Remova o container quebrado.docker rm apiapiRode 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.15c2d8e1f0a9b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a1b0c9dEntre no container e confira a variável por dentro.
docker exec api env | grep DATABASEDATABASE_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:3000http://localhost:8000http://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 aodocker build. - ports: O mesmo
-pdodocker 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.envque 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.
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.4sVeja o estado dos serviços.
docker compose psNAME 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/tcpLeia os logs só do serviço
api.docker compose logs apiapi-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:8000Crie 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}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.1sSuba 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
localhostpordb, o nome do serviço no Compose - Publicar a porta
5432do banco comports - 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-slimFROM python:latestENV DB_SENHA=minhasenha123no Dockerfile- Senha passada com
-eou num.envfora do Git USER 1000antes doCMD- Banco sem volume, “porque é só um teste”
.dockerignorecom.enve.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,RUNeCMD, das que mudam menos para as que mudam mais, para aproveitar o cache. -p computador:containerabre portas,-epassa configurações,docker logsedocker execinvestigam 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 taglateste 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.
- Escreva um Dockerfile para a aplicação com versão fixa no
FROM, dependências antes do código eUSERsem root - Crie um
compose.yamlcom a aplicação e umpostgres:16com volume e health check, e a senha vinda de um.envfora do Git - Suba com
docker compose up -d, provoque uma falha (como apagar uma variável de ambiente) e encontre a causa comdocker compose logs - Grave um dado, rode
docker compose downeup -dde novo e confirme que ele continua lá - Clone o repositório numa pasta nova e suba tudo só com os arquivos versionados, anotando no README os comandos usados