Saltar a contenido

Run Backend And Database Locally

Este runbook levanta PostgreSQL de infra, crea o valida finances_db, aplica migraciones y arranca el backend FastAPI.

1. Preparar Infra

Desde la raíz del monorepo:

cd infra
cp .env.example .env

Edita infra/.env y define valores locales para:

  • POSTGRES_USER
  • POSTGRES_PASSWORD
  • POSTGRES_PORT
  • FINANCES_DB_USER
  • FINANCES_DB_PASSWORD

No subas ese .env a Git.

2. Levantar PostgreSQL

docker network inspect timeliber-net >/dev/null 2>&1 || docker network create timeliber-net
docker compose up -d postgres

Verifica salud:

docker compose ps postgres

Si el volumen de Postgres es nuevo, infra/postgres/init/04_finances.sh crea:

  • Role: valor de FINANCES_DB_USER.
  • DB: finances_db.

3. Si El Volumen Ya Existía

Los scripts en infra/postgres/init/ solo se ejecutan al inicializar un volumen nuevo. En un volumen existente, entra a psql y crea la DB manualmente con los valores de tu .env local:

docker compose exec postgres sh -c 'psql -U "$POSTGRES_USER" -d "${POSTGRES_DB:-timeliber}"'

SQL:

CREATE ROLE finances_user WITH LOGIN PASSWORD '<local-password>';
CREATE DATABASE finances_db OWNER finances_user;

Si el role o la DB ya existen, no los recrees. Valida con:

\du finances_user
\l finances_db

4. Configurar Backend

cd ../apps/finances/backend
cp .env.example .env

Edita apps/finances/backend/.env:

  • FINANCES_DATABASE_URL debe apuntar a finances_db.
  • FINANCES_JWT_SECRET debe ser un secreto local fuerte.
  • FINANCES_PUBLIC_URL debe apuntar al frontend local cuando exista.
  • FINANCES_EMAIL_FROM debe tener un remitente local o transaccional válido.
  • RESEND_API_KEY puede quedar vacío fuera de producción.
  • FINANCES_EXPOSE_INVITATION_TOKEN=true solo para local/tests.

Ejemplo de secreto local:

openssl rand -hex 32

5. Instalar Dependencias Y Migrar

uv sync
uv run alembic upgrade head
uv run alembic current

El revision esperado actualmente es:

20260610_0013 (head)

6. Arrancar API

uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8010

URLs locales:

  • Healthcheck: http://localhost:8010/health
  • Swagger: http://localhost:8010/docs
  • OpenAPI runtime: http://localhost:8010/openapi.json

En producción, FINANCES_ENVIRONMENT=production desactiva /docs y /openapi.json.

7. Smoke Test Manual

curl -sS http://localhost:8010/health

Flujo funcional:

  1. POST /api/v1/auth/register
  2. POST /api/v1/auth/login
  3. Usar Authorization: Bearer <access_token>
  4. GET /api/v1/auth/me
  5. Crear cuenta, categoría, transacción y consultar dashboard.

Los detalles exactos de endpoints viven en la referencia generada: ../../backend/docs/03_REFERENCE/endpoints.md.

No existe usuario fijo de prueba por seguridad. Para probar localmente, registra un perfil desde el frontend o llama POST /api/v1/auth/register; luego ingresa con el mismo correo y contraseña. El tenant_slug se genera internamente en el frontend y solo se pide en login si un mismo correo tiene varios perfiles.

8. Quality Gates

uv run ruff check app tests scripts
uv run mypy --explicit-package-bases app --strict
uv run bandit -c pyproject.toml -r app
uv run pip-audit --skip-editable
uv run pytest tests/unit tests/integration -q

La guía específica de gates está en ../../backend/docs/02_HOW_TO/quality-gates.md.