Local Development Setup

This guide walks you through setting up a local development environment for lana-bank.

Prerequisites

• Nix with flakes enabled
• Docker and Docker Compose

Quick Start

1. Enter the Nix Shell

nix develop

This provides a reproducible shell with all required tools: Rust stable toolchain, Node.js 20, pnpm 10, Python 3.13, PostgreSQL client tools, and sqlx-cli.

2. Start Dependencies

make up-deps

This starts the following Docker services:

Service	Port	Purpose
core-pg (PostgreSQL)	5433	Main application database
keycloak	8081	Identity provider (OIDC)
keycloak-pg	5437	Keycloak database
otel-agent	4317, 4318	OpenTelemetry collector

The reporting data warehouse is not a service: it is a local DuckDB directory rooted at .nix-deps/dw in the worktree (see Data Pipelines).

3. Run the Backend

make setup-db run-server

This runs database migrations and starts the Rust application server.

4. Run Frontend Apps

In separate terminals:

# Admin Panel
cd apps/admin-panel && pnpm dev

Development URLs

Service	URL
Admin Panel	http://admin.lana-bank.localhost:1355
Admin GraphQL API	http://admin.lana-bank.localhost:1355/graphql
Customer GraphQL API	http://app.lana-bank.localhost:1355/graphql
Keycloak Admin Console	http://localhost:8081

info

GraphQL APIs validate Keycloak JWTs in the Rust servers. The admin panel dev server proxies /graphql to the admin API for same-origin browser requests.

tip

If app.localhost doesn't resolve, add 127.0.0.1 app.localhost and ::1 app.localhost to your /etc/hosts file.

Interactive Development with Process-Compose

For an all-in-one foreground stack (dependencies, backend, and admin panel) tied to the invoking shell:

make run-app

For a background stack with a live TUI for logs and restarts:

make up-app tui

Stop the worktree's stack with:

make down-deps

Common Commands

Command	Purpose
make up-deps	Start Nix-managed dependencies
make down-deps	Stop Nix-managed dependencies
make recreate-deps	Clean and restart databases
make check-code-rust	Verify Rust code compiles
make check-code-apps	Lint, type-check, and build frontends
cargo nextest run	Run all Rust tests
cargo nextest run -p <crate>	Run tests for a single crate
make e2e	Run BATS end-to-end tests
make sdl	Regenerate GraphQL schemas
make sqlx-prepare	Update SQLx offline query cache

warning

Prefix direct cargo commands with SQLX_OFFLINE=true to use the offline query cache instead of requiring a running database.

Database Access

Connect to the main PostgreSQL database:

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

Run migrations manually:

cargo sqlx migrate run

Migrations are located in lana/app/migrations/.

Inspect the DuckDB data warehouse (the read-only serving copy) with the bundled duckdb CLI:

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

The warehouse root contains the Parquet landing zone, the dbt build database, and the published serving copy.

Environment Variables

The Nix shell automatically sets key environment variables:

Variable	Value	Purpose
LANA__RUNTIME_DB__PG_CON	postgres://user:password@localhost:5433/pg	Runtime database connection
LANA__DW_DB__PATH	.nix-deps/dw	DuckDB data warehouse root directory
LANA__ENCRYPTION__PROVIDER	local-static (built-in dev key)	Encryption key provider (google-kms in production)
KC_URL	http://localhost:8081	Keycloak URL
REALM	(configured per realm)	Keycloak realm