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=trueandREDIS_HOSTif you want cache-backed paths. Disabled in the Compose default stack. - Typesense — optional. It adds typo-tolerant search. Leave
TYPESENSE_HOSTunset 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 devnpm 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:
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-serviceThe 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 --buildThe 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 --buildReview 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.