195 lines
4.2 KiB
Markdown
195 lines
4.2 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
git clone <repository-url> Olympus
|
|
cd Olympus
|
|
```
|
|
|
|
Umgebung anlegen:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
Wichtige lokale Werte:
|
|
|
|
```env
|
|
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:
|
|
|
|
```bash
|
|
docker network create olympus-network
|
|
```
|
|
|
|
Wenn das Netzwerk bereits existiert, meldet Docker das nur als Hinweis.
|
|
|
|
## Docker Compose Start
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
scripts/migrate.sh
|
|
```
|
|
|
|
Alternativ lokal im Backend:
|
|
|
|
```bash
|
|
cd backend/hermes
|
|
uv run alembic upgrade head
|
|
```
|
|
|
|
## Initial Admin
|
|
|
|
Fuer neue Installationen ohne aktive Benutzer kann Hermes beim Startup einen initialen Admin anlegen.
|
|
|
|
```env
|
|
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:
|
|
|
|
```env
|
|
STORAGE_HOST_PATH=./storage
|
|
STORAGE_BASE_PATH=/data/storage
|
|
```
|
|
|
|
VPS-Empfehlung:
|
|
|
|
```env
|
|
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:
|
|
|
|
```text
|
|
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.
|
|
|
|
## Typische Fehler
|
|
|
|
Hermes restartet wegen fehlender Migration:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
docker compose down
|
|
docker ps -a
|
|
```
|
|
|
|
Danach blockierenden Altcontainer gezielt entfernen, wenn er wirklich nicht mehr gebraucht wird.
|
|
|
|
External network fehlt:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
python3 -m compileall backend/hermes/app
|
|
cd frontend/athena
|
|
npm run lint
|
|
npx next build --webpack
|
|
```
|
|
|
|
Skripte pruefen:
|
|
|
|
```bash
|
|
bash -n scripts/*.sh
|
|
```
|