Local development

New to the dev loop? Read Dev loop first — it explains when to hot-reload vs when to rebuild Docker, which is the decision this page assumes you already understand.

This page is the operational reference — the quick list of commands you run every morning. The deeper narrative (why port 3001, why 5433) lives in Getting started / Run it locally. Read that first on your first day, then use this page as the cheat sheet afterwards.

Prerequisites

Node.js 22.x — nvm install 22 && nvm use 22
pnpm 9.15.9 — corepack enable && corepack prepare pnpm@9.15.9 --activate
Docker 24+ with the Compose plugin
Go 1.25+ — only if you want to run the Hub natively; skip if you stay in Docker
OpenSSL — one-time, to generate secrets

One-time setup

Clone both repos into sibling folders

mkdir -p ~/AG-DEV && cd ~/AG-DEV
git clone <hivecfm-core-url> hivecfm-core
git clone <hivecfm-hub-url>  hivecfm-hub

The dev hub and all tooling assume hivecfm-core/ and hivecfm-hub/ live next to each other.

Install dependencies

cd hivecfm-core
pnpm install

First install takes ~40 seconds.

Create `.env`

cp .env.example .env
# Open .env and set:
#   NEXTAUTH_SECRET      -> openssl rand -base64 32
#   ENCRYPTION_KEY       -> openssl rand -hex 32
#   SUPERSET_ADMIN_PASSWORD -> openssl rand -hex 16

Ports default to 3001 for web (port 3000 is taken on shared dev boxes). Leave them alone unless you know why.

Daily flow

Start the infrastructure

cd ~/AG-DEV/hivecfm-core
docker compose -f docker-compose.yml -f docker-compose.dev-ports.yml up -d

The dev-ports overlay is what exposes Postgres on 5433 and Redis on 6380 to the host. Without it, native pnpm dev cannot reach them.

Migrate the database

pnpm run db:migrate

Runs pnpm --filter @hivecfm/database db:migrate:dev under the hood. Applies every migration under packages/database/migrations/ and regenerates the Prisma client.

Run the app

pnpm dev

Starts the Next.js app on http://localhost:3001 with hot-reload. To run one workspace only:

pnpm --filter @hivecfm/web dev

Verify

curl -s -o /dev/null -w "%{http_code}\n" http://localhost:3001     # 200
curl -s http://localhost:8090/health                               # {"status":"ok"}
docker compose ps                                                  # everything "running" or "healthy"

Open http://localhost:3001 and create the first account — the first user bootstraps the initial organisation.

Running the Hub natively (optional)

Skip this if the Docker-ised Hub is enough. To run it natively:

cd ~/AG-DEV/hivecfm-hub
cp .env.example .env   # point DATABASE_URL at localhost:5433/hivecfm_hub
go run ./cmd/api

The binary will:

Load config from .env.
Apply its own migrations/*.sql via goose.
Start the HTTP server on 8090 and the River worker pool.

Running the dev hub

The documentation site you are reading now:

cd ~/AG-DEV/hivecfm-dev-hub
pnpm install
pnpm dev

Binds to http://localhost:4100 by default.

Common tasks

Task	Command
Rebuild Prisma client after pulling main	`pnpm --filter @hivecfm/database db:migrate:dev`
Reset the DB (destructive)	`pnpm --filter @hivecfm/database dlx prisma migrate reset`
Run all tests	`pnpm test`
Run one app’s tests	`pnpm --filter @hivecfm/web test`
Lint	`pnpm lint`
Build for prod (local sanity check)	`pnpm build`
Tear everything down	`docker compose down` (keeps volumes) or `docker compose down -v` (destroys volumes)

When things break

Port already in use → Port conflicts runbook.
pnpm run db:migrate hangs or errors → Migration stuck runbook.
Next.js build runs out of memory → the build peaks around 8 GB. Bump Docker’s memory limit or run pnpm --filter @hivecfm/web build natively.
Prisma client is stale → re-run pnpm --filter @hivecfm/database db:migrate:dev. It migrates and regenerates.

If you touched schema.prisma and TypeScript still does not see the new field, it is almost always a stale client. Rebuild.