Erstinstallation¶
Schritt-für-Schritt-Anleitung für die erstmalige Einrichtung einer calServer v2-Instanz mit vollständiger Datenbank.
Voraussetzungen¶
- calServer v1 läuft bereits (
docker-compose.yml) - Docker >= 24.0, Docker Compose >= 2.20
- Datenbank: PostgreSQL 16 (Vorgabe); alternativ MySQL oder Microsoft SQL Server, siehe Systemanforderungen
.env-Datei ist konfiguriert (siehe Installation)
Schnellstart (ein Befehl)¶
Für die häufigste Variante — V1-kompatible Installation auf einer leeren Datenbank:
Dieser Befehl führt automatisch alle Schritte aus:
- Bestehende Tabellen löschen (
--clean) - Alle Migrationen ausführen
- Superadmin-Benutzer + RBAC-Berechtigungen erstellen
- System-Property-Defaults einspielen
- V1-Systemdaten laden (Feldkonfigurationen, Grid-Templates, Sprachen)
- V1-Kompatibilitätsprüfung durchführen
Schrittweise Installation¶
Wenn du mehr Kontrolle über den Prozess benötigst:
Schritt 1: Migrationen ausführen¶
Erstellt alle Datenbanktabellen. Die Migrationen sind kompatibel mit der bestehenden V1-Tabellenstruktur.
Schritt 2: System-Setup (RBAC + Superadmin)¶
Erstellt:
- Superadmin-Benutzer mit
hidden_super_admin-Rolle - RBAC-Gruppen (27 Gruppen wie
inventory_management,calibration_management, etc.) - RBAC-Operationen (~110 Berechtigungen wie
inventory_view,calibration_edit, etc.) - Verknüpfung aller Operationen mit der Superadmin-Rolle
Superadmin-Zugangsdaten
superadmin@calhelp.de |
|
| Passwort | (wird bei der Installation festgelegt) |
Das Passwort muss nach dem ersten Login geändert werden.
Schritt 3: System-Properties einspielen¶
Dieser Schritt ist in db:install enthalten. Bei manueller Installation:
Setzt Standard-Werte für Benutzer-, Kalibrierungs- und Kundeneinstellungen.
Schritt 4: V1-Systemdaten laden (optional)¶
Lädt V1-Systemkonfiguration aus SQL-Dateien:
- Sprachen
- Feldkonfigurationen
- Grid-Setting-Templates
- Grid-Sortierungs-Defaults
V1-Kompatibilität
Dieser Schritt ist notwendig, wenn die Instanz mit einer bestehenden V1-Installation zusammenarbeiten soll. Ohne diese Daten fehlen Feldkonfigurationen und Grid-Vorlagen.
Schritt 5: Berichtspakete importieren¶
Eine frische Anlage druckt nichts, bis Berichtsvorlagen importiert sind. Das ist kein Defekt: die Vorlagen werden in calServer-reports gepflegt und nicht im Anwendungs-Image mitgeliefert, damit es keine zweite Fassung davon gibt.
- Paket unter calhelp.github.io/calServer-reports/downloads herunterladen
- Unter Administration → Berichtsverwaltung hochladen
Die drei Systemberichte haben nach der Installation bereits eine Zeile und nennen dort das Paket, das hineingehört:
| Bericht | Referenz-Paket |
|---|---|
| Leihschein | LOCATION-JSON-SAMPLE |
| Preisliste | PRICE-LIST-JSON-SAMPLE |
| Auftragsdokument | ORDER-JSON-SAMPLE |
Für alles Weitere — Kalibrierschein voran — wird der Bericht in der Berichtsverwaltung angelegt und das Paket dazu hochgeladen. Neue Vorlagen sollten die JSON-Datenquelle nutzen statt eingebettetem SQL, siehe V2-Berichte mit JSON-Datenquelle.
Aus V1 mitgebrachte Vorlagen
Klassische V1-Pakete lesen die V1-Tabellen. Auf einer reinen V2-Datenbank
finden sie nichts; calServer bricht dann mit einer Meldung ab, statt ein
leeres PDF auszuliefern. Abhilfe ist die JSON-Fassung derselben Vorlage
(z. B. DAKKS-JSON-SAMPLE statt DAKKS-SAMPLE).
Demodaten einspielen¶
Für Test- und Demonstrationszwecke können Demodaten eingespielt werden:
Dies erstellt:
- 3 Testbenutzer mit verschiedenen Berechtigungsstufen
- Testkunden mit Prüfmitteln und Kalibrierungen
- Repräsentative Feldkonfigurationen
- Standorte, Reparaturen, Standards, Kontakte, Kategorien, Typen und weitere Testdaten
Testbenutzer¶
| Passwort | Rolle | |
|---|---|---|
admin@test.calserver.local |
test-admin-password |
Admin (alle Rechte) |
viewer@test.calserver.local |
test-viewer-password |
Nur-Lesen |
noapi@test.calserver.local |
test-noapi-password |
Kein API-Zugang |
Demodaten entfernen¶
Entfernt alle Testdaten sauber, ohne die Systemkonfiguration zu beeinträchtigen.
Verifikation¶
Automatische Verifikation (empfohlen)¶
Prüft automatisch:
- Alle V1-kritischen Tabellen existieren
- RBAC-Operationen und -Rollen vorhanden
- Property-Defaults gesetzt
translation_versionvorhanden (verhindert V1/update-Seite)- Superadmin-Benutzer existiert
- Gesamtanzahl Tabellen
Manuelle Prüfung¶
# Login-Funktion testen
docker exec calserver-api-v2 php artisan auth:diagnose superadmin@calhelp.de --password='<IHR-PASSWORT>'
Typische Szenarien¶
Frische Entwicklungsumgebung¶
# Datenbank komplett aufsetzen mit V1-Kompatibilität + Demodaten
docker exec calserver-api-v2 php artisan db:install --v1 --clean --force
docker exec calserver-api-v2 php artisan demo:data seed --force
Datenbank zurücksetzen¶
# Alles löschen und neu aufsetzen
docker exec calserver-api-v2 php artisan db:install --v1 --clean --force
Nur Migrationen aktualisieren (bestehende Daten behalten)¶
Tests lokal ausführen¶
cd laravel
composer fresh # Frische Test-DB mit TestDatabaseSeeder
composer test # Alle Tests parallel
Fehlerbehebung¶
Login funktioniert nicht¶
# Diagnose-Tool ausführen
docker exec calserver-api-v2 php artisan auth:diagnose user@example.com --password='Passwort'
Das Tool prüft Datenbankverbindung, Benutzerexistenz, Passwort-Hash-Typ und Verifikation.
V1 zeigt /update-Seite¶
Die translation_version-Property fehlt. Erneut ausführen:
RBAC-Fehler (403 bei API-Aufrufen)¶
Berechtigungen neu aufsetzen: