Pular para conteúdo

Local Development

Guia para configurar e executar o ambiente de desenvolvimento local.

Pré-requisitos

Sistema Operacional

Suportamos desenvolvimento em: - macOS (recomendado) - Linux (Ubuntu 20.04+) - Windows (via WSL2)

Ferramentas Necessárias

  • Git 2.x+
  • Python 3.11+
  • Node.js 20+
  • Docker Desktop
  • PostgreSQL 14+ (ou via Docker)

Setup Backend (Python/FastAPI)

1. Clonar Repositório

git clone git@github.com:seu-org/backend-api.git
cd backend-api

2. Criar Ambiente Virtual

# Criar venv
python -m venv .venv

# Ativar
source .venv/bin/activate  # Linux/Mac
.venv\Scripts\activate     # Windows

3. Instalar Dependências

# Produção
pip install -r requirements.txt

# Desenvolvimento (inclui pytest, black, ruff)
pip install -r requirements-dev.txt

# Pre-commit hooks
pre-commit install

4. Configurar Banco de Dados

# Copiar arquivo de config
cp .env.example .env

# Editar .env
vim .env

Exemplo .env:

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/app_db
DATABASE_URL_TEST=postgresql://user:password@localhost:5432/app_db_test

# AWS (localstack para dev)
AWS_REGION=us-east-1
AWS_ENDPOINT_URL=http://localhost:4566
AWS_ACCESS_KEY_ID=test
AWS_SECRET_ACCESS_KEY=test

# App
DEBUG=True
LOG_LEVEL=DEBUG
SECRET_KEY=dev-secret-key-change-in-production

5. Rodar Migrations

# Aplicar migrations
alembic upgrade head

# Verificar
alembic current

# Seed database
python scripts/seed_database.py

7. Executar Servidor

# Dev server com reload
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# Ou usar script
./scripts/run_dev.sh

Acesse: - API: http://localhost:8000 - Swagger UI: http://localhost:8000/docs - ReDoc: http://localhost:8000/redoc

Setup Frontend (React)

1. Clonar Repositório

git clone git@github.com:seu-org/frontend-web.git
cd frontend-web

2. Instalar Dependências

npm install

3. Configurar Variáveis

# Copiar arquivo de config
cp .env.example .env.local

# Editar .env.local
vim .env.local

Exemplo .env.local:

VITE_API_URL=http://localhost:8000
VITE_APP_ENV=development

4. Executar Dev Server

npm run dev

Acesse: http://localhost:3000

Docker Compose (Recomendado)

Para subir todos os serviços juntos:

# Na raiz do projeto
docker-compose up -d

# Ver logs
docker-compose logs -f

# Parar
docker-compose down

docker-compose.yml:

version: '3.8'

services:
  postgres:
    image: postgres:14
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
      POSTGRES_DB: app_db
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

  localstack:
    image: localstack/localstack
    ports:
      - "4566:4566"
    environment:
      - SERVICES=s3,sqs,sns,lambda
      - DEBUG=1
      - DATA_DIR=/tmp/localstack/data
    volumes:
      - localstack_data:/tmp/localstack

  backend:
    build: ./backend-api
    command: uvicorn app.main:app --reload --host 0.0.0.0
    ports:
      - "8000:8000"
    volumes:
      - ./backend-api:/app
    environment:
      - DATABASE_URL=postgresql://user:password@postgres:5432/app_db
      - AWS_ENDPOINT_URL=http://localstack:4566
    depends_on:
      - postgres
      - localstack

  frontend:
    build: ./frontend-web
    command: npm run dev -- --host
    ports:
      - "3000:3000"
    volumes:
      - ./frontend-web:/app
      - /app/node_modules
    environment:
      - VITE_API_URL=http://localhost:8000

volumes:
  postgres_data:
  localstack_data:

Ferramentas de Desenvolvimento

AWS LocalStack

Para desenvolver com serviços AWS localmente:

# Iniciar LocalStack
docker run -d --name localstack \
  -p 4566:4566 \
  localstack/localstack

# Criar recursos
aws --endpoint-url=http://localhost:4566 \
  s3 mb s3://my-bucket

aws --endpoint-url=http://localhost:4566 \
  sqs create-queue --queue-name my-queue

Makefile

Criar Makefile para comandos comuns:

.PHONY: install test lint format run

install:
    pip install -r requirements-dev.txt
    npm install

test:
    pytest
    npm test

lint:
    ruff check .
    npm run lint

format:
    black .
    npm run format

run:
    docker-compose up -d
    uvicorn app.main:app --reload &
    npm run dev

Uso: 

make install
make test
make run

Debugging

Python (VS Code)

.vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: FastAPI",
      "type": "python",
      "request": "launch",
      "module": "uvicorn",
      "args": [
        "app.main:app",
        "--reload"
      ],
      "jinja": true,
      "justMyCode": false
    }
  ]
}

TypeScript (VS Code)

{
  "name": "Debug React",
  "type": "chrome",
  "request": "launch",
  "url": "http://localhost:3000",
  "webRoot": "${workspaceFolder}/src"
}

Testes

Backend

# Rodar todos os testes
pytest

# Com coverage
pytest --cov --cov-report=html

# Específico
pytest tests/test_users.py

# Com log
pytest -v -s

# Watch mode
pytest-watch

Frontend

# Rodar todos os testes
npm test

# Watch mode
npm test -- --watch

# Coverage
npm test -- --coverage

# Específico
npm test -- UserProfile.test.tsx

Troubleshooting

PostgreSQL não conecta

# Verificar se está rodando
pg_isready -h localhost -p 5432

# Conectar manualmente
psql -h localhost -U user -d app_db

# Reset completo
docker-compose down -v
docker-compose up -d postgres
alembic upgrade head

Port já em uso

# Encontrar processo
lsof -i :8000
# ou
netstat -anp | grep 8000

# Matar processo
kill -9 <PID>

Dependencies conflitantes

# Python: recriar venv
rm -rf .venv
python -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt

# Node: limpar cache
rm -rf node_modules package-lock.json
npm install

Docker problemas

# Limpar tudo
docker-compose down -v
docker system prune -a

# Rebuild
docker-compose build --no-cache
docker-compose up -d

Hot Reloading

Backend

FastAPI com --reload detecta mudanças automaticamente em .py files.

Frontend

Vite detecta mudanças automaticamente. Hot Module Replacement (HMR) funciona out-of-the-box.

Referências