Skip to main content
Fortress is a TypeScript monorepo. The API runs on port 3000; the web app runs on port 5173.

​
Prerequisites

  • Node.js 20 or newer
  • pnpm 10
  • Docker for Postgres
  • vp, the repo’s task runner wrapper

​
First run

vp run dev starts Docker services before launching the API and web processes.

​
Parallel worktrees

Codex/Claude worktrees under .codex/worktrees, .claude/worktrees, or .worktrees automatically get a stable port offset. Set FORTRESS_PORT_OFFSET when you want to choose the offset yourself:
This shifts Postgres, API, and web from 5433/3000/5173 to 5453/3020/5193. You can also set explicit ports with FORTRESS_DB_PORT, FORTRESS_API_PORT, and FORTRESS_WEB_PORT. Agent worktrees also get an isolated Docker Compose project name so their Postgres containers and volumes do not collide. For web-only agent worktrees, use the lighter setup profile:
This installs dependencies and prepares the web app without starting Postgres, running migrations, or loading dev fixtures. Use ./scripts/setup.sh or the Seed action when the worktree needs database-backed API flows.

​
Common commands

​
Migrations

Migrations are hand-authored SQL files in:
When changing the database:
  1. Update packages/api/src/db/schema.ts.
  2. Add the next numbered SQL migration.
  3. Run vp run db:migrate.
  4. Run vp run db:check.
The Drizzle schema does not generate migrations.

​
Scenario seeds

Focused scenario seeds live in:
Add a scenario seed when a UI surface is hard to exercise with db:seed-dev: empty states, long diffs, plan-limit cases, or deeply nested relationships. Scenario seeds should be idempotent.

​
Browser testing

Use the configured browser testing flow after UI changes. Start the dev server first:
Then drive the running app at localhost:5173. The browser session persists login state in the configured Playwright cache.