Local development

Contributor notes for the primary checkout and parallel Worktrunk worktrees. Operators who only want a first collection should stay on Getting started. Production layouts are under Deploy.

The same content lives in the repo as DEVELOPMENT.md.

Primary checkout

pnpm install
cp .env.example .env

Copy package env files from the matching *.env.example (cms-server/, cms-client/, packages/cms-db/, packages/storage/).

pnpm infra
pnpm db:migrate
pnpm dev

Process	Default
Admin UI (Vite)	http://localhost:5173
cms-server	http://localhost:3001
Postgres	`localhost:5432` / `cms`
RustFS (S3)	http://localhost:9000

Docs site (this site; separate process):

pnpm --filter docs dev

Open http://localhost:4000.

pnpm infra          # Docker: cms-postgres, rustfs (host ports published)
pnpm db:push
pnpm db:studio

Env files

Gitignored .env files (copy from the matching *.env.example):

File	What it is for
`cms-server/.env`	`CMS_DATABASE_URL`, `CMS_PUBLIC_BASE_URL`, `CORS_ORIGIN`, storage, auth, optional `PORT`
`cms-client/.env`	Vite: `VITE_CMS_API_BASE`, optional `VITE_DEV_PORT`
`packages/cms-db/.env`	`CMS_DATABASE_URL` for `db:push` / Studio
`packages/storage/.env`	RustFS / S3 for local storage package use
`.env` (repo root)	Compose: Postgres password, published ports, image env

Full Compose (docker compose up -d) serves the admin UI on :8080 instead of Vite :5173.

Worktrees

Worktrunk (wt) creates a sibling checkout. Project hooks then isolate it. Start any agent in that directory after wt finishes.

Shared with the primary checkout	Isolated per worktree
Docker Compose (Postgres, RustFS `:9000`)	App ports via `hash_port` (10000–19999)
pnpm content-addressable store	Postgres `wcwt_*` (copy of `cms`)

node_modules is not copied. pre-start runs pnpm install --frozen-lockfile --prefer-offline so the worktree only relinks from the store.

Install (once)

sudo pacman -S worktrunk && wt config shell install
# or: cargo install worktrunk && wt config shell install

First create in this repo asks you to approve hooks (wt config approvals add). Hooks live in .config/wt.toml. Scripts: scripts/worktree/isolate.sh, scripts/worktree/teardown.sh.

Create

wt switch --create feature-name

Creates ~/projects/wafercms.feature-name, copies .env files from the primary checkout, rewrites ports / database, installs from the pnpm store, copies cms → wcwt_*, then tethers pnpm dev.

wt switch --create -x claude feature-name -- 'the task'
wt switch feature-name

Same branch name → same ports on any machine. Do not bind 5173 / 3001 in a worktree.

Look around / remove

wt list          # URL column = Vite
wt urls          # client / api
wt open
cat .worktree-env
wt dev           # restart the stack
pnpm worktree:isolate   # rewrite env if setup failed
wt remove        # drops wcwt_* ; does not stop shared Docker

Uploads still go through shared RustFS on :9000. File rows live in the worktree database.