Installation

🔧 Installation & Einrichtung

Diese Seite beschreibt die Installation von OpenSchichtplaner5 v1.2.0 — per Docker (empfohlen) oder lokal ohne Docker.

---

Voraussetzungen

Komponente	Mindestversion	Empfohlen
Docker (empfohlener Weg)	aktuelle Engine + Compose	—
Python (lokal)	3.12	3.12+
Node.js (lokal)	20.x	20.x LTS
RAM	512 MB	1 GB+
Betriebssystem	Linux, macOS, Windows (WSL 2)	Ubuntu 24.04 LTS

💡 Auf Windows wird der Betrieb über WSL 2 (Windows Subsystem for Linux) empfohlen.

---

🐳 Docker (empfohlen)

Fertige Images werden bei jedem Release in die GitHub Container Registry veröffentlicht:

docker pull ghcr.io/mschabhuettl/openschichtplaner5:latest   # oder :1.2.0

Das Image liefert SPA + API aus einem Container auf Port 8000. Den Ordner mit den Schichtplaner5-.DBF-Dateien nach /app/data mounten und einen SECRET_KEY setzen — alles andere hat sinnvolle Defaults:

docker run -d --name openschichtplaner5 -p 8000:8000 \
  -v /pfad/zu/SP5/Daten:/app/data \
  -e SECRET_KEY=$(openssl rand -hex 32) \
  ghcr.io/mschabhuettl/openschichtplaner5:latest

curl http://localhost:8000/api/health   # → {"status":"healthy",...}

Docker Compose

git clone https://github.com/mschabhuettl/openschichtplaner5.git
cd openschichtplaner5
cp .env.example .env && nano .env   # SP5_DB_PATH + SECRET_KEY setzen!
make prod                           # docker compose up -d --build

Hinweise:

• In Docker liegt die Datenbank einheitlich unter /app/data (DBF-Dateien direkt im Volume-Root des sp5_data-Volumes) — ohne .env-Eintrag läuft das Setup out of the box
• Veränderlicher Laufzeit-Zustand (JSON-Stores, Foto-Uploads, Auto-Migrate-Backups) liegt in eigenen Named Volumes (sp5_state, sp5_api_state, sp5_backups) und übersteht Container-Neuerstellungen; das Root-Dateisystem des Containers bleibt read-only
• Beim lokalen Bauen statt Pullen: die Build-Args LIB_SOURCE / API_SOURCE zeigen standardmäßig auf die PyPI-Pins der Library und des API-Pakets und sind mit beliebigen pip-Requirements überschreibbar

Für das Produktions-Setup mit nginx-Reverse-Proxy, SSL/Let's Encrypt, Backups und Hardening-Checkliste siehe docs/DEPLOYMENT.md im Repository.

🧱 Gesamt-Stack (drei Container)

Für den Betrieb mit getrennten Containern für SPA und API gibt es docker-compose.stack.yml:

• app — nginx served das gebaute SPA und proxied /api an den API-Container (Port 8080)
• api — der REST-API-Container, gebaut aus dem Geschwister-Repo ../openschichtplaner5-api (Port 8000)
• postgres — optionales Profil für den PostgreSQL-Betrieb (DB_BACKEND=postgresql), inkl. einmaligem DBF→PostgreSQL-Seed-Schritt

# Voraussetzung: openschichtplaner5-api liegt als Geschwister-Verzeichnis daneben
docker compose -f docker-compose.stack.yml up -d --build

# DBF-Daten als Host-Verzeichnis statt leerem Named Volume:
SP5_DBF_DIR=/pfad/zu/SP5/Daten docker compose -f docker-compose.stack.yml up -d --build

# mit PostgreSQL-Profil (zusätzlich DB_BACKEND=postgresql in .env):
docker compose -f docker-compose.stack.yml --profile postgres up -d --build

💡 Der Gesamt-Stack ist für Setups gedacht, die Frontend und API getrennt skalieren oder betreiben wollen. Für den Einstieg reicht das Einzel-Image völlig. (Verfügbar auf dem main-Branch.)

