# ToolCTRL Boilerplate Quick Start ![coverage](https://img.shields.io/badge/coverage-see%20ci-blue) — 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`](docs/architecture/test-coverage.md). ## Installation New users should start with the focused documentation entrypoints: - [Quickstart](docs/quickstart.md) for install-to-first-local-run setup. - [New Project Onboarding](docs/new-project.md) for adapting the boilerplate to a new project. - [Local Development](docs/local-dev.md) 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](https://github.com/nvm-sh/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](https://www.prisma.io/docs/concepts/components/prisma-client/connection-management#direct-database-connection) 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](docs/deployment.md) - [Deployment porting notes](docs/deployment-porting.md) - [Troubleshooting](docs/troubleshooting.md) 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](https://github.com/evilmartians/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.