Loheide-eu-mitarbeiterplatt.../docs/INSTALLATION.md
Friederich Loheide b3a057e27c
All checks were successful
CI / PHP 8.3 / mariadb:10.6 (pull_request) Successful in 2m46s
CI / PHP 8.4 / mariadb:10.6 (pull_request) Successful in 2m51s
CI / PHP 8.3 / mariadb:11.4 (pull_request) Successful in 3m2s
CI / PHP 8.4 / mariadb:11.4 (pull_request) Successful in 2m55s
CI / PHP 8.3 / mysql:8.0 (pull_request) Successful in 4m15s
CI / PHP 8.4 / mysql:8.0 (pull_request) Successful in 4m16s
CI / PHP 8.4 / mysql:8.4 (pull_request) Successful in 3m44s
CI / PHP 8.3 / mysql:8.4 (pull_request) Successful in 3m46s
CI / Build-Artefakte aktuell (pull_request) Successful in 52s
Neues Modul: Qualitätsmanagement
- Kategorien mit farbigen Ordnerkacheln; Farbe und Symbol je Ordner
  (Auswahl oder eigener Upload, SVG bereinigt), an Unterordner vererbt
- Ordnerseite: Einführungstext, Ansprechpartner (Profilfelder wählbar),
  Unterordner, Liste mit Dokument, Version, Stand, Größe, Aktion
- Einträge: Datei (Lesefassung + bearbeitbare Vorlage), Link,
  Online-Formular; neue Fassungen archivieren die bisherigen
- PDF-Betrachter im Portal (pdf.js)
- Eigene Volltextsuche (PDF, Word, Excel, PowerPoint, OpenDocument)
  mit Textausschnitt; optionale Texterkennung per Tesseract
- Rollen-Ausschluss für das ganze Modul, Pflegerecht qm.manage,
  Zielgruppen je Kategorie
- Vorbereitet: Wiedervorlage, Verantwortliche, Lesebestätigungen
- Abhängigkeit smalot/pdfparser

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-26 15:50:23 +00:00

