Running it locally

Six commands separate a freshly cloned repository from a running application. They are detailed below, but the sequence fits in one block:

pnpm install     # dependencies + Prisma client
pnpm docker:up   # PostgreSQL, Redis, pgAdmin
pnpm db:push     # the schema into the database
pnpm db:seed     # the reference data
pnpm dev         # the 7 services

The missing step before those is the .env file: without it, db:push does not know which database to target.

Prerequisites

Tool	Version	Why this version
Node	≥ 22.22	Required by React Router 8; the seed relies on its native .ts typing
pnpm	exactly 11.18.0	Pinned by packageManager — another version replays a different resolution
Docker	daemon running	PostgreSQL 18.4 and Redis 8.8 run in containers
python3	3.x	Only to probe the corpus; without it, db:seed loads the SQL snapshot

A script checks them and exits on the first one missing, naming the version it found:

pnpm check:prerequisites

The .env file

It lives at the root of the repository, and nowhere else: prisma.config.ts, the seed and the db:* commands all read it there. A variable already set in the shell takes precedence.

cp .env.example .env

The default values match the containers started by pnpm docker:up — in development, there is nothing to change.

Variable	Role
DATABASE_URL	PostgreSQL, shared by the five backends through packages/database
REDIS_URL	Redis: BullMQ queues and real-time pub/sub
REDIS_QUEUE_PREFIX	Queue prefix — isolates dev and preprod, which share one instance
SESSION_SECRET	Signature of the frontend's session cookies

The file also carries the service ports and the URLs the frontend uses to reach the backends. They are fixed: changing them breaks the contract tests.

The six commands

pnpm install

Installs the dependencies of the 12 workspaces. The postinstall hook of packages/database generates the Prisma client along the way.

pnpm docker:up

Starts PostgreSQL 18.4, Redis 8.8 and pgAdmin. The applications themselves are not containerised: they run through pnpm dev and connect over localhost.

pnpm docker:logs follows the logs, pnpm docker:down stops everything without losing the volumes.

pnpm db:push

Converges the database towards schema.prisma without going through a migration, then regenerates the client — Prisma chains generate on its own.

db:push is for development only

The command alters the schema in place, without confirmation. It refuses to start if DATABASE_URL does not point at localhost: a .env copied from .env.preprod therefore cannot touch the preprod schema. Overriding this requires an explicit ALLOW_REMOTE_RESET=1. Outside development, schema updates go through prisma migrate.

pnpm db:seed

Loads the reference data: technologies, event types, templates and datasets. The command first builds the packages the import depends on, then runs the import — the order matters, and this is what remembers it.

It is replayable: everything goes through upsert, a second run duplicates nothing. What it imports, what it infers and what it sets aside is detailed in Importing the corpus.

The corpus lives outside the repository

The data comes from _source-oldproject/, which is in .gitignore — it contains production intake keys. The path can be passed as an argument: pnpm db:seed ../elsewhere/_source-oldproject. If the folder is missing, the command does not stop: it loads the SQL snapshot versioned in the repository — which is also how CI and the deployed environments receive the corpus.

pnpm dev

Starts the seven services in parallel. The first run builds the shared packages, which takes about thirty seconds before the ports answer.

Checking that everything runs

Address	What you see there
http://localhost:3000	The dashboard: health of the five backends, live
http://localhost:3001/api	The Swagger UI of the configuration API
http://localhost:3005	This documentation
http://localhost:5050	pgAdmin (admin@sekoiacraft.com / sekoia)

Two scripts answer without opening a browser:

pnpm smoke:health   # the /health probes of the five backends
pnpm smoke:dev      # do the seven services answer on their port

Starting over

When the database has drifted — schema edited by hand, inconsistent test data — one command wipes and reloads it in a single go:

pnpm db:reset [corpus-path] [--overwrite-templates]

It chains dropping the database, pushing the schema, purging the BullMQ queues and reloading the corpus. Each step is detailed in Importing the corpus.

When it goes wrong

Symptom	Cause	What to do
db:push: "is not local"	The .env targets a remote database	Copy it again from .env.example
db:push: P1001, connection refused	PostgreSQL is not started, or not ready yet	pnpm docker:up, then try again
db:snapshot: "corpus not found"	_source-oldproject/ is missing	Drop it at the root, or pass its path as an argument
db:seed: python3: command not found	The import reads the registry by executing the source	Install Python 3
pnpm dev: a backend exits on DATABASE_URL is not defined	.env is missing	cp .env.example .env
The dashboard shows a backend in red	Postgres or Redis went down	pnpm docker:logs to read which one