desktop/CopyToKeycloak/WAS_DU_TUN_MUSST.md

Was Du Tun Musst

1. Theme nach Keycloak kopieren

Den Ordner

• CopyToKeycloak/theme/kusche-desktop

in das Keycloak-Themes-Verzeichnis kopieren.

Typische Ziele:

• Container: /opt/keycloak/themes/
• VM/Bare Metal: <KEYCLOAK_HOME>/themes/

Danach muss dort existieren:

• /opt/keycloak/themes/kusche-desktop/login/theme.properties

2. Keycloak neu laden

Wenn du in Entwicklung arbeitest:

• Keycloak neu starten

Wenn du in Produktion Theme-Caches aktiv hast:

1. Keycloak stoppen oder neu starten
2. falls nötig Theme-Cache löschen:
   • data/tmp/kc-gzip-cache

3. Theme nur für den Desktop-Client setzen

In Keycloak:

1. Realm KuscheBerlin öffnen
2. Client desktop-kusche-berlin öffnen
3. Die Login-Theme-Override für den Client auf kusche-desktop setzen

Wichtig:

• Das Theme soll nicht pauschal als Realm-Login-Theme für alle Clients gesetzt werden, wenn andere Clients das Standard-Keycloak-Login behalten sollen.
• Wenn die Texte automatisch nach Browser-Sprache wechseln sollen:
  • im Realm unter Realm settings die Internationalisierung aktivieren
  • de und en als erlaubte Sprachen hinterlegen
  • optional de als Standard-Sprache setzen
• Wenn Passwort vergessen? sichtbar sein soll:
  • im Realm unter Login die Option Forgot password aktivieren
• Wenn Angemeldet bleiben sichtbar sein soll:
  • im Realm unter Login die Option Remember Me aktivieren
• Wenn ein Passwort-Reset auch wirklich ins angebundene LDAP zurückschreiben soll:
  • in der LDAP-User-Federation muss Passwort-Änderung erlaubt sein
  • das hängt von der Keycloak-LDAP-Konfiguration ab, nicht vom Theme selbst
  • falls LDAP nur read-only angebunden ist, kann Keycloak zwar den Reset-Flow anzeigen, aber das Passwort nicht ins LDAP zurückschreiben

Falls deine Keycloak-Version im Client-UI keine direkte Login-Theme-Auswahl anzeigt:

• prüfen, ob die Client-spezifische Login-Theme-Option in den Client-Einstellungen / Advanced Settings vorhanden ist
• falls nicht vorhanden, bleibt als saubere Alternative nur:
  • eigener Realm für Desktop
  • oder später ein Theme Selector SPI

4. Testen

Danach testen:

1. https://staging.desktop.kusche.berlin
2. https://desktop.kusche.berlin

Erwartung:

• für den Client desktop-kusche-berlin erscheint das neue Desktop-Login-Theme
• nach erfolgreichem Login geht es zur Desktop-Shell zurück

5. Falls das Theme nicht erscheint

Dann diese Punkte prüfen:

• Theme-Ordner liegt wirklich im Keycloak-themes/-Verzeichnis
• Verzeichnisname ist exakt kusche-desktop
• theme.properties liegt unter kusche-desktop/login/
• Keycloak wurde nach dem Kopieren neu gestartet
• Cache wurde geleert
• wirklich der Client desktop-kusche-berlin wird verwendet

6. Welche Datei du später bei Änderungen ersetzt

Wenn du nur Styling ändern willst, reicht meist:

• theme/kusche-desktop/login/resources/css/desktop-kusche.css

Wenn du die Struktur ändern willst:

• theme/kusche-desktop/login/login.ftl

7. Was ich bewusst nicht für dich serverseitig tue

Diese Schritte musst du selbst auf dem Keycloak-System machen:

• Dateien nach Keycloak kopieren
• Keycloak neu starten
• Client-Theme-Override setzen

Das Projekt hier erzeugt nur den fertigen Theme-Ordner.