Erste Schritte für Entwickler

Willkommen bei der Entwicklung von Katalon Collections! Dieser Leitfaden führt Sie durch das Einrichten einer lokalen Entwicklungsumgebung, das Starten der Dienste, den Umgang mit Zugangsdaten und das Laden von Testdaten.

Systemvoraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass folgende Software auf Ihrem System installiert ist:

Git (zur Quellcodeverwaltung)
Docker & Docker Compose v2 (Docker Desktop, OrbStack oder Docker Engine ab v24+)
(Optional für rein lokale Entwicklung ohne Docker):
- Python 3.14+ und uv (extrem schneller Python-Paketmanager)
- Node.js 20+ und npm bzw. pnpm
- libvips (unter macOS: brew install vips)

Repository klonen

Klonen Sie das offizielle Repository und wechseln Sie in das Projektverzeichnis:

git clone https://github.com/katalon-collections/katalon.git
cd katalon

Entwicklungsstack starten: `make dev` vs. `make up`

Katalon stellt ein komfortables Makefile bereit, das die wichtigsten Compose-Befehle kapselt:

1. Empfohlen: Entwicklungsmodus mit Live-Reload (`make dev`)

Der Entwicklungsmodus bindet den lokalen Quellcode als Volumes in die Container ein. Jede Änderung an Python-Dateien oder Frontend-Komponenten wird sofort ohne Neubau der Images wirksam:

make dev
# Alternativer direkter Compose-Aufruf:
# docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build

Was automatisch neu lädt:

FastAPI Backend: Uvicorn lädt bei Änderungen in backend/src/ per Hot-Reload neu.
Admin UI: Vite Hot Module Replacement (HMR) spiegelt Änderungen in frontend/admin/src/ sofort wider.
Portal UI: Vite HMR spiegelt Änderungen in frontend/portal/src/ wider.
Celery Worker: Überwacht Änderungen via watchfiles und startet die Worker-Prozesse neu.

2. Produktivitätsnaher Stack (`make up`)

Für Integrationstests, das Prüfen von Nginx-Routing, SSL-Terminierung und finalen Produktions-Builds:

make up
# Alternativer Aufruf:
# docker compose up -d --build

Im produktiven Modus laufen alle Frontends als vorkompilierte Nginx-Container; es gibt keinen automatischen Live-Reload.

Lokale URLs & Port-Regel

Achten Sie auf die Unterscheidung der Ports zwischen Dev- und Prod-Stack:

Dienst	Entwicklungs-Stack (`make dev`)	Prod-Stack (`make up` via Nginx)
Admin-Oberfläche	http://localhost:4000	http://localhost/admin/
Öffentliches Portal	http://localhost:4001	http://localhost/
FastAPI REST-API	http://localhost:8000	http://localhost/v1/ (intern geproxied)
Interaktive API-Docs	http://localhost:8000/api/docs	http://localhost/api/docs

Zugangsdaten & Erststart

Standard-Zugangsdaten im Dev-Stack

Beim ersten Start des Dev-Containers richtet das System automatisch ein administratives Erstkonto ein:

E-Mail: admin@katalon.dev
Passwort: adminadmin

Zufallspasswort bei gesetzter Basis-URL (`first-run-credentials.txt`)

Wird eine feste Basis-URL konfiguriert (z. B. KATALON_BASE_URL=https://katalon.local), generiert Katalon aus Sicherheitsgründen beim ersten Start ein kryptografisch sicheres Einmalkennwort:

Das Passwort wird in den Logs des API-Containers ausgegeben:
Terminal-Fenster
```
docker compose logs api | grep "KATALON FIRST RUN" -A 5
```
Zusätzlich wird die Datei /app/first-run-credentials.txt im API-Container abgelegt:
Terminal-Fenster
```
docker compose exec api cat /app/first-run-credentials.txt
```

Admin-Passwort zurücksetzen

Sollten Sie ein Kennwort vergessen haben, setzen Sie es über das integrierte CLI-Tool zurück:

# Zufälliges neues Passwort generieren und anzeigen:
docker compose exec api katalon-manage reset-admin --email admin@katalon.dev

# Oder explizit setzen:
docker compose exec api katalon-manage reset-admin --email admin@katalon.dev --password meinNeuesPasswort123

Demo- und Testdaten einspielen

Um Katalon mit einem realistischen Datenbestand auszuprobieren, existiert ein Seed-Skript für eine fiktive Weimarer Mustersammlung. Es erzeugt 100 verknüpfte Datensätze über alle 7 Kerntypen (Objekte, Akteure, Orte, Ausstellungen, Sammlungen, Lagerorte, Leihvorgänge) inklusive Bildern und Vokabularen.

Führen Sie das Skript im laufenden API-Container aus:

docker compose exec api python /app/scripts/seed_demo.py

Nützliche Optionen für das Seeding

--skip-downloads: Erzeugt synthetische Testbilder lokal per Pillow statt Beispieldateien aus dem Internet zu laden (extrem schnell und offline-fähig).
--no-images: Legt nur Metadatensätze ohne Medienverknüpfungen an.
--no-iiif: Überspringt das Einreihen von IIIF-Kachelungsaufgaben in die Celery-Queue.

Beispiel für ultraschnelles Offline-Seeding:

docker compose exec api python /app/scripts/seed_demo.py --skip-downloads --no-iiif

Datenbank & Suchindex zurücksetzen

Wenn Sie nach Schema-Experimenten oder Importtests wieder einen sauberen Zustand herstellen möchten:

1. Schneller Datenreset über die CLI (Schema bleibt erhalten)

# Setzt alle Erfassungsdaten zurück, behält aber Schema und Nutzer:
docker compose exec api katalon-manage db-reset --yes

# Vollständiger Reset inklusive Schema-Tabellen und Vokabularen:
docker compose exec api katalon-manage db-reset --all --no-backup --yes
docker compose restart api

2. Kompletter Docker-Volume-Reset (alles neu aufsetzen)

Löscht sämtliche Docker-Volumes (PostgreSQL-Datenbank, Elasticsearch-Index, Medienablage):

# Stack stoppen und Volumes vernichten:
make down-volumes
# Alternativ: docker compose down -v

# Stack neu starten (Alembic-Migrationen laufen automatisch beim Start):
make dev

Keine Volume-Löschung in Produktivumgebungen

Der Befehl docker compose down -v löscht sämtliche Datenbanken unwiderruflich. Verwenden Sie diesen Befehl ausschließlich auf lokalen Entwicklungsrechnern.