Documentation

Installation

Prerequisites, workspace layout, and the container path — what the kit needs and what it deliberately does not.

The kit has a short list of hard requirements and a longer list of things it explicitly does not need. Both matter when you are deciding whether to adopt it.

Requirements

Node.js >=22.12.0 <23 — the repository pins 22.12.0 in .nvmrc and .node-version
npm Workspaces are used throughout. Do not use pnpm or yarn.
PostgreSQL Required and authoritative

No exact npm version is pinned. Use the root package-lock.json with npm ci for reproducible installs.

What is optional

This is the part worth reading twice, because it is where most portal stacks force a decision on you:

  • Redis — optional. Set REDIS_ENABLED=true and REDIS_HOST if you want cache-backed paths. Disabled in the Compose default stack.
  • Typesense — optional. It adds typo-tolerant search. Leave TYPESENSE_HOST unset and search uses PostgreSQL ILIKE/trigram behaviour instead.
  • The MLS worker — included, but idle until you configure a vendor.
  • The Agent API — off by default.

Neither Redis nor Typesense is a substitute for PostgreSQL, and Typesense never replaces PostgreSQL's authority over what is true.

Install

npm installcp .env.example .envnpm run db:migratenpm run dev

npm run db:migrate runs prisma migrate deploy and applies committed migrations. It does not create a migration.

API startup does not run migrations. Run npm run db:migrate explicitly as a separate release step before starting a newly deployed API version. Docker Compose handles this for you with a dedicated migrate service that runs once before the API starts.

Configure PostgreSQL

Set a PostgreSQL URL in the root .env:

.env
DATABASE_URL="postgresql://frontstead:change-me@localhost:5432/frontstead_dev?schema=public"

Use a dedicated local database and credentials. Never commit a real connection URL.

The MLS worker runs separately

apps/mls-service is a persistent worker, not a route in the API. It shares PostgreSQL with the API and nothing else:

cp apps/mls-service/.env.example apps/mls-service/.envnpm run dev --workspace=@frontstead/mls-service

The portal and API run perfectly well without it configured. See MLS board setup when you are ready to connect a real board.

Containers

Docker Compose is the canonical portable baseline:

docker compose up --build

The portal is at http://localhost:3006 and the API health endpoint at http://localhost:3001/health. PostgreSQL is exposed on 5432 for local tools, and data persists in the postgres-data named volume.

The default graph does not start or require MLS, Redis, Typesense, MinIO, cloud credentials, or Agent HQ.

Optional profiles

Profiles can be combined. Starting an infrastructure profile does not automatically opt the API or worker into that dependency — you supply the matching settings explicitly.

# Redis-backed cacheREDIS_ENABLED=true REDIS_HOST=redis docker compose --profile cache up --build# Typesense searchTYPESENSE_HOST=typesense TYPESENSE_API_KEY=replace-with-a-typesense-key \  docker compose --profile search up --build# S3-compatible local object storagedocker compose --profile storage up --build# Included MLS worker; idle unless MLS_AUTH_TYPE is configureddocker compose --profile mls up --build

Review and replace the placeholder database password and JWT secret before any shared or production deployment. Every committed value is blank, local-only, or an explicit replacement placeholder.

Next

Configuration — the one file that defines your portal.