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
- 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>
187 lines
10 KiB
Markdown
187 lines
10 KiB
Markdown
# 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.
|