# Quickstart

Use this path to get from a fresh checkout to a local web runtime. It is for local development only: keep production secrets out of `.env`, use placeholders in examples, and run browser, Playwright, Cypress, or other E2E checks manually unless a focused run is explicitly approved.

## 1. Enable the pinned package manager

From the repository root, enable Corepack and activate the pinned pnpm version:

```sh
corepack enable
corepack prepare pnpm@11.12.0 --activate
```

Then install dependencies:

```sh
pnpm install
```

## 2. Create local environment placeholders

Copy the example environment file:

```sh
cp .env.example .env
```

Fill only local placeholder values. Do not paste production credentials, database passwords, API keys, Mailjet credentials, Legacy-Provider secrets, OAuth secrets, or deployment tokens into local docs or examples.

Minimum local values to review:

- `APP_NAME`: a local display name.
- `SESSION_SECRET`: a local placeholder secret.
- `CRYPTO_SECRET`: a separate local placeholder secret.
- `DATABASE_URL`: a local PostgreSQL connection string for Prisma.
- `APP_BASE_DOMAIN`, `WEB_APP_HOST`, `ADMIN_APP_HOST`, `API_HOST`, and `APP_PROTOCOL`: keep the split-host defaults from `.env.example`.
- `PORT` / `API_PORT`: listener bind ports only; keep defaults unless you need a custom local port.

## 3. Prepare PostgreSQL and Prisma

Start a local PostgreSQL database and point `DATABASE_URL` at it. The active application database uses PostgreSQL through Prisma.

Apply migrations:

```sh
pnpm exec prisma migrate dev
```

If you are bootstrapping a disposable local database and migrations are not enough, use a schema push as a local fallback:

```sh
pnpm exec prisma db push
```

Keep `DIRECT_URL` as a placeholder unless you intentionally need a direct Prisma database connection for local maintenance.

## 4. Seed local data

Seed the local database after the schema is ready:

```sh
pnpm seed
pnpm run permissions:sync
```

Seeded accounts are development conveniences only. `pnpm run permissions:sync` aligns the static role/permission matrix after schema or permission changes. Do not reuse seeded passwords or seed production databases from this quickstart.

## 5. Start the web runtime

Run the active `@hivegrid/web` React Router runtime in `apps/web/app`:

```sh
pnpm dev:local
```

Open `http://app.localhost:3000` for the tenant app and `http://admin.localhost:3000` for admin. Use `admin@email.com` / `password` for the canonical local admin login. `pnpm dev:local` restores this sole local admin with the `SuperAdmin` role and resets every password-backed platform or portal user in the disposable local database to `password` before the web runtime starts. It refuses CI, deployed, RLS-required, non-loopback, connection-parameter, or unmarked database targets. Fresh `pnpm dev:services` databases are marked automatically; run `pnpm dev:services:mark-local` once for an existing local Compose volume. The raw `pnpm dev` command intentionally skips this local credential setup.

## 6. Optional worker and Redis

Redis is optional for the default quickstart. Only enable it when you are working on queue or worker behavior:

- Set `WORKER_ENABLED=true`.
- Set `BULLMQ_REDIS_URL` to a local Redis placeholder such as `redis://localhost:6379/0`.
- Leave `REDIS_URL` as a fallback-only platform binding unless that contract is being tested.

## 7. Verification boundary

For quick local documentation checks, prefer scoped non-E2E commands such as linting changed files or running the milestone docs verifier when available. Browser automation, Playwright, Cypress, and other E2E execution are manual-only by default in this project and should not be added to automated quickstart steps without explicit approval for that exact run.