Developer Setup Guide — Help

This guide is for developers who want to run, modify, or deploy LanJAM.

Prerequisites

Before you begin, make sure you have the following installed:

Tool	Version	Purpose
Node.js	22 or later	JavaScript runtime
pnpm	9.x	Package manager
Docker & Docker Compose	Latest	Runs PostgreSQL, MinIO, and Whisper
Ollama	Latest	Runs AI models locally

Quick start

# Clone the repository
git clone <repo-url> && cd lanjam-ai

# Start infrastructure (PostgreSQL, MinIO, Whisper)
docker compose up -d

# Install dependencies
pnpm install

# Copy environment variables and fill in values
cp .env.example .env

# Run database migrations
pnpm db:migrate

# Start the development server
pnpm dev

Visit http://localhost:5173 to access the app. The first visit triggers the setup flow to create an admin account.

Installing Ollama

Ollama runs the AI models that power the chat. Install it on the machine that will do the AI processing:

macOS

brew install ollama
ollama serve

Linux

curl -fsSL https://ollama.com/install.sh | sh
ollama serve

Windows

Download the installer from ollama.com and run it. Ollama runs as a background service.

Once Ollama is running, pull a model:

ollama pull llama3.2

Project structure

LanJAM is a TurboRepo monorepo with pnpm workspaces:

apps/
  web/           → React Router 7 (SSR, Vite) + Tailwind v4
packages/
  api/           → Route handlers, services, middleware
  db/            → Drizzle ORM schemas, repositories, migrations
  utils/         → Shared types (Zod), error classes, utilities
  file-extract/  → File text extraction (PDF, DOCX, etc.)

Key commands

Command	Description
`pnpm dev`	Start dev server (all workspaces)
`pnpm build`	Build all packages and app
`pnpm lint`	Lint with Biome
`pnpm format`	Format with Biome
`pnpm check`	Type-check all workspaces
`pnpm db:generate`	Generate Drizzle migrations
`pnpm db:migrate`	Run database migrations
`pnpm db:push`	Push schema to DB (dev only)

Architecture

The API follows a Handler → Service → Repository pattern:

Handlers (packages/api/src/routes/) — Validate requests, call services, return responses
Services (packages/api/src/services/) — Business logic for external systems (Ollama, MinIO, embeddings)
Repositories (packages/db/src/repositories/) — Data access only, all methods require userId for data isolation

Authentication uses httpOnly cookies with SHA-256 hashed session tokens. Passcodes are hashed with argon2id.

Environment variables

Create a .env file from .env.example. Key variables:

Variable	Description	Default
`DATABASE_URL`	PostgreSQL connection string	`postgresql://lanjam:lanjam@localhost:5432/lanjam`
`MINIO_ENDPOINT`	MinIO host	`localhost`
`MINIO_PORT`	MinIO API port	`9100`
`MINIO_ACCESS_KEY`	MinIO access key	`minioadmin`
`MINIO_SECRET_KEY`	MinIO secret key	`minioadmin`
`OLLAMA_HOST`	Ollama API endpoint	`http://localhost:11434`
`WHISPER_HOST`	Whisper API endpoint	`http://localhost:8000`
`SESSION_SECRET`	Secret for sessions (min 32 chars)	—
`SESSION_DAYS`	Session expiry in days	`180`
`MAX_UPLOAD_MB`	Max file upload size	`25`

Docker services

The docker-compose.yml runs three services:

Service	Port	Notes
PostgreSQL 17 (+ pgvector)	5432	Persistent volume, health checks
MinIO	9100 (API), 9101 (Console)	S3-compatible object storage
Whisper	8000	Speech-to-text, CPU optimised

Database migrations

When you change the schema in packages/db/src/schema/:

# Generate a migration file
pnpm db:generate

# Apply migrations
pnpm db:migrate

Migration files are stored in packages/db/drizzle/.

Deployment considerations

LanJAM is designed for LAN-only access. Do not expose it to the public internet.
For production, set a strong SESSION_SECRET (at least 32 random characters).
Ollama can run on a separate, more powerful machine — set OLLAMA_HOST to point to it, or use the remote model feature in the admin panel.
The Whisper service is optional — voice input will not work without it, but everything else functions normally.
Consider backing up the PostgreSQL database and MinIO data volumes regularly.