89 lines
3.3 KiB
Markdown
89 lines
3.3 KiB
Markdown
# 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:
|
|
|
|
```sh
|
|
corepack enable
|
|
corepack prepare pnpm@10.33.0 --activate
|
|
```
|
|
|
|
Then install dependencies:
|
|
|
|
```sh
|
|
pnpm install
|
|
```
|
|
|
|
## 2. Create local environment placeholders
|
|
|
|
Copy the example environment file:
|
|
|
|
```sh
|
|
cp .env.example .env
|
|
```
|
|
|
|
Fill only local placeholder values. Do not paste production credentials, database passwords, API keys, Mailjet credentials, Stripe 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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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 `@toolctrl/web` React Router runtime in `apps/web/app`:
|
|
|
|
```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`.
|
|
|
|
## 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.
|