Development Environment

For prerequisites, startup commands, service URLs, and environment variables, follow Local Development Setup. The default stack is Nix/process-compose with worktree-specific Portless routes, not Docker Compose or fixed ports.

Process-Compose Development

Start the full stack in the background and attach the TUI:

make up-app bootstrap tui

For a foreground stack tied to your terminal:

make run-app

Ctrl+C tears down the foreground stack. A background stack stays running until you stop it:

make down-deps

Use make restart-app to switch a dependency-only stack to the full application graph without deleting data.

Frontend Development

make up-app starts the Vite dev servers with the worktree's ports and Keycloak settings. To edit the admin panel, leave that process running; Vite reloads changed frontend files.

The managed admin process installs workspace dependencies and supplies ADMIN_PANEL_PORT, ADMIN_SERVER_PORT, KEYCLOAK_URL, KEYCLOAK_REALM=main-internal, and KEYCLOAK_CLIENT_ID=admin-panel. The Vite server proxies API requests to the worktree's backend.

Prefer this managed process over a bare pnpm dev, which otherwise defaults to port 3001 and does not register Portless routes or supply the Keycloak settings. To run Vite manually, preserve those settings and ensure its public origin matches an allowed Keycloak redirect URI.

Database Access and Reset

Inside the development shell:

psql "$LANA__RUNTIME_DB__PG_CON"
make setup-db

For a destructive reset, choose the stack you want to bring back:

make recreate-deps  # Dependencies only
# Or:
make recreate-app   # Dependencies, backend, and frontends

Both commands wipe .nix-deps/, including warehouse state, and rerun migrations automatically. Do not use them merely to restart processes.

Troubleshooting

Port or Route Conflicts

make status
make status-everywhere

Prefer make down-deps or make restart-app over killing processes manually. Portless assigns separate internal ports to each worktree; if you override the route name or base port, use the same values for the stack and development shell.

make down-proxy stops the shared Portless proxy and can affect other worktrees. Use it only for proxy recovery; the next up-* or run-* command starts it again.

Cache Issues

cargo clean
pnpm store prune

These clear build/package caches, not database state.

Authentication

The Keycloak master-console credentials are not the admin panel credentials. See Authentication (Local Dev) for the console login, instance realms, and passwordless development login.