Update hivegrid-cloud reference to latest main
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
1 parent
e98d38e716
commit
7b21524c86
3781 files changed
+373484
-225607
No files matched your search
@@ -1,127 +1,110 @@
|
||||
# ToolCTRL Boilerplate Quick Start
|
||||
# HiveGrid Cloud
|
||||
|
||||
 — 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).
|
||||
HiveGrid Cloud ist die Produkt-Codebase fuer HiveGrid 2.0. Das Repo basiert historisch auf der HiveGrid-SaaS-Basis, wird aber als bespoke HiveGrid-Anwendung weitergebaut. Neue Arbeit passiert ticket-getrieben und muss den Projektregeln, dem gesperrten Entity-Modell und den Architekturentscheidungen folgen.
|
||||
|
||||
## Installation
|
||||

|
||||
|
||||
New users should start with the focused documentation entrypoints:
|
||||
## Zuerst lesen
|
||||
|
||||
- [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.
|
||||
- [`AGENTS.md`](AGENTS.md) ist die zentrale Arbeitsregel fuer Coding-Agents und Menschen, inklusive Ticket-Scope, Plane-Tracking, DoD, Prisma-Regeln und EU-Stack.
|
||||
- [`CLAUDE.md`](CLAUDE.md) ist der Claude-Code-Einstieg und importiert `AGENTS.md`, damit Claude dieselben Projektregeln nutzt.
|
||||
- [Ticket-Docs README](.planning/ticket-docs/README.md) beschreibt den Einstieg in ein Ticket.
|
||||
- [Entity Model](.planning/ENTITY-MODEL.md) ist die Datenmodell-Quelle der Wahrheit, besonders fuer P6-P9.
|
||||
- [Architecture Decisions](docs/ARCHITECTURE-DECISIONS.md) dokumentiert verbindliche Architekturentscheidungen.
|
||||
- [Agent Checklist](docs/AGENT-CHECKLIST.md) ist vor Commit und Push abzuarbeiten.
|
||||
|
||||
1. Enable the pinned package manager:
|
||||
## Arbeitsmodus
|
||||
|
||||
```
|
||||
Wir nutzen die `.planning/`-Struktur als Projektgedaechtnis, aber keine GSD-Slash-Commands. Gebaut wird nach Plane-Tickets und den zugehoerigen Ticket-Docs. Wenn Ticket-Doc, Entity Model und aeltere Specs widersprechen, gewinnt das Entity Model beziehungsweise `AGENTS.md`.
|
||||
|
||||
Wichtig fuer neue Arbeit:
|
||||
|
||||
- Strikt im Ticket-Scope bleiben.
|
||||
- DoD-Fortschritt als Prozent der Ticket-DoD melden.
|
||||
- UI-Routen importieren keine Subframe-Outputs direkt, sondern gehen ueber den Adapter-Layer.
|
||||
- Neue Fachmodelle werden typisiert in Prisma gebaut; der generische Entity-Builder ist Altlast und bekommt keine neuen Konsumenten.
|
||||
- Prisma-Modelle gehoeren in modulbezogene Dateien im Schema-Ordner.
|
||||
- US-Provider und Social-Login-Provider sind fuer HiveGrid nicht erlaubt.
|
||||
|
||||
## Repo-Aufbau
|
||||
|
||||
- `apps/web` enthaelt die React-Router-Web-App.
|
||||
- `apps/api` enthaelt die externe API.
|
||||
- `apps/worker` enthaelt Queue- und Hintergrundjobs.
|
||||
- `packages/*` enthaelt geteilte Runtime-, UI-, Config-, DB-, Mail- und View-Model-Pakete.
|
||||
- `prisma/schema` enthaelt das modulare Prisma-Schema.
|
||||
- `docs` und `.planning` enthalten Projektentscheidungen, Ticket-Docs und operative Runbooks.
|
||||
|
||||
## Lokales Setup
|
||||
|
||||
```sh
|
||||
corepack enable
|
||||
corepack prepare pnpm@10.33.0 --activate
|
||||
```
|
||||
|
||||
2. Install the dependencies:
|
||||
|
||||
```
|
||||
pnpm install
|
||||
```
|
||||
|
||||
3. Duplicate `.env.example` file to `.env`.
|
||||
Mit Zugriff auf die geteilten Dev-Secrets:
|
||||
|
||||
```sh
|
||||
pnpm env:pull
|
||||
```
|
||||
|
||||
Ohne Secrets fuer eine lokale Wegwerf-Umgebung:
|
||||
|
||||
```sh
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
4. Set up the minimum variables:
|
||||
Danach die lokalen Werte in `.env` setzen. Mindestens relevant sind `DATABASE_URL`, `SESSION_SECRET`, `CRYPTO_SECRET`, `APP_BASE_DOMAIN`, `WEB_APP_HOST`, `ADMIN_APP_HOST`, `API_HOST`, `APP_PROTOCOL` und `JWT_SECRET`. Worker/Redis ist nur noetig, wenn Worker-Flows lokal getestet werden.
|
||||
|
||||
- **`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.
|
||||
Datenbank und Seed:
|
||||
|
||||
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:
|
||||
|
||||
```
|
||||
```sh
|
||||
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:
|
||||
Web-App starten:
|
||||
|
||||
```
|
||||
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:
|
||||
|
||||
```
|
||||
```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`.
|
||||
Standard lokal:
|
||||
|
||||
- Tenant-App: `http://app.localhost:3000`
|
||||
- Admin-App: `http://admin.localhost:3000`
|
||||
- API bei Bedarf separat: `pnpm --filter @hivegrid/api dev`
|
||||
|
||||
## Verifikation
|
||||
|
||||
Vor Commit/Push mindestens:
|
||||
|
||||
```sh
|
||||
pnpm typecheck
|
||||
pnpm lint
|
||||
pnpm test
|
||||
```
|
||||
|
||||
Je nach Aenderung zusaetzlich die passenden `verify:*`-Gates aus der Agent-Checkliste. Haeufig relevant:
|
||||
|
||||
```sh
|
||||
pnpm run verify:ci-baseline
|
||||
pnpm run verify:env-drift
|
||||
pnpm run verify:docs-links
|
||||
pnpm run verify:production-docs
|
||||
pnpm run verify:deploy-readiness
|
||||
```
|
||||
|
||||
Browser-/E2E-Pruefungen werden nur gezielt ausgefuehrt, wenn sie fuer das Ticket noetig oder explizit beauftragt sind.
|
||||
|
||||
## 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`.
|
||||
Deployment laeuft ueber Coolify und Gitea CI. Details stehen in [Deployment](docs/deployment.md), [Database](docs/database.md), [Worker](docs/worker.md), [Mail](docs/mail.md), [Observability](docs/observability.md) und [Troubleshooting](docs/troubleshooting.md).
|
||||
|
||||
## Pre-commit hooks
|
||||
Produktionsdatenbank: `pnpm run db:migrate:deploy` fuer reviewed Migrations. Kein `prisma db push` gegen Production.
|
||||
|
||||
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.
|
||||
## Hooks und CI
|
||||
|
||||
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.
|
||||
Lefthook wird durch `pnpm install` eingerichtet. Pre-commit und pre-push laufen lokal, CI wiederholt die wichtigen Gates. Bypass nur bewusst und nur kurzfristig, weil CI denselben Fehler spaeter wieder sichtbar macht.
|
||||
Reference in new issue
Block a user