Ein-Befehl-Entwicklungsstack mit Mailpit (#14)

ops/dev/run.sh: MariaDB (Volume), Mailpit, API/Worker/Web im Watch-Modus,
Migrationen und idempotente Testdaten (Superadmin, SMTP → Mailpit), nur
Dummy-Konfiguration. Probelauf: Web nach 20 s erreichbar, Login ok,
Passwort-vergessen-Mail kommt in Mailpit an. README ergänzt.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Claude (KI) 2026-10-06 13:00:57 +02:00
parent ce290143e6
commit 546e667081
6 changed files with 83 additions and 0 deletions

View file

@ -101,6 +101,18 @@ API-Module liegen in `apps/api/src/modules/<name>` und implementieren `KcModule`
`modules/index.ts` eingetragen, registrieren Routen und Rechte und sprechen nur über `core/*` und Jobs miteinander. `modules/index.ts` eingetragen, registrieren Routen und Rechte und sprechen nur über `core/*` und Jobs miteinander.
Neue Anbieter kommen als Connector unter `packages/connector-*` hinzu (`docs/connector-vertrag.md`). Neue Anbieter kommen als Connector unter `packages/connector-*` hinzu (`docs/connector-vertrag.md`).
## Lokale Entwicklung
Ein Befehl, nur Docker nötig:
```bash
ops/dev/run.sh
```
Startet MariaDB (eigenes Volume), Mailpit und API/Worker/Web im Watch-Modus mit Dummy-Konfiguration (`ops/dev/dev.env`).
Kundencenter: http://127.0.0.1:4101 (Anmeldung `dev@kundencenter.local` / `entwicklung-passwort-123`, 2FA wird beim ersten
Login eingerichtet), ausgehende Mails: http://127.0.0.1:8025. Zurücksetzen: `docker compose -f ops/dev/compose.yml down -v`.
Vor dem Commit: `pnpm check` (Modulgrenzen + Stilprüfung).
## Tests ## Tests
Ein Befehl, nur Docker nötig (frischer Checkout, Dummy-Schlüssel, Wegwerf-MariaDB im RAM – nie die Produktivdatenbank): Ein Befehl, nur Docker nötig (frischer Checkout, Dummy-Schlüssel, Wegwerf-MariaDB im RAM – nie die Produktivdatenbank):

24
ops/dev/compose.yml Normal file
View file

@ -0,0 +1,24 @@
# Lokaler Entwicklungsstack (#14): API + Worker + Web im Watch-Modus, eigene MariaDB, Mailpit für ausgehende Mails.
# Start: ops/dev/run.sh → Kundencenter http://127.0.0.1:4101 , Mailpit http://127.0.0.1:8025
# Nur Dummy-Konfiguration (ops/dev/dev.env), keine Verbindung zu Produktivsystemen.
name: kc-dev
services:
db:
image: mariadb:11.4
environment: { MARIADB_ROOT_PASSWORD: devroot, MARIADB_DATABASE: kundencenter_dev }
command: ["--character-set-server=utf8mb4", "--collation-server=utf8mb4_unicode_ci"]
volumes: [kc-dev-db:/var/lib/mysql]
healthcheck: { test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"], interval: 2s, timeout: 5s, retries: 30 }
mailpit:
image: axllent/mailpit:latest
ports: ["127.0.0.1:8025:8025"]
app:
build: ../test
depends_on: { db: { condition: service_healthy }, mailpit: { condition: service_started } }
working_dir: /w
volumes: ["../..:/w"]
env_file: dev.env
ports: ["127.0.0.1:4101:4101"]
command: ["bash", "ops/dev/start.sh"]
volumes:
kc-dev-db:

14
ops/dev/dev.env Normal file
View file

@ -0,0 +1,14 @@
# Dummy-Konfiguration NUR für den lokalen Entwicklungsstack – keine echten Geheimnisse.
KC_ENV_DIR=/nonexistent
KC_NODE_ENV=development
KC_BASE_URL=http://127.0.0.1:4101
KC_API_PORT=4100
DB_HOST=db
DB_PORT=3306
DB_NAME=kundencenter_dev
DB_USER=root
DB_PASSWORD=devroot
KC_SECRET_KEY=ZGV2LXNjaGx1ZXNzZWwtbnVyLWxva2FsLTMyLWJ5dGU=
LICENSE_PROGRAM_KEY=00000000-0000-0000-0000-000000000000
TICKET_ATTACHMENT_DIR=/tmp/kc-dev-attachments
BACKUP_STATUS_FILE=/tmp/kc-dev-backup-status.json

6
ops/dev/run.sh Executable file
View file

@ -0,0 +1,6 @@
#!/usr/bin/env bash
# Ein Befehl für die lokale Entwicklung. Beenden mit Strg+C; Datenbank bleibt im Volume kc-dev-db erhalten
# (zurücksetzen: docker compose -f ops/dev/compose.yml down -v).
set -euo pipefail
cd "$(dirname "$0")"
docker compose -f compose.yml up --build --abort-on-container-exit app

15
ops/dev/seed.mjs Normal file
View file

@ -0,0 +1,15 @@
// Testdaten für den Entwicklungsstack (idempotent): Superadmin und SMTP → Mailpit.
// Anmeldung: dev@kundencenter.local / entwicklung-passwort-123 (2FA wird beim ersten Login eingerichtet).
import { createRequire } from 'node:module';
const require = createRequire(new URL('../../apps/api/package.json', import.meta.url));
const mysql = require('mysql2/promise');
const { hash } = require('@node-rs/argon2');
const c = await mysql.createConnection({ host: process.env.DB_HOST, user: process.env.DB_USER, password: process.env.DB_PASSWORD, database: process.env.DB_NAME });
const [[u]] = await c.query("SELECT id FROM users WHERE email = 'dev@kundencenter.local'");
if (!u) {
await c.query("INSERT INTO users (id, email, name, password_hash, kind, staff_role, status, email_verified_at) VALUES (UUID(), 'dev@kundencenter.local', 'Entwicklung', ?, 'staff', 'superadmin', 'active', UTC_TIMESTAMP(3))", [await hash('entwicklung-passwort-123')]);
console.log('Superadmin angelegt: dev@kundencenter.local / entwicklung-passwort-123');
}
await c.query("UPDATE smtp_settings SET host = 'mailpit', port = 1025, secure_mode = 'none', from_name = 'Kundencenter (Entwicklung)', from_email = 'kundencenter@dev.local' WHERE id = 1");
await c.end();
console.log('Entwicklungsdaten bereit – Kundencenter http://127.0.0.1:4101 , Mailpit http://127.0.0.1:8025');

12
ops/dev/start.sh Executable file
View file

@ -0,0 +1,12 @@
#!/usr/bin/env bash
# Läuft im app-Container: installieren, bauen, migrieren, Testdaten anlegen, dann API/Worker/Web im Watch-Modus.
set -euo pipefail
pnpm install --frozen-lockfile
pnpm build
pnpm migrate
node ops/dev/seed.mjs
trap 'kill 0' EXIT
pnpm --filter @kc/api dev &
pnpm --filter @kc/worker dev &
pnpm --filter @kc/web exec next dev -p 4101 -H 0.0.0.0 &
wait