> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fortressproductivity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Local development

> Run Fortress locally.

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

```bash theme={"theme":"github-dark"}
vp install
vp run services:up
vp run db:migrate
vp run db:seed
vp run db:seed-dev
vp run dev
```

`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:

```bash theme={"theme":"github-dark"}
FORTRESS_PORT_OFFSET=20 vp run dev
```

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:

```bash theme={"theme":"github-dark"}
./scripts/setup.sh web
```

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

| Command                | Purpose                                             |
| ---------------------- | --------------------------------------------------- |
| `vp run dev`           | Start API and web.                                  |
| `vp run dev:api`       | API only.                                           |
| `vp run dev:web`       | Web only.                                           |
| `vp run test`          | Run tests.                                          |
| `vp run typecheck`     | Type-check all packages.                            |
| `vp run db:migrate`    | Apply SQL migrations.                               |
| `vp run db:check`      | Detect schema drift against the migrated dev DB.    |
| `vp run db:seed`       | Seed default account, user, workspace, and domains. |
| `vp run db:seed-dev`   | Populate realistic development data.                |
| `vp run services:down` | Stop Postgres.                                      |

## Migrations

Migrations are hand-authored SQL files in:

```text theme={"theme":"github-dark"}
packages/api/drizzle/
```

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:

```text theme={"theme":"github-dark"}
packages/api/src/db/seeds/
```

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:

```bash theme={"theme":"github-dark"}
vp run dev
```

Then drive the running app at `localhost:5173`. The browser session persists login state in the configured Playwright cache.