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 up-deps

Esto inicia los siguientes servicios de Docker:

Servicio	Puerto	Propósito
core-pg (PostgreSQL)	5433	Base de datos principal de la aplicación
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

El almacén de datos para informes no es un servicio: es un directorio local de DuckDB con raíz en .nix-deps/dw del worktree (consulta Pipelines de Datos).

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) vinculado a la shell que lo invoca:

make run-app

Para un stack en segundo plano con un TUI en vivo para logs y reinicios:

make up-app tui

Detén el stack del worktree con:

make down-deps

Comandos Comunes

Comando	Propósito
make up-deps	Iniciar dependencias gestionadas por Nix
make down-deps	Detener dependencias gestionadas por Nix
make recreate-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/.

Inspecciona el almacén de datos DuckDB (la copia de servicio de solo lectura) con el CLI duckdb incluido:

nix develop -c duckdb .nix-deps/dw/serve/lana_dw.duckdb -readonly

La raíz del almacén contiene la zona de aterrizaje Parquet, la base de datos de construcción de dbt y la copia de servicio publicada.

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
LANA__DW_DB__PATH	.nix-deps/dw	Directorio raíz del almacén de datos DuckDB
LANA__ENCRYPTION__PROVIDER	local-static (clave de desarrollo integrada)	Proveedor de claves de cifrado (google-kms en producción)
KC_URL	http://localhost:8081	URL de Keycloak
REALM	(configurado por realm)	Realm de Keycloak