sass-imobiliaria/.specify/features/002-docker-setup/plan.md

Implementation Plan: Docker Setup

Branch: 002-docker-setup Spec: .specify/features/002-docker-setup/spec.md Created: 2026-04-13

Constitution Check

• ✅ Design-First: não se aplica (infra)
• ✅ Separation of Concerns: Flask e React permanecem desacoplados, Docker apenas orquestra
• ✅ Spec-Driven: este plano deriva da spec aprovada
• ✅ Security: nenhuma secret hardcoded; .env no gitignore
• ✅ Simplicity: sem multi-stage build, sem nginx — foco em dev environment

---

Phase 1 — Backend Dockerfile

Objetivo: Containerizar o Flask app usando python:3.12-slim e uv.

Arquivos:

• backend/Dockerfile

Detalhes:

• Base: python:3.12-slim
• Instalar uv via pip
• Copiar pyproject.toml → uv sync → copiar código
• Entrypoint: script shell que executa flask db upgrade && python seeds/seed.py && python run.py
• Porta exposta: 5000

Critério de conclusão: docker build -t backend ./backend conclui sem erro.

---

Phase 2 — Frontend Dockerfile

Objetivo: Containerizar o servidor de desenvolvimento Vite com hot-reload.

Arquivos:

• frontend/Dockerfile

Detalhes:

• Base: node:20-alpine
• Copiar package*.json → npm ci → copiar código
• CMD: npm run dev -- --host 0.0.0.0 (necessário para expor dentro do container)
• Porta exposta: 5173
• O vite.config.ts já tem proxy /api → http://localhost:5000; atualizar para http://backend:5000 (nome do serviço Docker)

Critério de conclusão: docker build -t frontend ./frontend conclui sem erro.

---

Phase 3 — docker-compose.yml

Objetivo: Orquestrar db + backend + frontend com dependências e healthchecks.

Arquivos:

• docker-compose.yml (raiz)
• .env.example (atualizar/criar na raiz)

Serviços:

db:
  image: postgres:16-alpine
  healthcheck: pg_isready -U ${POSTGRES_USER}
  depends_on: (nenhum)

backend:
  build: ./backend
  depends_on:
    db: { condition: service_healthy }
  environment:
    DATABASE_URL: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB}

frontend:
  build: ./frontend
  depends_on: [backend]
  volumes:
    - ./frontend/src:/app/src        ← hot-reload
    - ./frontend/public:/app/public

Critério de conclusão: docker-compose config valida sem erro; docker-compose up sobe os 3 serviços.

---

Phase 4 — start.ps1

Objetivo: Script PowerShell de conveniência na raiz.

Arquivos:

• start.ps1 (raiz)

Lógica:

1. Verificar se docker está disponível no PATH
2. Se não: exibir mensagem com link para Docker Desktop e sair
3. Se sim: executar docker-compose up --build

Critério de conclusão: .\start.ps1 inicia o ambiente ou exibe erro informativo.

---

Sequência de execução

Phase 1 (backend/Dockerfile)
  ↓
Phase 2 (frontend/Dockerfile + vite.config proxy update)
  ↓
Phase 3 (docker-compose.yml + .env.example)
  ↓
Phase 4 (start.ps1)
  ↓
Validação: docker-compose up --build → testar endpoints