Golden-path bootstrap for new Pluma contributors — from clone to running stack
This skill documents the canonical, step-by-step process for getting a fully working local Pluma development environment. Follow this in order; every step is required.
npm install -g [email protected])git clone <repo-url>
cd pluma
pnpm install
All workspace packages are installed in one pass. Do not use npm install or yarn.
cd packages/db
docker-compose up -d
This starts a PostgreSQL 16 container bound to localhost:5432 with database pluma, user pluma, password pluma.
Verify it is healthy:
docker-compose ps
Expected: State column shows Up.
Each app and the db package need a .env file. Copy the provided examples:
# Database
cp packages/db/.env.example packages/db/.env
# API
cp apps/api/.env.example apps/api/.env
# Next.js UI
cp apps/app/.env.example apps/app/.env
Default values work out of the box for local development:
| File | Key variable | Default |
|---|---|---|
packages/db/.env | DATABASE_URL | postgresql://pluma:pluma@localhost:5432/pluma?schema=public |
apps/api/.env | PORT / HOST | 2137 / 0.0.0.0 |
apps/app/.env | NEXT_PUBLIC_API_URL | http://localhost:2137 |
Do not commit .env files. Only .env.example files are tracked in git.
pnpm --filter @pluma-flags/db db:generate
pnpm --filter @pluma-flags/db db:migrate
# optional
pnpm --filter @pluma-flags/db db:seed
# recommended: all apps together
pnpm --filter './apps/*' -r dev
pnpm --filter @pluma-flags/app dev # Next.js UI → http://localhost:3000
pnpm --filter @pluma-flags/api dev # Fastify API → http://localhost:2137
| Check | Command / URL | Expected |
|---|---|---|
| API health | curl http://localhost:2137/health | {"status":"ok"} or HTTP 200 |
| UI | http://localhost:3000 | Login / dashboard renders |
| DB Studio | pnpm --filter @pluma-flags/db db:studio | Opens at http://localhost:5555 |
| Symptom | Fix |
|---|---|
Cannot connect to database | Ensure Docker container is running: docker-compose ps in packages/db/ |
Prisma Client not found | Run pnpm --filter @pluma-flags/db db:generate |
Port already in use | Check .env PORT value; kill the conflicting process |
Module not found errors | Run pnpm install at repo root; check workspace:* deps are resolved |
| Stale types after schema change | Run pnpm --filter @pluma-flags/db db:generate then restart the API |
Invoke this skill when: