Olympus/README-DEV.md

Olympus CRM Entwicklungssetup

Dieses Dokument beschreibt das lokale Setup fuer neue Rechner und parallele Entwicklung auf mehreren Macs.

Setup auf neuem Mac

Voraussetzungen:

• Git
• Docker Desktop
• Node.js passend zu Athena
• Python/uv fuer lokale Hermes-Checks

Repository klonen:

git clone <repository-url> Olympus
cd Olympus

Umgebung anlegen:

cp .env.example .env

Wichtige lokale Werte:

AUTH_COOKIE_SECURE=false
ATHENA_PUBLIC_ORIGIN=http://localhost:3001
STORAGE_PROVIDER=local
STORAGE_BASE_PATH=/data/storage
STORAGE_MAX_UPLOAD_MB=50
STORAGE_HOST_PATH=./storage
OLYMPUS_REPAIR_INTAKE_TOKEN=

Wenn SECRET_KEY Sonderzeichen wie $ enthaelt, den Wert in der Shell oder Compose-Umgebung korrekt quoten. Secrets gehoeren nicht ins Git.

Docker Netzwerk

Das gemeinsame Compose-File nutzt ein externes Docker-Netzwerk:

docker network create olympus-network

Wenn das Netzwerk bereits existiert, meldet Docker das nur als Hinweis.

Docker Compose Start

docker compose build
docker compose up -d

Hermes ist im gemeinsamen Stack nur intern im Docker-Netzwerk erreichbar. Athena ist lokal ueber den Browser erreichbar:

• Athena: http://localhost:3001
• Hermes intern: http://hermes:8000

Der Browser spricht nicht direkt mit Hermes.

Migrationen

Migrationen ausfuehren:

scripts/migrate.sh

Alternativ lokal im Backend:

cd backend/hermes
uv run alembic upgrade head

Initial Admin

Fuer neue Installationen ohne aktive Benutzer kann Hermes beim Startup einen initialen Admin anlegen.

INITIAL_ADMIN_USERNAME=admin
INITIAL_ADMIN_EMAIL=admin@example.local
INITIAL_ADMIN_PASSWORD=<lokales-passwort>
INITIAL_ADMIN_FIRST_NAME=
INITIAL_ADMIN_LAST_NAME=

Diese Werte nur lokal oder sicher auf dem Zielsystem setzen. Nach dem ersten produktiven Login sollte das Passwort geaendert und die Bootstrap-Variablen wieder entfernt werden.

Login

Nach Start und Migration:

1. Browser auf http://localhost:3001 oeffnen.
2. Mit dem initialen Admin oder einem bestehenden Benutzer anmelden.
3. Athena setzt das HttpOnly-Cookie. Hermes setzt keine Browser-Cookies.

Storage

Neue Dateiablagen laufen ueber das Storage Framework.

Lokaler Standard:

STORAGE_HOST_PATH=./storage
STORAGE_BASE_PATH=/data/storage

VPS-Empfehlung:

STORAGE_HOST_PATH=/opt/olympus-storage
STORAGE_BASE_PATH=/data/storage

Bestehende Knowledge-Dateien aus alten Setups unter /data/knowledge werden nicht automatisch verschoben. Vor einer manuellen Migration immer Backup erstellen.

Knowledge Workflow

Die Wissensdatenbank folgt lokal und produktiv diesem Ablauf:

Hersteller -> Gerät -> Dokument -> Notiz/Reparaturhinweis

Hermes legt beim Startup Standard-Hersteller an, wenn sie noch fehlen. Danach koennen Geraete angelegt werden. Dokumentuploads sind erst sinnvoll, wenn Hersteller und Geraet vorhanden sind; Athena blockiert unvollstaendige Uploads direkt im Formular.

Reparaturmanagement

Das Reparaturmodul ist ab v0.8.0 aktiv.

Lokaler Ablauf:

cd backend/hermes
SECRET_KEY=local-check uv run alembic upgrade head

Athena erreicht Reparaturen ausschliesslich ueber BFF-Routen:

• /api/repairs
• /api/repairs/[id]
• /api/repairs/[id]/status
• /api/repairs/[id]/history

Hermes stellt zusaetzlich POST /public/repair-intake fuer die spaetere Website-Anbindung bereit. Der Endpunkt ist fuer Server-zu-Server-Kommunikation gedacht und erwartet X-Olympus-Intake-Token. Der Token wird ueber OLYMPUS_REPAIR_INTAKE_TOKEN gesetzt und darf nicht im Browser verwendet werden.

Vorbereitete Kundenportal-Routen fuer spaeter:

• /status
• /reparatur/status
• /portal/login

Typische Fehler

Hermes restartet wegen fehlender Migration:

scripts/migrate.sh
docker compose restart hermes

SECRET_KEY mit $ wird falsch interpretiert:

• Wert in .env korrekt escapen oder quoten.
• Keine Secrets in Commit oder Logs schreiben.

Docker Container Name Conflict:

docker compose down
docker ps -a

Danach blockierenden Altcontainer gezielt entfernen, wenn er wirklich nicht mehr gebraucht wird.

External network fehlt:

docker network create olympus-network

DB leer oder Admin fehlt:

• INITIAL_ADMIN_* Werte setzen.
• scripts/migrate.sh ausfuehren.
• docker compose restart hermes.

Athena nicht erreichbar:

• docker compose ps pruefen.
• Port 3001 auf dem Rechner pruefen.
• scripts/healthcheck.sh ausfuehren.

MacBook und Mac mini parallel

Empfehlung:

• .env pro Rechner lokal pflegen und nicht committen.
• STORAGE_HOST_PATH pro Rechner bewusst setzen.
• Datenbank- und Storage-Backups nicht ungeprueft zwischen Rechnern ueberschreiben.
• Vor Branch-Wechseln Migrationen pruefen.
• Bei paralleler Arbeit keine Docker-Volumes loeschen, solange ungesicherte Uploads existieren.

Qualitaetschecks

python3 -m compileall backend/hermes/app
cd frontend/athena
npm run lint
npx next build --webpack

Skripte pruefen:

bash -n scripts/*.sh