Set up Lumen locally

Outcome

A clean checkout has pinned JavaScript and Python dependencies, a healthy local PostgreSQL database, the current Alembic schema, the development project, and a generated TypeScript API client.

Prerequisites

• macOS or Linux with Git and Docker available to the current user;
• Node 24.18.0 and pnpm 11.15.0 exactly;
• Python 3.12.13, managed through uv; and
• enough local disk for dependency caches, PostgreSQL, and generated builds.

Do not place provider or cloud-administration credentials in the checkout. The ignored owner-only environment file is not part of this procedure.

Steps

From the repository root:

pnpm bootstrap

The command verifies tool versions, installs from lockfiles, starts the digest-pinned PostgreSQL container, creates the test database if needed, applies Alembic, seeds the development project, and regenerates the browser client.

Verify

The command ends with the next local URL and exits zero. For a stronger integration check, run:

pnpm check

That command runs formatting, lint, types, unit/integration tests, generated-contract drift, builds, migration drift, and the public-tree policy gate.

Recover

If version validation fails, install the exact version named by the error and rerun the command. If PostgreSQL does not become healthy, inspect Docker's status and the postgres service logs before changing files. Do not delete volumes as a first response: that discards local evidence and hides the original failure.

Next task

Run the deterministic research story.