Feature Specification: Docker Setup

Feature Branch: 002-docker-setup Created: 2026-04-13 Status: Approved

User Scenarios & Testing

User Story 1 — Desenvolvedor sobe todo o ambiente com um comando (Priority: P1)

Um desenvolvedor que acabou de clonar o repositório deve conseguir subir PostgreSQL, backend Flask e frontend React rodando juntos com um único comando, sem instalar Python ou Node localmente.

Why this priority: É o bloqueio zero de onboarding. Sem isso, cada dev configura manualmente, gerando ambientes inconsistentes.

Independent Test: Executar docker-compose up --build na raiz e acessar http://localhost:5173 deve exibir a homepage carregando dados do backend.

Acceptance Scenarios:

Given o repositório recém-clonado com Docker instalado, When o dev roda docker-compose up --build, Then os três serviços (db, backend, frontend) sobem sem erro e ficam acessíveis.
Given o ambiente rodando, When o dev acessa http://localhost:5173, Then a homepage é renderizada com dados reais do banco.
Given o ambiente rodando, When o dev acessa http://localhost:5000/api/v1/homepage-config, Then a API retorna JSON 200 com os dados seedados.
Given o ambiente rodando, When o dev faz uma alteração num arquivo .tsx, Then o Vite hot-reload atualiza o browser sem reiniciar o container.

User Story 2 — Script de conveniência na raiz (Priority: P1)

Um desenvolvedor Windows deve poder rodar .\start.ps1 na raiz para ter o ambiente de um clique, sem memorizar comandos Docker.

Why this priority: Reduz fricção para devs Windows que são o público principal.

Independent Test: .\start.ps1 executa docker-compose up --build e exibe mensagens de status claras.

Acceptance Scenarios:

Given Docker Desktop instalado, When o dev roda .\start.ps1, Then o script valida que Docker está rodando e executa o compose.
Given Docker não instalado, When o dev roda .\start.ps1, Then o script exibe mensagem clara pedindo para instalar Docker Desktop.

Edge Cases

O que acontece se a porta 5432/5000/5173 já estiver em uso? → docker-compose retorna erro; o script deve informar.
O que acontece se o banco ainda não estiver pronto quando o backend inicializar? → depends_on com healthcheck; backend deve aguardar ou fazer retry.
Como rodar as migrations no primeiro boot? → Entrypoint do backend executa flask db upgrade antes de python run.py.

Requirements

Functional

FR1: docker-compose up --build na raiz sobe 3 serviços: db (PostgreSQL 16), backend (Flask), frontend (React/Vite)
FR2: Backend aguarda PostgreSQL estar saudável antes de inicializar (healthcheck)
FR3: Backend executa flask db upgrade + seeder automaticamente no primeiro boot
FR4: Frontend tem hot-reload via bind mount do código-fonte
FR5: Variáveis de ambiente devem estar em .env na raiz (não hardcoded no compose)
FR6: .\start.ps1 na raiz é o ponto de entrada único para Windows

Non-Functional

NFR1: docker-compose up --build deve completar em menos de 5 min com cache
NFR2: Imagens devem usar variantes slim/alpine para minimizar tamanho
NFR3: Nenhuma secret hardcoded nas imagens — tudo via env vars
NFR4: .env não deve ser commitado; .env.example deve existir

Design / Architecture

raiz/
├── docker-compose.yml       ← orchestração dos 3 serviços
├── .env.example             ← template de variáveis (db, secret key)
├── .env                     ← valores locais (gitignored)
├── start.ps1                ← script Windows de conveniência
├── backend/
│   └── Dockerfile           ← python:3.12-slim, uv, flask
└── frontend/
    └── Dockerfile           ← node:20-alpine, vite dev server

Serviços docker-compose:

db: postgres:16-alpine, volume persistente, healthcheck
backend: build ./backend, porta 5000, DATABASE_URL apontando para db
frontend: build ./frontend, porta 5173, bind mount src/ para hot-reload, proxy vite → backend

Out of Scope

Build de produção (multi-stage, nginx servindo static) — feature futura
CI/CD pipeline
Deploy em cloud
HTTPS/TLS local

Success Criteria

docker-compose up --build funciona do zero em máquina limpa
http://localhost:5173 carrega homepage com dados reais
http://localhost:5000/api/v1/properties?featured=true retorna array JSON com imóveis seedados
Alteração em .tsx reflete no browser sem restart do container
.env está no .gitignore; .env.example documenta todas as variáveis necessárias

4.6 KiB Raw Blame History