HiveGrid-Wireframes/hivegrid-cloud/README.md

ToolCTRL Boilerplate Quick Start

— refresh locally with pnpm coverage:badge after pnpm run verify:test-coverage. Coverage policy and per-path thresholds are documented in docs/architecture/test-coverage.md.

Installation

New users should start with the focused documentation entrypoints:

• Quickstart for install-to-first-local-run setup.
• New Project Onboarding for adapting the boilerplate to a new project.
• Local Development for day-to-day setup, service dependencies, and focused verification.

1. Enable the pinned package manager:

corepack enable
corepack prepare pnpm@10.33.0 --activate

2. Install the dependencies:

pnpm install

3. Duplicate .env.example file to .env.

cp .env.example .env

4. Set up the minimum variables:

• APP_NAME: Your app name.
• SESSION_SECRET: A secret string for sessions.
• CRYPTO_SECRET: A separate secret string for encrypted app data.
• DATABASE_URL: This is tied to the database provider at prisma/schema/schema.prisma (default is PostgreSQL).
• APP_BASE_DOMAIN, WEB_APP_HOST, ADMIN_APP_HOST, API_HOST, APP_PROTOCOL: Keep the split-host defaults from .env.example for local routing. Use PORT / API_PORT only as listener bind ports.

Worker Redis is optional for the quick start. Set WORKER_ENABLED=true and provide BULLMQ_REDIS_URL only when you run the worker; existing REDIS_URL platform bindings are used only as a fallback.

5. Create and seed the database:

pnpm exec prisma migrate dev
pnpm seed
pnpm run permissions:sync

🌱  The seed command has been executed.

If you get any issues, try pushing the database changes manually, and then seeding:

pnpm exec prisma db push
pnpm seed
pnpm run permissions:sync

If for any reason this also fails, run the following commands for a clean install:

rm -rf node_modules pnpm-lock.yaml
pnpm store prune
pnpm install

Optional: Install nvm and install the correct version of Node.js:

nvm install
nvm use

---

Demo users and tenants are opt-in for disposable local databases via SEED_DEMO_DATA=true. Static role and permission definitions live in @toolctrl/db/permissions-seed.server; run pnpm run permissions:sync after permission changes when you only need to align role definitions.

• 1 Admin User: Email is admin@email.com and password is password.
• 2 Tenants/Accounts: Acme Corp 1, Acme Corp 2.
• 2 App Users: john.doe@company.com and luna.davis@company.com, both with password password.

Production seeding is intentionally narrower: pnpm seed:prod creates only the configured bootstrap admin plus roles, permissions, and entitlements. It refuses local defaults and requires SEED_ADMIN_EMAIL / SEED_ADMIN_PASSWORD. The production Docker image also contains a built packages/db/dist/production-seed.server.js entrypoint for the Coolify web pre-deployment command.

Seed production database:

1. Create a .env.production file, and make sure to set the DATABASE_URL variable pointing to your prod database (e.g. postgres://{USER}:{PASSWORD}@{HOST}:{PORT}/{DATABASE}?pgbouncer=true).
2. Provide SEED_ADMIN_EMAIL and SEED_ADMIN_PASSWORD; do not edit seed source files with secrets.
3. Run pnpm run db:migrate:deploy to apply reviewed migrations. Do not use prisma db push against production.
4. Run pnpm seed:prod; this includes static roles, permissions, and entitlements.

DATABASE_URL vs DIRECT_URL: If you exhaust your database connection limit, you can use the DIRECT_URL env variable to connect directly to the database. Read the official Prisma docs for more info.

5. Start the application:

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 @toolctrl/web runtime; when API work is in scope, run pnpm --filter @toolctrl/api dev separately and open http://api.localhost:3001.

Deployment

• Deployment guide
• Deployment porting notes
• Troubleshooting plus focused runbooks in docs/local-dev.md, docs/database.md, docs/mail.md, docs/worker.md, and docs/observability.md.

Pre-commit hooks

Local hooks are managed by lefthook and configured in lefthook.yml. They install automatically the first time you run pnpm install (the root prepare script calls lefthook install), so no manual setup is required after a fresh clone.

What runs and when:

• pre-commit (in parallel): ESLint on staged *.ts/*.tsx files, verify:secrets, verify:eslint-baseline, and verify:test-density.
• pre-push: pnpm typecheck followed by verify:hardcoded-strings.

Bypass for a single commit only when you really need to: LEFTHOOK=0 git commit .... The same gates re-run in CI, so a bypass just shifts the failure to a later step.

If hooks ever stop firing (e.g. after switching branches with a different config), reinstall them with pnpm exec lefthook install.

Continuous Integration

The active Gitea CI pipeline starts with Corepack and the pinned pnpm version, installs dependencies with pnpm install --frozen-lockfile, then runs the quality, api, worker, database, and Docker smoke gates. Use pnpm run verify:ci-baseline, pnpm run verify:gitea-ci-workflow, pnpm run verify:deploy-workflow, and pnpm run verify:production-seed-artifact locally to statically verify the baseline CI contract, workflow contract, deploy workflow contract, and deploy seed artifact. These commands prove static contracts, not a live Coolify deployment. For post-port documentation review, use docs/porting-verification.md as the checklist.

The Docker smoke job runs after quality, api, worker, and database. It builds the web, api, and worker Dockerfile targets with local smoke tags, validates web Docker artifacts plus web/api/worker runtime smoke paths, and validates the Docker Compose configuration without logging in to a registry, pushing images, publishing artifacts, deploying, or running browser/E2E flows.

For this milestone, Auto-Mode does not run Playwright, browser, Cypress, or other E2E flows by default. Any E2E execution remains a manual verification step unless explicitly approved for a focused run.