Docker Compose, Dockerfile multi-stage, volumes, Traefik com SSL e monitoramento.
O que é: O docker-compose.yml orquestra dois serviços: app (MiroFish) e traefik (proxy reverso com SSL). Define volumes, redes, portas e variáveis de ambiente.
Por que aprender: Entender o compose file permite customizar portas, domínios, volumes e adicionar serviços extras (como monitoramento).
# docker-compose.yml (simplificado)
version: '3.8'
services:
app:
build: .
ports:
- "5001:5001"
volumes:
- ./backend/uploads:/app/backend/uploads
- ./backend/data:/app/backend/data
- ~/.claude:/root/.claude
- ~/.local/share/claude:/root/.local/share/claude
env_file: .env
restart: unless-stopped
traefik:
image: traefik:v3.0
ports:
- "80:80"
- "443:443"
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- ./acme.json:/acme.json
O que é: O Dockerfile usa build multi-stage para criar uma imagem otimizada. Stage 1 (node:20-bookworm-slim) compila o frontend. Stage 2 (python:3.11-slim) configura o backend.
Por que aprender: Multi-stage build mantém a imagem final menor (só inclui artefatos necessários). Entender as stages ajuda a debugar falhas de build.
# Dockerfile (estrutura)
# Stage 1: Build do Frontend
FROM node:20-bookworm-slim AS frontend-build
WORKDIR /app/frontend
COPY frontend/package*.json ./
RUN npm ci
COPY frontend/ ./
RUN npm run build
# Stage 2: Runtime (Python + Node)
FROM python:3.11-slim
RUN apt-get update && apt-get install -y nodejs npm
WORKDIR /app
COPY --from=frontend-build /app/frontend/dist ./frontend/dist
COPY backend/ ./backend/
RUN pip install uv && cd backend && uv sync
EXPOSE 5001
CMD ["python", "backend/app.py"]
O que é: Volumes Docker mapeiam diretórios do host para dentro do container, garantindo persistência de dados e acesso a credenciais do Claude CLI.
Por que aprender: Sem os volumes corretos: dados são perdidos ao recriar containers, Claude CLI não autentica, e uploads desaparecem.
# Volumes essenciais no docker-compose.yml
volumes:
# Documentos enviados pelo usuário
- ./backend/uploads:/app/backend/uploads
# Banco KuzuDB e dados de simulação
- ./backend/data:/app/backend/data
# Credenciais do Claude CLI (ESSENCIAL!)
- ~/.claude:/root/.claude
- ~/.local/share/claude:/root/.local/share/claude
# Credenciais do Codex CLI (se usar)
- ~/.codex:/root/.codex
# Sem esses volumes, o Claude CLI dentro do Docker
# não consegue autenticar e retorna erro de login.
O que é: Traefik é um proxy reverso moderno que obtém certificados SSL automaticamente via Let's Encrypt. Configurado via labels no docker-compose.yml.
Por que aprender: HTTPS é obrigatório para produção. Traefik automatiza tudo: emissão, renovação de certificados e roteamento de tráfego.
# Labels Traefik no serviço app
labels:
- "traefik.enable=true"
- "traefik.http.routers.mirofish.rule=Host(`synth.scty.org`)"
- "traefik.http.routers.mirofish.tls=true"
- "traefik.http.routers.mirofish.tls.certresolver=letsencrypt"
- "traefik.http.services.mirofish.loadbalancer.server.port=5001"
# Configuração do Traefik
command:
- "--providers.docker=true"
- "--entrypoints.websecure.address=:443"
- "--certificatesresolvers.letsencrypt.acme.email=seu@email.com"
- "--certificatesresolvers.letsencrypt.acme.storage=/acme.json"
- "--certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=web"
# Pré-requisito: criar acme.json
touch acme.json && chmod 600 acme.json
O que é: O comando docker compose up -d --build constrói a imagem Docker e sobe todos os serviços em background. O primeiro build leva 5-10 minutos.
Por que aprender: Este é o comando que coloca o MiroFish em produção. Entender os flags evita problemas comuns de deploy.
# Subir tudo (primeira vez - vai demorar)
docker compose up -d --build
# Flags explicados:
-d → Detached (roda em background)
--build → Rebuild a imagem (necessário após mudanças)
# Comandos úteis após subir:
docker compose ps # Ver status dos serviços
docker compose stop # Parar sem destruir
docker compose down # Parar e remover containers
docker compose restart app # Reiniciar só o app
# Verificar se está rodando:
curl http://localhost:5001/health # Deve retornar OK
O que é: Docker Compose oferece ferramentas de log e monitoramento integradas. Use docker compose logs para ver saída dos containers em tempo real.
Por que aprender: Logs são a ferramenta #1 de diagnóstico. Erros de API, falhas de memória e problemas de configuração aparecem aqui.
# Ver logs em tempo real (todos os serviços)
docker compose logs -f
# Ver logs só do app
docker compose logs -f app
# Ver últimas 100 linhas
docker compose logs --tail=100 app
# Verificar uso de recursos
docker stats # CPU, RAM, I/O em tempo real
# Entrar no container para debug
docker compose exec app bash
docker compose exec app python --version
docker compose exec app claude --version