---

Lokal ohne Docker

Voraussetzungen: Python 3.12+, Node.js 20+, Zugriff auf die SP5-.DBF-Dateien.

git clone https://github.com/mschabhuettl/openschichtplaner5.git
cd openschichtplaner5
bash start.sh          # legt .env + venv an, baut das Frontend, startet auf :8000
bash start.sh --stop   # Backend stoppen

Das Backend ist das Python-Paket openschichtplaner5-api (ASGI-Entrypoint sp5api.main:app), die Datenbankzugriffe übernimmt die libopenschichtplaner5 — beide werden über backend/requirements.txt installiert.

Manuell (Backend direkt):

SP5_DB_PATH=/pfad/zu/deinen/daten uvicorn sp5api.main:app --host 0.0.0.0 --port 8000

Die Anwendung ist dann erreichbar unter: http://localhost:8000

⚠️ Nur einen uvicorn-Worker verwenden: Sessions werden im Prozessspeicher gehalten und nicht zwischen Workern geteilt.

Für getrennten Backend-/Frontend-Dev-Betrieb (npm run dev), die make-Targets und die Drei-Repo-Co-Entwicklung via make dev-link siehe docs/DEVELOPMENT.md im Repository.

---

SP5_DB_PATH — Wo liegen die Daten?

Die Umgebungsvariable SP5_DB_PATH zeigt auf den Ordner mit den DBF-Dateien des Original-Schichtplaner5.

Umgebung	Default
Docker	/app/data (DBF-Dateien dorthin mounten)
Lokal	../sp5_db/Daten neben dem Repository; relative Pfade löst start.sh gegen das Repo-Root auf

Typische Pfade bei bestehender SP5-Installation:

• Windows: C:\SP5\Daten\ → im WSL: /mnt/c/SP5/Daten/
• Netzlaufwerk: /mnt/nas/SP5/Daten/
• Lokal kopiert: /home/user/sp5_daten/

So prüfst du, ob der Pfad stimmt:

ls $SP5_DB_PATH | grep "5EMPL"
# Ausgabe: 5EMPL.DBF  5EMPL.CDX

💡 Mehr zum Datenbankformat: Datenbankformat und das Library-Wiki.

---

Troubleshooting

❌ Container startet nicht / Import-Fehler

Das Image benötigt Python 3.12 (im offiziellen Image enthalten). Bei lokalen Builds sicherstellen, dass nicht ein veraltetes Basis-Image gecacht ist: docker build --pull.

❌ SP5_DB_PATH not set oder 5EMPL.DBF not found

Der Datenbankpfad fehlt oder ist falsch. Prüfe den Pfad mit ls $SP5_DB_PATH (lokal) bzw. das Volume-Mount nach /app/data (Docker).

❌ Login-Sessions brechen nach Neustart ab

SECRET_KEY ist nicht gesetzt — dann wird pro Prozess ein zufälliger Schlüssel verwendet und alle Sessions werden beim Neustart ungültig. SECRET_KEY in .env setzen (z. B. openssl rand -hex 32).

❌ Frontend zeigt "Cannot GET /"

Frontend wurde nicht gebaut (nur lokal relevant):

cd frontend && npm install && npm run build

❌ Port 8000 bereits belegt

fuser -k 8000/tcp   # Linux: Port freigeben
# oder anderen Port verwenden (Docker: -p 8001:8000)

❌ CDX-Fehler beim Schreiben

Die CDX-Indexdateien (z. B. 5EMPL.CDX) wurden manuell verändert oder sind beschädigt. Spiele ein Backup ein oder kopiere die Originaldateien zurück.

---

Updates einspielen

Docker:

docker compose pull && docker compose up -d

Lokal:

git pull origin main
bash start.sh          # installiert Abhängigkeiten neu und baut das Frontend

Beim ersten Start nach einem Update führt die Auto-Migration notwendige Schema-Anpassungen automatisch durch.

---

Weiter: Erste-Schritte — In 5 Minuten zum ersten Dienstplan