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:

corepack enable
corepack prepare pnpm@11.12.0 --activate

Then install dependencies:

pnpm install

2. Create local environment placeholders

Copy the example environment file:

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:

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:

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:

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:

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.

3.7 KiB Raw Blame History