HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/docs/quickstart.md

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@10.33.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

Open http://app.localhost:3000 for the tenant app and http://admin.localhost:3000 for admin. The root pnpm dev command starts only the @hivegrid/web runtime; when API work is in scope, run pnpm --filter @hivegrid/api dev separately and open http://api.localhost:3001.

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.