Loheide-eu-mitarbeiterplatt.../docs/INSTALLATION.md
Friederich Loheide 82bbeef31b
Some checks failed
CI / PHP 8.3 / mariadb:10.6 (pull_request) Successful in 2m7s
CI / PHP 8.4 / mariadb:10.6 (pull_request) Successful in 2m11s
CI / PHP 8.3 / mariadb:11.4 (pull_request) Successful in 2m16s
CI / PHP 8.4 / mariadb:11.4 (pull_request) Successful in 2m18s
CI / PHP 8.3 / mysql:8.0 (pull_request) Failing after 2m49s
CI / PHP 8.4 / mysql:8.0 (pull_request) Failing after 2m46s
CI / PHP 8.3 / mysql:8.4 (pull_request) Failing after 2m41s
CI / PHP 8.4 / mysql:8.4 (pull_request) Failing after 2m33s
CI / Build-Artefakte aktuell (pull_request) Successful in 1m0s
Phase 5: Erscheinungsbild mit Entwurf, Vorschau und Veröffentlichen
- Theme in den Einstellungen (Entwurf/veröffentlicht), Übernahme der
  Einstellungen aus Phase 0; statische CSS-Datei mit Hash beim Veröffentlichen
- Logos hell/dunkel, Signet, App-Symbol → Favicon, Homescreen-Symbole,
  Web-App-Manifest; SVG-Bereinigung
- Markenfarbe exakt, zweite Akzentfarbe, Kopfleiste hell/Marke/dunkel,
  Kontrastprüfung (WCAG AA) mit automatisch lesbarer Linkfarbe
- Lokale Schriften (Latein), Überschriften-Schrift, eigene WOFF2-Schrift,
  Ecken, Dichte, Dunkelmodus-Regel
- Anmeldeseite (geteilt/zentriert, Bild, Texte), Fußzeile, E-Mails im Design
- Admin: Live-Vorschau (Startseite, Anmeldung, Beispielseite; hell/dunkel),
  Veröffentlichen, Verwerfen, Export/Import, Zurücksetzen, eigenes CSS
- Admin-Bereich übernimmt Logo, Farbe und Favicon; Whitelabel

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

7.9 KiB
Raw Permalink Blame History

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 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.

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.