Dev Quickstart¶

Prerequisites¶

Node.js >= 24 (corepack enable for pnpm)
Docker & Docker Compose

Setup¶

git clone <repo-url> floh && cd floh
cp .env.example .env        # defaults work as-is for local dev
pnpm install

Start Infrastructure¶

pnpm docker:infra            # Postgres :5432, Redis :6379, MailHog :8025
pnpm migrate:latest          # apply database migrations

Default Ports¶

Port	Service	Env var
3000	API server	`PORT`
3001	Portal BFF	`PORTAL_PORT`
4200	Admin frontend	—
4201	Portal frontend	—

Run Services (HTTP)¶

Command	Service	URL
`pnpm dev:server`	API server	http://localhost:3000
`pnpm dev:web`	Admin frontend	http://localhost:4200
`pnpm dev:portal`	Portal (BFF + frontend)	http://localhost:3001 / http://localhost:4201

Or start everything at once:

pnpm dev

Run Services (HTTPS)¶

Generate local certs first (one-time):

pnpm generate-certs

Then uncomment TLS_CERT_FILE, TLS_KEY_FILE, and NODE_EXTRA_CA_CERTS in .env:

TLS_CERT_FILE=certs/localhost.crt
TLS_KEY_FILE=certs/localhost.key
NODE_EXTRA_CA_CERTS=certs/localhost.crt

NODE_EXTRA_CA_CERTS tells Node.js to trust the self-signed certificate, which is required for the portal BFF to proxy requests to the API server over HTTPS.

Command	Service	URL
`pnpm dev:server`	API server (start first)	https://localhost:3000
`pnpm dev:https`	Server + admin frontend	https://localhost:3000 / https://localhost:4200
`pnpm dev:portal:https`	Portal (BFF + frontend)	http://localhost:3001 / https://localhost:4201

The portal and admin frontend scripts do not start the API server. Run pnpm dev:server or pnpm dev:https in a separate terminal first.

Useful URLs¶

URL	What
http(s)://localhost:3000/api/docs	Swagger UI
http://localhost:8025	MailHog inbox

Auth¶

With OIDC_ISSUER left blank (the default), auth is bypassed and a built-in dev admin user is used. No provider setup needed.

Note: In production (NODE_ENV=production), OIDC_ISSUER is required. The server will refuse to start without it.

New Environment Variables¶

The following env vars were added as part of the architecture hardening work:

Env var	Default	Description
`ALLOWED_ORIGINS`	`FRONTEND_URL`	Comma-separated CORS allowed origins
`DB_POOL_MAX`	`10`	Max database pool connections
`DB_POOL_MIN`	`2`	Min idle database pool connections
`DB_POOL_IDLE_TIMEOUT_MS`	`30000`	Idle connection timeout
`DB_POOL_CONNECTION_TIMEOUT_MS`	`5000`	Connection acquisition timeout
`STUCK_RUN_TIMEOUT_MINUTES`	`30`	Timeout for stuck workflow runs

These can also be managed via Admin > Security Settings in the web UI (requires settings:manage permission).

CSRF Tokens¶

When OIDC is enabled, the server sets a floh_csrf cookie on login. The frontend automatically sends this as X-CSRF-Token on mutating requests. API clients using Bearer tokens are not affected.

Webhook Configuration¶

Connector webhooks now require HMAC-SHA256 signature verification. Set a webhook secret on the connector and send X-Webhook-Signature: <hmac-sha256-hex> with each webhook request.

MCP Server (AI Integration)¶

To set up the MCP server for Claude Desktop or Cursor, see MCP Setup. For Authifi RBAC configuration, run:

node scripts/setup-authifi-resource-server.mjs --help

Reporting¶

The admin UI includes a full reporting system at /reports/* with predefined templates, a visual query builder, multi-format export (PDF, Excel, CSV, Markdown), saved reports with sharing and scheduling. See Reporting for details.

Predefined templates are automatically seeded on server startup (migration 035_reporting). PDF export requires Puppeteer; Excel export requires ExcelJS — both are included in dependencies.

Tests¶

pnpm test:unit        # server unit (vitest)
pnpm test:integration # server integration (testcontainers)
pnpm test:web         # frontend (jest)
pnpm test             # all

Troubleshooting¶

Port already in use — if a dev server fails with ELIFECYCLE / exit status 2, a previous process is still holding the port. Find and kill it:

lsof -ti :3000 | xargs kill   # server
lsof -ti :4200 | xargs kill   # web
lsof -ti :3001 | xargs kill   # portal BFF
lsof -ti :4201 | xargs kill   # portal web

Stop Infrastructure¶

pnpm docker:down