187 lines
10 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Installation und Betrieb
Diese Anleitung richtet sich an die IT bzw. an die Person, die das Portal beim
Hoster einrichtet. Shell-Zugang wird nicht benötigt.
## Voraussetzungen
- PHP **8.3** oder neuer mit den Erweiterungen `pdo_mysql`, `mbstring`,
`openssl`, `intl`, `gd`, `zip`, `fileinfo`, `tokenizer`, `ctype`, `xml`, `dom`
- **MySQL ab 8.0** oder **MariaDB ab 10.6** – eine leere Datenbank samt Benutzer
- Apache mit `mod_rewrite` (Einstellungen per `.htaccess` müssen erlaubt sein)
- Empfohlen: OPcache, `memory_limit` ≥ 128M, `upload_max_filesize` ≥ 8M, HTTPS
- Ausgehende HTTPS-Verbindungen zu `update.loheide.cloud` und
`api.loheide.cloud` (für Aktualisierungen und Rückmeldungen)
## Einrichtung
1. Das Installationsarchiv entpacken und **alle** Dateien per FTP/SFTP oder
Dateimanager in das gewünschte Verzeichnis hochladen.
2. Webroot festlegen:
- **Empfohlen:** Die Domain zeigt auf das Unterverzeichnis `public/`.
- Lässt der Hoster das nicht zu, zeigt die Domain auf das
Installationsverzeichnis – die mitgelieferte `.htaccess` leitet dann alle
Anfragen nach `public/` weiter.
3. Schreibrechte für den Webserver: `storage/`, `bootstrap/cache/`,
`public/uploads/` und – damit Aktualisierungen per Klick funktionieren – für
das gesamte Installationsverzeichnis.
4. Die Adresse des Portals im Browser aufrufen. Der Einrichtungsassistent führt
durch **Systemprüfung → Datenbank → Administrator**. Lizenz-E-Mail und
Lizenzschlüssel können dabei oder später eingetragen werden.
5. Mit dem Administratorkonto anmelden und unter **Administration →
Systemzustand** die Hinweise durchgehen.
> Solange die Einrichtung nicht abgeschlossen ist, kann jede Person, die die
> Adresse kennt, den Assistenten ausfüllen. Die Einrichtung daher direkt nach
> dem Hochladen abschließen.
## Anmeldung mit Microsoft Entra ID
1. Im [Microsoft Entra Admin Center](https://entra.microsoft.com) unter
**App-Registrierungen → Neue Registrierung** eine App anlegen
(„Nur Konten in diesem Organisationsverzeichnis“).
2. **Umleitungs-URI** (Plattform „Web“): die Adresse, die im Portal unter
**Administration → Anmeldung** angezeigt wird (`https://portal.firma.de/auth/entra/callback`).
3. **Zertifikate & Geheimnisse → Neuer geheimer Clientschlüssel** und den *Wert* notieren.
4. **API-Berechtigungen → Microsoft Graph:**
- delegiert: `User.Read`, `GroupMember.Read.All`
- für den Hintergrund-Abgleich zusätzlich als Anwendung: `User.Read.All`,
`GroupMember.Read.All`, `Application.Read.All` (nur für App-Rollen)
- danach **Administratorzustimmung erteilen**.
5. Im Portal unter **Administration → Anmeldung** Verzeichnis-ID,
Anwendungs-ID und Geheimnis eintragen, Gruppen den Rollen zuordnen und die
Anmeldung aktivieren. Mit **Mapping testen** lässt sich vorab prüfen,
welche Rollen eine Person erhalten wird.
### Entra-Attribute ins Profil übernehmen
Unter **Anmeldung → Profil** wird jedem Profilfeld ein Microsoft-Graph-Attribut
zugeordnet. Das geht nicht nur für die festen Felder (Name, Funktion, Abteilung,
Telefon …), sondern auch für eigene Felder, die unter **Benutzer & Rechte →
Profilfelder** angelegt werden – etwa Personalnummer, Kostenstelle oder
Eintrittsdatum. Übernommene Felder sind im Portal schreibgeschützt.
| Beispiel | Graph-Attribut |
| -------------------------------- | ---------------------------------------------------- |
| Personalnummer | `employeeId` |
| Kostenstelle | `employeeOrgData.costCenter` |
| Firma, Ort | `companyName`, `city` |
| lokales AD-Erweiterungsattribut | `onPremisesExtensionAttributes.extensionAttribute1` |
| eigene Verzeichniserweiterung | `extension_<AppId ohne Striche>_<Name>` |
Pfade mit Punkt lesen verschachtelte Werte, Listen werden mit Komma verbunden.
**Erweiterungsattribute laden** holt alle im Mandanten registrierten
Verzeichniserweiterungen (z. B. per Entra Connect synchronisierte AD-Attribute)
in die Auswahl; dafür braucht die App zusätzlich die Anwendungsberechtigung
`Directory.Read.All`. Einzelne Attribute verlangen eigene Berechtigungen – etwa
`employeeHireDate` die Berechtigung `User-LifeCycleInfo.Read.All`. Fehlt eine,
meldet sich die Person trotzdem an; übernommen werden dann nur die Grunddaten.
Die Anmeldung mit Passwort bleibt für Notfälle erhalten (z. B. wenn Entra ID
nicht erreichbar ist). Den geheimen Clientschlüssel vor Ablauf erneuern – er
ist bei Microsoft befristet.
## Weitere Anmeldeverfahren
Unter **Administration → Anmeldung → Anmeldeverfahren hinzufügen**. Jedes Verfahren ist
ein Plugin (unter „Plugins“ abschaltbar); mehrere Verfahren gleichzeitig sind möglich.
- **OpenID Connect**: Beim Anbieter einen vertraulichen Client anlegen, Weiterleitungs-URI
steht im Formular. Eingetragen wird nur die Issuer-URL – Endpunkte und Schlüssel kommen
aus dem Discovery-Dokument. Gruppen stehen je nach Anbieter in `groups`, `roles` oder
(Keycloak) `realm_access.roles`; ggf. den Scope `groups` ergänzen.
- **LDAP / Active Directory**: benötigt die PHP-Erweiterung `ldap` (beim Hoster
aktivieren lassen). Ein Dienstkonto mit Leserechten reicht. Die Verbindung sollte
LDAPS oder StartTLS nutzen. Gruppen werden als DN zugeordnet – „Verbindung testen“
zeigt die DNs einer Person. Als Kennung dient `objectGUID` (AD) bzw. `entryUUID`.
- **SAML 2**: Beim Anbieter die Metadaten-Adresse aus dem Formular eintragen
(`/auth/<kürzel>/metadata`) oder Entity-ID und ACS-URL von Hand. Die Assertion muss
signiert sein (SHA-256); Anmeldungen, die der Anbieter von sich aus startet, werden
aus Sicherheitsgründen nicht angenommen.
Nach der ersten Anmeldung zeigt das Formular unter „Zuletzt empfangene Angaben“, welche
Attribute und Gruppen der Anbieter liefert.
## Qualitätsmanagement: Texterkennung (optional)
Der Text von PDF-, Word-, Excel- und PowerPoint-Dateien wird ohne weitere Voraussetzungen
durchsuchbar gemacht. **Eingescannte PDFs** (Bilder ohne Textebene) brauchen eine
Texterkennung. Dafür gibt es kein Apache- oder PHP-Modul; das Portal ruft das Programm
**Tesseract** auf und wandelt PDF-Seiten mit `pdftoppm` (poppler-utils) oder PHP-Imagick in Bilder um.
Auf einem eigenen Server (Debian/Ubuntu):
apt install tesseract-ocr tesseract-ocr-deu poppler-utils
Dann unter **Administration → Qualitätsmanagement → QM-Einstellungen** die Texterkennung
einschalten. Die Seite zeigt, was der Server bereitstellt. Erkannt wird im Hintergrund
(Hintergrundaufgaben), einige Dateien je Durchgang. PHP muss Programme starten dürfen
(`proc_open` nicht in `disable_functions`). Auf Shared Hosting ist das meist nicht möglich –
eingescannte PDFs sind dort nur über Titel und Beschreibung auffindbar.
## Erscheinungsbild
Unter **Administration → Portal → Erscheinungsbild** lassen sich Name, Logos,
Farben, Schriften, Anmeldeseite, Fußzeile und E-Mails anpassen. Änderungen
werden zuerst als **Entwurf** gespeichert und sind nur in der Vorschau
sichtbar; für alle gelten sie erst nach **Veröffentlichen**. Über „Mehr“ lässt
sich das Erscheinungsbild als Datei exportieren und auf einem anderen System
(z. B. vom Test- auf das Produktivsystem) importieren.
Schriften werden immer vom eigenen Server ausgeliefert. Eine eigene Schrift
(WOFF2) darf nur hochgeladen werden, wenn ihre Lizenz die Nutzung im Web erlaubt.
## E-Mail-Versand
Unter **Administration → E-Mail-Versand** den SMTP-Zugang eintragen (vom
Hoster oder der IT, z. B. Microsoft 365: `smtp.office365.com`, Port 587,
STARTTLS) und mit **Test-Mail senden** prüfen. Das Passwort wird verschlüsselt
gespeichert. Gebraucht wird der Versand für „Passwort vergessen“ und
Formular-Benachrichtigungen. Mails werden über die Hintergrundaufgaben
verschickt – ohne Cron oder Web-Cron also mit etwas Verzögerung.
## Umstieg von WordPress
1. In WordPress unter **Werkzeuge → Daten exportieren** „Alle Inhalte“ wählen
und die XML-Datei herunterladen.
2. Im Portal unter **Administration → Inhalte → WordPress-Import** hochladen
und **Datei prüfen**.
3. Kategorien zuordnen (neu anlegen, vorhandene nutzen oder weglassen),
Autorinnen und Autoren prüfen (Zuordnung über die E-Mail-Adresse) und
entscheiden, ob Entwürfe und WordPress-Seiten mitkommen.
4. **Import starten** – die Seite geöffnet lassen, der Import läuft in Portionen.
Bilder werden von der alten Website geladen, sie muss dafür noch erreichbar
sein. Ein erneuter Import legt nichts doppelt an; auf Wunsch aktualisiert er
bereits übernommene Einträge. Kommentare, Schlagwörter und Inhalte anderer
WordPress-Plugins werden nicht übernommen. Nach dem Umstieg kann das Plugin
„WordPress-Import“ deaktiviert werden.
## Hintergrundaufgaben
Rückmeldungen, geplante Inhalte und Aufräumarbeiten laufen im Hintergrund. Die
genauen Angaben zeigt **Systemzustand** an.
- **Am besten:** Cronjob beim Hoster, jede Minute:
`cd /pfad/zum/portal && php artisan schedule:run`
- **Ohne Cron-Zugang:** die unter Systemzustand angezeigte geheime
Web-Cron-Adresse jede Minute von einem externen Cron-Dienst aufrufen lassen.
- **Ohne beides** laufen die Aufgaben beim Aufruf von Seiten mit – das
funktioniert, ist aber weniger zuverlässig.
## Aktualisierungen
Unter **Administration → Aktualisierung**: „Nach Updates suchen“ und „Jetzt
aktualisieren“. Das Portal zeigt währenddessen eine Wartungsseite, übernimmt
die neue Fassung, bringt die Datenbank auf den neuen Stand und ist nach
wenigen Minuten wieder erreichbar. `.env`, `storage/`, hochgeladene Dateien
und Plugins werden dabei nie verändert.
Voraussetzung ist eine gültige Lizenz. Ein Lizenzproblem schränkt die Nutzung
des Portals nicht ein – es verhindert nur den Bezug neuer Fassungen.
## Umzug auf einen anderen Server
Alle Dateien (inklusive `.env` und `storage/`) und die Datenbank übertragen.
Anschließend unter **Aktualisierung** die alte Installation abmelden bzw. die
Lizenz neu prüfen – jede Installation belegt einen Geräteplatz der Lizenz.