Configuración del Entorno de Desarrollo Local

Esta guía te acompaña en la configuración de un entorno de desarrollo local para lana-bank.

Requisitos Previos

• Nix con flakes habilitados
• Docker y Docker Compose

Inicio Rápido

1. Ingresar al Shell de Nix

nix develop

Esto proporciona un shell reproducible con todas las herramientas requeridas: cadena de herramientas Rust estable, Node.js 20, pnpm 10, Python 3.13, herramientas de cliente PostgreSQL y sqlx-cli.

2. Iniciar Dependencias

make start-deps

Esto inicia los siguientes servicios de Docker:

Servicio	Puerto	Propósito
core-pg (PostgreSQL)	5433	Base de datos principal de la aplicación
datawarehouse-pg (PostgreSQL)	5434	Almacén de datos para informes
keycloak	8081	Proveedor de identidad (OIDC)
keycloak-pg	5437	Base de datos de Keycloak
oathkeeper	4455	Puerta de enlace de API (validación JWT)
otel-agent	4317, 4318	Recolector de OpenTelemetry

3. Ejecutar el Backend

make setup-db run-server

Esto ejecuta las migraciones de base de datos e inicia el servidor de aplicación Rust.

4. Ejecutar las Aplicaciones Frontend

En terminales separadas:

# Panel de Administración

cd apps/admin-panel && pnpm dev

URLs de Desarrollo

Servicio	URL
Panel de Administración	http://admin.localhost:4455
API GraphQL de Administración	http://admin.localhost:4455/graphql
API GraphQL de Cliente	http://app.localhost:4455/graphql
Consola de Administración de Keycloak	http://localhost:8081

info

Las APIs GraphQL deben accederse a través de Oathkeeper (puerto 4455) que maneja la validación de JWT. Los puertos directos (5253/5254) carecen de contexto de autenticación y no funcionarán correctamente.

tip

Si app.localhost no se resuelve, añade 127.0.0.1 app.localhost y ::1 app.localhost a tu archivo /etc/hosts.

Desarrollo Interactivo con Process-Compose

Para un stack todo-en-uno en primer plano (dependencias, backend y panel de administración) con un TUI en vivo para logs y reinicios:

make dev-deps-and-app

Detén el stack del worktree con:

make dev-down

Comandos Comunes

Comando	Propósito
make start-deps	Iniciar dependencias de Docker
make stop-deps	Detener dependencias de Docker
make reset-deps	Limpiar y reiniciar bases de datos
make check-code-rust	Verificar que el código Rust compila
make check-code-apps	Lintear, verificar tipos y compilar frontends
cargo nextest run	Ejecutar todas las pruebas de Rust
cargo nextest run -p <crate>	Ejecutar pruebas para un solo crate
make e2e	Ejecutar pruebas end-to-end de BATS
make sdl	Regenerar esquemas GraphQL
make sqlx-prepare	Actualizar caché de consultas offline de SQLx

aviso

Antepón SQLX_OFFLINE=true a los comandos directos de cargo para usar la caché de consultas offline en lugar de requerir una base de datos en ejecución.

Acceso a la Base de Datos

Conéctate a la base de datos principal de PostgreSQL:

psql postgres://user:password@localhost:5433/pg

Ejecuta migraciones manualmente:

cargo sqlx migrate run

Las migraciones se encuentran en lana/app/migrations/.

Variables de Entorno

El shell de Nix establece automáticamente las variables de entorno clave:

Variable	Valor	Propósito
PG_CON	postgres://user:password@localhost:5433/pg	Conexión a la base de datos
ENCRYPTION_KEY	(clave de desarrollo)	Clave de cifrado para secretos
KC_URL	http://localhost:8081	URL de Keycloak
REALM	(configurado por realm)	Realm de Keycloak