Local Development Setup
Run the ProBeya monorepo with its PostgreSQL 16 development stack.
Prerequisites
| Tool | Version | Check |
|---|---|---|
| Node.js | 22 | node --version |
| pnpm | 9.15.5 | pnpm --version |
| Docker | 24+ with Compose v2 | docker --version |
| Git | 2.40+ | git --version |
The WebSocket package targets Node.js 22. Enable the repository’s pinned pnpm version through Corepack:
corepack enable
corepack prepare [email protected] --activate
Setup
Clone and install
git clone https://github.com/obeya-cloud/obeya.git
cd obeya
pnpm install --frozen-lockfile
cp .env.example .env
The environment template contains working local database URLs and explicit production placeholders. Do not deploy it unchanged.
Start infrastructure
docker compose -f docker/docker-compose.yml up -d
docker compose -f docker/docker-compose.yml ps
| Service | Host port | Purpose |
|---|---|---|
| PostgreSQL 16 | 5433 | Primary database |
| Redis 7 | 6380 | Cache and pub/sub |
| PgBouncer | 6432 | Optional connection-pool testing |
| MinIO | 9010 / 9011 | S3 API / console |
| ClamAV | 3311 | Attachment scanning |
Apply and verify the database
pnpm db:migrate
pnpm --filter @probeya/db apply-rls
pnpm --filter @probeya/db check-rls
db:migrate applies the immutable, hash-verified Drizzle journal. The
apply/check pair installs and verifies the reviewed functions, constraints,
indexes, grants, and canonical RLS policies. All three commands are
required.
The migrator requires DATABASE_ADMIN_URL and never falls back to the
RLS-subject DATABASE_URL. db:push is only an explicit introspection
tool for disposable development databases.
Seed optional demo data
pnpm db:seed
The seed command prints the available accounts when it completes. The
primary demo login is [email protected] / demo1234.
Provision local object storage
In .env, keep the base container’s root identity only for bootstrap and
choose a different application key and secret:
MINIO_ROOT_USER=probeya_minio
MINIO_ROOT_PASSWORD=probeya_minio_secret
S3_ACCESS_KEY=probeya_local_app
S3_SECRET_KEY=<generate-a-distinct-local-secret>
S3_BUCKET=probeya-uploads
S3_ENDPOINT=http://localhost:9010
S3_PUBLIC_URL=http://localhost:9010
docker compose \
-f docker/docker-compose.yml \
-f docker/docker-compose.prod.yml \
run --rm --no-deps minio-init
The bootstrap creates a private bucket and least-privilege application identity. Attachments remain private.
Start the applications
pnpm dev
| Application | URL |
|---|---|
| Next.js web and API | http://localhost:8000 |
| WebSocket | ws://localhost:8003 |
| Docusaurus dev server | http://localhost:3002 |
| Mintlify dev server | http://localhost:3003 |
There is no separate API process. The routers in packages/api run inside
Next.js.
Common commands
pnpm dev
pnpm lint
pnpm type-check
pnpm test
pnpm build
pnpm db:generate
pnpm db:migrate
pnpm --filter @probeya/db apply-rls
pnpm --filter @probeya/db check-rls
pnpm --filter @probeya/db test:rls
pnpm db:seed
pnpm db:studio
Troubleshooting
Production self-hosting
Use the dedicated backup, ownership, schema, and startup sequence.
Was this page helpful?