130 lines
6.1 KiB
Markdown
130 lines
6.1 KiB
Markdown
# New Project Onboarding
|
|
|
|
## Purpose
|
|
|
|
This guide is the local quick-start entrypoint for starting a new project from the boilerplate. It focuses on the current repository state: root scripts start the `@toolctrl/web` React Router runtime whose source lives in `apps/web/app`, while `apps/api` and `apps/worker` are extracted foundations for API and worker evolution. `apps/api` is a runtime-wired Hono API app with a canonical `/v1` surface, and `apps/worker` is opt-in through worker environment flags.
|
|
|
|
Start with [`docs/quickstart.md`](./quickstart.md) for first-run bootstrap, then use [`docs/local-dev.md`](./local-dev.md) for day-to-day local development, service dependencies, verification, and troubleshooting.
|
|
|
|
Use this document for local setup and static verification. Browser, Playwright, Cypress, and other E2E checks are manual unless a focused run is explicitly approved.
|
|
|
|
## Prerequisites
|
|
|
|
Install or provide these local dependencies before running the project:
|
|
|
|
- Node.js compatible with the repository `.nvmrc` when present.
|
|
- Corepack for the pinned package manager.
|
|
- `pnpm@10.33.0` through Corepack.
|
|
- PostgreSQL for the Prisma-backed application database.
|
|
- Optional Redis only when running the BullMQ worker foundation.
|
|
|
|
Enable the pinned package manager:
|
|
|
|
```sh
|
|
corepack enable
|
|
corepack prepare pnpm@10.33.0 --activate
|
|
```
|
|
|
|
## Install Dependencies
|
|
|
|
Install the workspace dependencies from the repository root:
|
|
|
|
```sh
|
|
pnpm install
|
|
```
|
|
|
|
Root scripts start the active `@toolctrl/web` React Router runtime from `apps/web/app`. Workspace packages such as `@toolctrl/db`, `@toolctrl/mail`, and `@toolctrl/queue` describe current or target boundaries, but they do not replace the web runtime for local development.
|
|
|
|
## Environment Setup
|
|
|
|
Create a local environment file from the example:
|
|
|
|
```sh
|
|
cp .env.example .env
|
|
```
|
|
|
|
Set placeholder values for local development. Do not copy production secrets into `.env`.
|
|
|
|
Required local variables:
|
|
|
|
- `APP_NAME`: local display name for the app.
|
|
- `SESSION_SECRET`: placeholder-only local session secret.
|
|
- `CRYPTO_SECRET`: placeholder-only local encryption secret.
|
|
- `DATABASE_URL`: PostgreSQL connection string used by Prisma.
|
|
- `APP_BASE_DOMAIN`, `WEB_APP_HOST`, `ADMIN_APP_HOST`, `API_HOST`, and `APP_PROTOCOL`: split-host routing settings from `.env.example`.
|
|
- `PORT` / `API_PORT`: listener bind ports only; keep the example defaults unless you need a custom local port.
|
|
|
|
Transactional mail is represented by the Mailjet boundary. Keep any Mailjet API keys or webhook signing secrets as placeholder-only local values unless you are deliberately testing mail delivery with a non-production account.
|
|
|
|
## PostgreSQL and Prisma Setup
|
|
|
|
Start a local PostgreSQL database, then point `DATABASE_URL` at that database. The active database stack is PostgreSQL through Prisma. The Prisma schema and migrations still live under `prisma/`, while `packages/db` owns the server-side Prisma client boundary and database command surface.
|
|
|
|
Apply the schema with Prisma:
|
|
|
|
```sh
|
|
pnpm exec prisma migrate dev
|
|
```
|
|
|
|
If you need a schema push during local bootstrap, use:
|
|
|
|
```sh
|
|
pnpm exec prisma db push
|
|
```
|
|
|
|
Use `DIRECT_URL` only when you intentionally need a direct database connection for Prisma operations. Keep both `DATABASE_URL` and `DIRECT_URL` as placeholders in documentation and local examples.
|
|
|
|
## Seed and Run the Web App
|
|
|
|
Seed the local database when needed:
|
|
|
|
```sh
|
|
pnpm seed
|
|
pnpm run permissions:sync
|
|
```
|
|
|
|
Start the active `@toolctrl/web` React Router runtime from the root script:
|
|
|
|
```sh
|
|
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`. Seeded demo tenants and users are created only when `SEED_DEMO_DATA=true` is set for a disposable local database; those accounts must not be reused as production credentials.
|
|
|
|
## Optional Worker Redis
|
|
|
|
Redis is not required for the default web quick start. Enable worker execution only when you are working on queue-backed behavior:
|
|
|
|
- Set `WORKER_ENABLED=true`.
|
|
- Set `BULLMQ_REDIS_URL` to a local Redis connection placeholder.
|
|
- Set `WORKER_QUEUE_GROUP` to the queue group you are testing, such as `general`, `mail`, or `plugin`.
|
|
- Use `REDIS_URL` only as a platform-binding fallback when that is the environment contract being tested.
|
|
|
|
`apps/worker` exits unless `WORKER_ENABLED=true`. It now contains active BullMQ processors for optional background surfaces, including general maintenance/notification/outbox work, mail-bound jobs, and the isolated plugin invocation queue. Some feature-specific processors remain behind their own environment gates, so do not treat Redis as mandatory for every new project user.
|
|
|
|
## Static Verification Commands
|
|
|
|
Run scoped non-E2E checks before handing off local setup changes:
|
|
|
|
```sh
|
|
test -s docs/new-project.md
|
|
grep -Eq "Corepack|pnpm@10\.33\.0|DATABASE_URL|PostgreSQL|Prisma|WORKER_ENABLED|BULLMQ_REDIS_URL|manual" docs/new-project.md
|
|
pnpm run verify:ci-baseline
|
|
pnpm run verify:gitea-ci-workflow
|
|
```
|
|
|
|
Use focused lint or test commands for files you changed. Full browser and E2E suites are not part of Auto-Mode task verification unless explicitly approved for that exact run.
|
|
|
|
## Manual Checks
|
|
|
|
After the static checks pass, use manual checks only for human-facing confidence:
|
|
|
|
1. Confirm `.env` contains only local placeholders and no real deployment secrets.
|
|
2. Confirm PostgreSQL is reachable through `DATABASE_URL`.
|
|
3. Confirm Prisma migration or push completed successfully.
|
|
4. Confirm `pnpm seed` created local development data and `pnpm run permissions:sync` aligned static roles and permissions.
|
|
5. Confirm `pnpm dev` starts the `@toolctrl/web` React Router runtime in `apps/web/app` and serves the configured app/admin hosts.
|
|
6. If worker work is in scope, confirm Redis is running and the worker is started with `WORKER_ENABLED=true` and `BULLMQ_REDIS_URL` set.
|
|
|
|
Keep Playwright, Cypress, browser automation, and other E2E execution manual by default. Record the scenario and result in handoff notes instead of adding automatic E2E runs to local onboarding.
|