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

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.

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