# 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__` | 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//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.