# 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**:

1. **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.
2. **Given** o ambiente rodando, **When** o dev acessa `http://localhost:5173`, **Then** a homepage é renderizada com dados reais do banco.
3. **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.
4. **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**:

1. **Given** Docker Desktop instalado, **When** o dev roda `.\start.ps1`, **Then** o script valida que Docker está rodando e executa o compose.
2. **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
1. `docker-compose up --build` funciona do zero em máquina limpa
2. `http://localhost:5173` carrega homepage com dados reais
3. `http://localhost:5000/api/v1/properties?featured=true` retorna array JSON com imóveis seedados
4. Alteração em `.tsx` reflete no browser sem restart do container
5. `.env` está no `.gitignore`; `.env.example` documenta todas as variáveis necessárias