Skip to main content

Local setup

Constellation is a Turborepo monorepo using npm workspaces. Node 20+ required.

Install​

git clone https://github.com/B2B-Online/constellation.git
cd constellation
npm install

Start the dev services​

The apps need a local PostgreSQL (shared by all modules) and MinIO (for storage).

npm run dev:services       # starts PostgreSQL + MinIO in Docker
npm run db:migrate         # applies all module migrations

Run an app​

npm run dev:dir            # Directory on :3001
npm run dev:pt             # Project Tracker on :3002
# or
npx turbo dev --filter=@constellation/catalog

Full CI pipeline locally​

Before every push:

npx prettier --check "**/*.{ts,tsx,js,jsx,json,md}"
npx turbo run lint typecheck build test
npm run check:routes

See the root CLAUDE.md for the full checklist.

Per-OS notes​

The setup above works on every supported OS — these sections only call out the gotchas that vary.

macOS​

Required tooling: node (≥ 20, install via nvm or Homebrew), docker (Docker Desktop or OrbStack), git. Recommended: psql from Homebrew (brew install postgresql@16) — set PSQL_PATH=/usr/local/bin/psql (or /opt/homebrew/bin/psql on Apple Silicon) in your .env.local so module migrations can find it.

If you use OrbStack instead of Docker Desktop, no special configuration is needed — npm run dev:services works against either.

Linux​

Required tooling: node (≥ 20), docker + docker compose plugin, git. The dev:services script binds default ports — make sure ports 5432 (Postgres) and 9000 / 9001 (MinIO) are free. If your distro packages psql separately (apt install postgresql-client), no env-var override is needed; the binary is on the default PATH.

Windows / WSL2​

The supported workflow is WSL2 with an Ubuntu (or similar) distro, not native Windows + PowerShell. Inside the WSL2 distro the Linux instructions above apply directly. Reasons:

  • Module migrations call psql and rely on POSIX tooling. PowerShell paths break the migration scripts in subtle ways.
  • Docker Desktop's WSL2 integration gives you docker and docker compose from inside the distro out of the box.
  • The repo has been exercised against WSL2 + Ubuntu 22.04+; native Windows is not currently in CI.

If you need to work directly on Windows for some reason, expect to debug shell-script differences yourself — patches welcome but support is best-effort.

Troubleshooting​

  • psql not found — on macOS set PSQL_PATH=/usr/local/bin/psql (or /opt/homebrew/bin/psql on Apple Silicon) in your .env.local.
  • Prisma client out of date — run npx turbo db:generate.
  • Port already in use — the dev:services Docker compose binds default ports; stop conflicting processes or edit docker-compose.dev.yml.