Installation und Betrieb

Installation und Betrieb

Diese Seite beschreibt die drei Installationswege (PyPI, Docker Standalone, Docker Compose) sowie die wichtigsten Betriebs-Endpoints und Hintergrund-Jobs.

Voraussetzungen: Python ≥ 3.12 (bei PyPI-Installation) bzw. Docker; ein Verzeichnis mit den Schichtplaner5-.DBF-Dateien (alternativ der PostgreSQL-Mirror, siehe Konfiguration).

---

1. PyPI (empfohlen für native Installation)

pip install openschichtplaner5-api

Die Abhängigkeit libopenschichtplaner5[postgres]>=1.7.0 wird automatisch mitinstalliert. Start:

SP5_DB_PATH=/pfad/zu/SP5/Daten python -m uvicorn sp5api.main:app --host 0.0.0.0 --port 8000

• Einziger Einstiegspunkt ist die ASGI-App sp5api.main:app — es gibt bewusst kein CLI-Kommando.
• Für Produktion zusätzlich mindestens SECRET_KEY setzen (JWT-Signatur; ohne sie wird pro Prozess ein Zufallssecret erzeugt und alle Sessions verfallen beim Neustart) sowie SP5_BACKEND_DIR als Ressourcen-Root für Laufzeitdaten (JSON-Stores, Uploads). Details: Konfiguration.

⚠️ Ein Worker-Prozess: Session-Store, SSE-Subscriber, Metriken und Cache liegen im Prozess-Speicher. Die API ist für den Betrieb mit einem uvicorn-Worker ausgelegt (--workers 1, Default).

SPA- oder API-only-Modus

Liegt unter SP5_FRONTEND_DIST (Default: <SP5_BACKEND_DIR>/../frontend/dist) ein gebautes Frontend, wird es unter / ausgeliefert (Single-Page-App mit index.html-Fallback). Fehlt das Verzeichnis, läuft die API im reinen API-Modus — so betreibt man sie z. B. hinter der Hauptanwendung.

---

2. Docker Standalone (ein Container)

Das Repository enthält ein produktionsreifes Multi-Stage-Dockerfile (schlankes Runtime-Image, Non-Root-User, HEALTHCHECK auf /api/health, EXPOSE 8000). Im Image sind SP5_DB_PATH=/app/data und SP5_BACKEND_DIR=/app/backend vorkonfiguriert.

docker build -t openschichtplaner5-api .

# .env mit JWT-Secret anlegen (Minimum für Produktion)
echo "SECRET_KEY=$(openssl rand -hex 32)" > .env

docker run -d --name sp5-api -p 8000:8000 \
  -v /pfad/zu/SP5/Daten:/app/data \
  --env-file .env \
  openschichtplaner5-api

• DBF-Volume: Das Verzeichnis mit den .DBF-Dateien wird nach /app/data gemountet — die API liest und schreibt dort.
• Weitere Umgebungsvariablen (CORS, Rate-Limits, SMTP, …) kommen über die .env-Datei dazu, siehe Konfiguration.

Build gegen einen anderen Bibliotheksstand

Der Build installiert die Bibliothek standardmäßig von PyPI (libopenschichtplaner5[postgres]==1.7.0, gepinnt). Über das Build-Argument LIB_SOURCE lässt sich z. B. der Entwicklungsstand verwenden:

docker build --build-arg LIB_SOURCE=git+https://github.com/mschabhuettl/libopenschichtplaner5.git@main .

---

3. Docker Compose

Die beiliegende docker-compose.yml startet die API mit DBF-Volume und persistenten State-Volumes:

# 1. DBF-Verzeichnis angeben (in .env oder als Shell-Variable);
#    ohne Angabe wird ein Named Volume sp5_dbf verwendet
# 2. .env anlegen (SECRET_KEY für Produktion Pflicht)
SP5_DBF_DIR=/pfad/zu/SP5/Daten docker compose up --build

Gemountete Volumes:

Volume / Pfad	Container-Pfad	Inhalt
${SP5_DBF_DIR} (sonst Named Volume sp5_dbf)	/app/data	DBF-Datenbank
api_state	/app/backend/data	JSON-Stores (Webhooks, Scheduled Reports, …)
api_api_state	/app/backend/api	Laufzeit-State + Uploads (Fotos)
api_backups	/app/backend/backups	Auto-Migrations-Backups

Der Container läuft gehärtet (read_only: true, no-new-privileges, tmpfs /tmp, restart: unless-stopped). Das Build-Argument LIB_SOURCE ist per .env überschreibbar.

📦 Komplettes System gesucht? Die Hauptanwendung bringt ein Full-Stack-Compose (Frontend + API) mit — siehe App-Wiki → Installation.

---

4. Health, Metrics & Betriebs-Endpoints

Diese Endpoints sind ohne Anmeldung erreichbar:

Endpoint	Inhalt
GET /api/health	Aggregierter Health-Check: DB (5 kritische DBF-Tabellen), Disk, Memory, Uptime, aktive Sessions, Paketversion
GET /api/metrics	In-Process-Metriken: Request-Zähler, Fehlerrate, Cache-Hitrate, DB-Latenz
GET /api/version	API-Version, Python-Version, min_compatible_frontend
GET /api	Service-Info (Name, Version, aktives Backend dbf/postgresql)

curl http://localhost:8000/api/health
# → {"status":"healthy","checks":{"db":"ok","disk":"ok","memory":"ok"},"version":"1.2.0",...}

Der Docker-HEALTHCHECK nutzt ebenfalls /api/health.

Hintergrund-Jobs (beim Start)

Beim Hochfahren startet die API automatisch:

• DBF-Auto-Migration der Bibliothek (Schema-Updates; Status via GET /api/migration/status),
• DBF-Startup-Check (Prüfung der kritischen Tabellen),
• Auto-Backup (höchstens 1× pro 24 h, Rotation auf 7 Backups; Verwaltung über GET /api/admin/backups),
• Cleanup-Task für abgelaufene Sessions/Lockouts (Intervall SESSION_CLEANUP_INTERVAL_MINUTES, Default 5),
• Report-Scheduler für Scheduled Reports (Prüfung alle 5 Minuten).

Logging & Monitoring

• Strukturiertes JSON-Logging (umschaltbar auf Text via SP5_LOG_FORMAT) in eine rotierende Logdatei (LOG_FILE, Default /tmp/sp5-api.log), mit X-Request-ID-Propagierung.
• Audit-Log sicherheitsrelevanter Aktionen als JSON-Lines (SP5_AUDIT_LOG).
• Rate-Limit-Dashboard: 429-Ereignisse landen in einem Event-Log und sind für Admins über GET /api/admin/rate-limits abrufbar.

API-Versionierung

Jede Route existiert doppelt: kanonisch unter /api/... und unter /api/v1/... (empfohlen). Unversionierte Aufrufe erhalten die Header Deprecation: true, Sunset (+365 Tage) und Link: successor-version.

---

Siehe auch

• Konfiguration — vollständige Environment-Referenz
• Authentifizierung-und-Rechte — Erstanmeldung und Benutzerverwaltung
• App-Wiki → Health-Check
• Lib-Wiki → Datenbank-Backends