Hostsharing Wiki - Benutzerbeiträge [de]

Prozessmanagement mit systemd im Userspace

2026-04-28T12:27:36Z

Tim00: /* systemd Unit begrenzen */

== Über systemd ==
''systemd'' ist seit einigen Jahren das Init-System aller gängigen Linux-Distributionen. Der ''init''-Prozess hat im laufenden System die Prozessnummer "1". Er verwaltet alle anderen Prozesse als Kind-Prozesse.

Auch ein normaler Account ohne besondere Privilegien kann systemd nutzen, um Prozesse im Userspace zu starten und zu kontrollieren. Auf der Hostsharing Managed Operations Platform kann jeder Account mit einer gültigen Login-Shell Dienste unter der Kontrolle von systemd starten.

Im Hostsharing Managed Webspace ist es zwingend, systemd als Prozessmonitor für eigene Serverdienste zu nutzen; auf einem Hostsharing Managed Server ist es die empfohlene Vorgehensweise ("Best practice").

== Eigene Serverdienste mit systemd ==

Die systemd-Konfiguration wird in dem Verzeichnis des Benutzers eingerichtet, unter dem die Anwendung laufen soll.
In diesem Beispiel soll die Anwendung GotoSocial unter der Benutzerkennung von ''xyz00-service'' laufen.
Nachdem die Anwendung im Benutzer ''xyz00-service'' installiert wurde, erfolgt nun die Konfiguration von systemd in demselben Benutzer.

Benutzer, die systemd steuern sollen, müssen über eine gültige Shell verfügen, so dass man sich per ''ssh'' oder vom Paketadmin mit dem Befehl ''sudo -i -u xyz00-service'' anmelden kann.
Die Umgebungsvariable ''XDG_RUNTIME_DIR'' sollte im Environment des Users gesetzt sein, wenn man erfolgreich angemeldet ist. Das testet man mit

<syntaxhighlight lang="bash">
echo $XDG_RUNTIME_DIR
</syntaxhighlight>

Die Ausgabe sollte sein:

<syntaxhighlight lang="bash">
xyz00-service@h01:~$ echo $XDG_RUNTIME_DIR
/run/user/112345
xyz00-service@h01:~$
</syntaxhighlight>

Dabei wird statt ''112345'' eine andere Zahl erscheinen. Diese Zahl ist die numerische User-Id des Users ''xyz00-service'' im System.

=== systemd Units ===

Die systemd-Units für einen User werden im Verzeichnis ''$HOME/.config/systemd/user/'' verwaltet. Dieser Pfad ist fest vorgegeben. Der Pfad muss bei einem neuen Benutzer angelegt werden.

<syntaxhighlight lang="bash">
mkdir -p $HOME/.config/systemd/user
</syntaxhighlight>

In diesem Verzeichnis wird für jeden Service eine Datei mit der Endung ''.service'' angelegt. In diesem Beispiel ist dies eine GotoSocial-Instanz. GotoSocial ist ein einfaches Binärprogramm, das in der Programmiersprache ''Go'' programmiert ist.

<syntaxhighlight lang="ini" line>
[Unit]
Description=GotoSocial Service
#After=my-redis.service

[Service]
Type=simple
WorkingDirectory=%h/gotosocial
Environment="PATH=/usr/local/bin:/usr/bin:/bin"
ExecStart=%h/gotosocial/gotosocial --config-path %h/gotosocial/config.yaml server start
StandardOutput=append:%h/var/gotosocial.log
StandardError=inherit
Restart=always
PrivateTmp=true

[Install]
WantedBy=default.target
</syntaxhighlight>

Folgende Eigenschaften sind einstellbar:

; After: Hier kann eingestellt werden, welcher Dienst bereits laufen muss, bevor dieser Dienst gestartet wird. Wenn GotoSocial eine Redis-Instanz benötigt, könnte das entsprechend eingestellt werden.
; Type=simple : ''simple'' ist die Voreinstellung und kann weggelassen werden. Evtl. braucht man auch ''forking'', wenn ein Dienst als Daemon im Hintergrund startet. Wenn man die Wahl hat, sollte man den Dienst immer im Vordergrund starten und nicht forken.
; WorkingDirectory : ist das Verzeichnis, in dem der Dienst gestartet wird. %h ist in dieser Datei eine Abkürzung für das Home-Verzeichnis des Users.
; Environment : Hier wird die Variable ''PATH'' definiert. Man kann mehrere Einträge des Namens ''Environment'' eintragen und bei Bedarf eine beliebige Anzahl von Environment-Variablen definieren.
; ExecStart : Das Programm, das als Dienst ausgeführt wird. Man kann eine komplette Kommandozeile angeben.
; StandardOutput : Eine Log-Datei, in die die Standardausgabe des laufenden Dienstes geschrieben wird.
; StandardError : Entsprechend zu ''StandardOutput''. Mit ''inherit'' wird die Datei von ''StandardOutput'' geerbt.
; Restart=always : Der Dienst soll grundsätzlich neu gestartet werden, wenn der Prozess unerwartet beendet wird.
; PrivateTmp=true : ''/tmp'' und ''/var/tmp'' werden temporär im Namespace gemountet, so dass sie nicht mit anderen Prozessen geteilt werden.
; WantedBy : sollte im Usermodus von systemd meistens ''default.target'' sein. Andere Targets sind z.B. ''base.target'' oder ''timers.target''. Für eine komplette Liste: <code>systemctl list-units --user --type=target</code>

==== RAM- und CPU-Limits ====

Auf Wunsch kann man die RAM- und CPU-Ressourcen für den Dienst begrenzen. Dazu trägt man weitere Eigenschaften im Abschnitt ''Service'' ein:

<syntaxhighlight lang="ini" line>
[Service]
...
MemoryAccounting=true
CPUAccounting=true
MemoryHigh=512M
MemoryMax=768M
CPUQuota=50%
</syntaxhighlight>

; MemoryHigh : Weiches RAM-Limit, das ggf. überschritten werden kann, wenn es unvermeidlich ist.
; MemoryMax : Hartes, absolutes RAM-Limit.
; CPUQuota : Maximale Belegung eines CPU-Threads in Prozent. Werte über 100% sind sinnvoll, wenn mehr als ein CPU-Thread verfügbar ist.

==== Ausführliche Dokumentation der Direktiven ====
Eine ausführliche Dokumentation der Direktiven findet sich hier:

https://www.freedesktop.org/software/systemd/man/latest/systemd.directives.html

=== systemd Unit starten und stoppen ===

Nachdem die systemd-Unit definiert ist, soll der Dienst gestartet werden.
Für die Verwaltung des Dienstes stehen die folgenden Kommandos zur Verfügung:

==== Reload ====

<syntaxhighlight lang="bash">
systemctl --user daemon-reload
</syntaxhighlight>

Die Konfigurationsdateien im Verzeichnis ''$HOME/.config/systemd/user/'' werden neu eingelesen. Dieses Kommando ist nach jeder Änderung einer ''.service''-Datei nötig.

==== Start und Stopp ====

<syntaxhighlight lang="bash">
systemctl --user start gotosocial.service
</syntaxhighlight>

bzw.

<syntaxhighlight lang="bash">
systemctl --user stop gotosocial.service
</syntaxhighlight>

sind die Kommandos zum Starten und Beenden des Dienstes.

==== Enable und Disable ====

Wenn ein Dienst nach einem Reboot des Servers automatisch gestartet werden soll, muss er aktiviert werden:

<syntaxhighlight lang="bash">
systemctl --user enable gotosocial.service
</syntaxhighlight>

Wenn er nicht automatisch nach einem Reboot starten soll, muss der Dienst entsprechend deaktiviert werden:

<syntaxhighlight lang="bash">
systemctl --user disable gotosocial.service
</syntaxhighlight>

sind die Kommandos, die den Dienst für einen Reboot des Servers aktivieren bzw. deaktivieren.

==== Status ====

<syntaxhighlight lang="bash">
systemctl --user status
</syntaxhighlight>

oder

<syntaxhighlight lang="bash">
systemctl --user status gotosocial.service
</syntaxhighlight>

zeigen den Status aller Dienste des Users bzw. eines bestimmten Dienstes an.

=== Ressourcen einer systemd Unit beschränken ===

Mit den folgenden Befehlen können die zur Verfügung stehenden Ressourcen einer systemd Unit beschränkt werden:

<syntaxhighlight lang="bash">
systemctl --user set-property gitea.service MemoryMax=500M
systemctl --user set-property gitea.service CPUQuota=25%
systemctl --user set-property gitea.service TasksMax=100
systemctl --user daemon-reload
</syntaxhighlight>

== Zeitgesteuerte Ausführung mit systemd ==

Mit Hilfe von systemd können auch wiederkehrende Aufgaben zeitgesteuert automatisiert werden.
Cronjobs, die früher für solche Zwecke benutzt wurden, lassen sich also durch systemd Units ersetzen.
Neben dem »service-file« wird dazu eine weitere Unit, nämlich ein »timer-file«, mit der Endung ».timer« angelegt und aktiviert.

=== Einrichten des »service-files« ===

<syntaxhighlight lang=bash line>
$ cat $HOME/.config/systemd/user/my-cleanup.service

[Unit]
Description=My Cleanup Service

[Service]
Type=oneshot
ExecStart=%h/bin/cleanup-script

ExecStopPost=/usr/local/bin/hs-notify-unit-failure %N %H %u $EXIT_CODE $SERVICE_RESULT %u
</syntaxhighlight>

Bemerkung: das Skript hs-notify-unit-failure schickt bei einem Fehler des Hauptskripts eine E-Mail an den aktuellen Benutzer, die über .forward oder über .procmailrc auch an eine andere E-Mail Adresse weitergeleitet werden kann.

=== Testen ===

<syntaxhighlight lang=bash>
$ systemctl --user start my-cleanup.service
</syntaxhighlight>

=== Einrichten des »timer-files« ===

<syntaxhighlight lang=bash>
$ cat $HOME/.config/systemd/user/my-cleanup.timer

[Unit]
Description=Daily My Cleanup Timer

[Timer]
OnCalendar=daily
RandomizedDelaySec=3600
Persistent=true

[Install]
WantedBy=timers.target
</syntaxhighlight>

Der RandomizedDelay bewirkt, dass der Prozess zufällig im Zeitraum einer Stunde gestartet wird.
Wenn mehrere Timer-Aufgaben täglich (daily) auf einem System gestartet werden, verhindert diese Einstellung, dass alle Prozesse exakt zur gleichen Zeit starten und das System eventuell überlasten.

Die zufällige Verzögerung sollte in einem sinnvollen Verhältnis zur Frequenz der Zeitsteuerung erfolgen.
Bei täglich ausgeführten Aufgaben mag eine Stunde (3600 Sekunden) sinnvoll sein.
Bei Aufgaben, die stündlich ausgeführt werden, wählt man eine kürzere Verzögerung, zum Beispiel fünf Minuten.

Die Syntax der Datei lässt sich mit diesem Befehl prüfen:

<syntaxhighlight lang=bash>
systemd-analyze verify $HOME/.config/systemd/user/my-cleanup.timer
</syntaxhighlight>

Einzelne Kalendereinträge lassen sich mit Erklärung ausgeben:

<syntaxhighlight lang=bash>
systemd-analyze calendar '*:0/2'
</syntaxhighlight>

Eine ausführliche Dokumentation der Direktiven findet sich hier:

https://www.freedesktop.org/software/systemd/man/latest/systemd.timer.html

=== Aktivieren der zeitgesteuerten Ausführung ===

Der Timer muss noch aktiviert und gestartet werden:

<syntaxhighlight lang=bash>
$ systemctl --user enable my-cleanup.timer --now
</syntaxhighlight>

=== Übersicht über die Timer im aktuellen User ===

<syntaxhighlight lang=bash>
$ systemctl --user list-timers --all
</syntaxhighlight>

== RAM Kontingent eines Webspace ==

Den aktuell belegten RAM eines Webspace ''xyz00'' kann man sich mit dem Befehl

<syntaxhighlight lang="bash">
systemctl status pacs-xyz00.slice
</syntaxhighlight>

ansehen.

Etwa in der fünften Zeile der Ausgabe findet man eine Angabe der Form:

<syntaxhighlight lang="bash">
Memory: 58.4M (max: 14.8G available: 14.8G)
</syntaxhighlight>

Hier sind aktuell 58,4 Megabyte RAM genutzt, es sind 14,8 Gigabyte RAM für den Webspace verfügbar. Der verfügbare RAM ist das gebuchte Kontingent. Das gebuchte Kontigent wird im Shared Hosting deutlich kleiner sein.

Das RAM Kontingent wird in Schritten von jeweils 128 Ḿegabyte gebucht. Änderungen des RAM Kontingents für einen Webspace nimmt der Service unter [mailto:service@hostsharing.net service@hostsharing.net] entgegen, wie es bei anderen Paketoptionen die Vorgehensweise ist.

== Beliebte Fehler ==
=== Fehler: Failed to connect to bus: No such file or directory ===

Wenn ich einen systemctl Befehl ausführe, kommt:

<syntaxhighlight lang="bash">
systemctl --user daemon-reload
Failed to connect to bus: No such file or directory
</syntaxhighlight>

Bitte prüfen, ob Lingering für den Benutzer aktiviert ist. Dazu muss im Hsadmin beim Benutzer die Login Shell <code>/bin/bash</code> eingetragen sein. Falls das bereits der Fall ist, ist es vielleicht ein sehr alter Benutzer. Dann bitte kurz auf <code>/usr/bin/passwd</code> stellen, und dann wieder auf <code>/bin/bash</code> zurückstellen.

Evtl. hilft es auch, die Umgebungsvariable XDG_RUNTIME_DIR zu setzen:

<syntaxhighlight lang="bash">
export XDG_RUNTIME_DIR=/run/user/$UID
</syntaxhighlight>

Das kann auch in die Datei <code>$HOME/.profile</code> eingefügt werden.

=== Fehler: Beim Starten passiert nichts ===

Ich hatte das Problem bei einem Redis Dienst. Er stoppte innerhalb von Millisekunden. In der Log Datei stand nichts.

Ursache: in der Service Datei war bei <code>WorkingDirectory</code> ein nicht existierendes Verzeichnis eingetragen.

= weiterführende Links =

* https://www.freedesktop.org/software/systemd/man/latest/systemd.directives.html
* https://www.freedesktop.org/software/systemd/man/latest/systemd.timer.html
* https://documentation.suse.com/smart/systems-management/html/systemd-working-with-timers/index.html#systemd-timer-catchup
* https://wiki.archlinux.org/title/Systemd/Timers#As_a_cron_replacement

----
[[Kategorie:systemd]]
[[Kategorie:Eigene Daemons]]

Speicherbelegung

2026-04-28T06:47:32Z

Tim00: /* Speicherbelegung von einzelnen Benutzern prüfen */

== Paketspeicher ==

Der im gesamten Paket zur Verfügung stehende bzw genutzte Speicher kann wie folgt abgefragt werden:

Einloggen als Paketadmin

{{Textkasten|gruen||xyz00@h01:~$ pac-du-quota}}
Es wird der Speicherplatz (NVMe SSD) und der Zusatz-Speicherplatz (HDD) angezeigt.

oder

{{Textkasten|gruen||xyz00@h01:~$ quota -gs}}
(g > wir nutzen Gruppenquota, s > für Ausgabe in MB). Die Felder bedeuten:

{| class="wikitable" style="margin: 0em 0em 0em 2em; font-size:1em;"
|- style="background-color:orange;"
!Feld !! Bedeutung
|- style="background-color:#CAE1FF;"
|blocks || KB belegt
|- style="background-color:#B9D3EE;"
|quota || normales (gebuchtes) Limit in KB; "soft quota"
|- style="background-color:#CAE1FF;"
|limit || maximales (temporär toleriertes) Limit in KB; "hard quota"
|- style="background-color:#B9D3EE;"
|grace || Anzahl der Tage, die man noch über "quota" bleiben darf (ist nur gesetzt, wenn blocks>quota)
|- style="background-color:#CAE1FF;"
|files ||Anzahl der INodes (entspricht nicht immer, aber fast einem File. Lediglich Hardlinks verbrauchen nur einen INode pro "realer" Datei)
|- style="background-color:#B9D3EE;"
|quota ||normales Limit der INode-Anzahl
|- style="background-color:#CAE1FF;"
|limit ||maximales Limit der INode-Anzahl
|- style="background-color:#B9D3EE;"
|grace || Anzahl der Tage, die man noch über "INode-quota" bleiben darf (ist nur gesetzt, wenn quota überschritten ist)
|-
|}

Um zu prüfen, ob ein Paket die Quota bald erreicht oder schon überschritten hat, muss man '''blocks''' mit '''quota''' in Verhältnis setzen. Wenn '''blocks > quota''', beginnt die ''grace period'', während der ein weiterer Anstieg des Speicherverbrauchs noch toleriert wird. In jedem Fall gilt '''blocks < limit''': die "hard quota" kann nicht überschritten werden und liegt z.B. bei 150% der "soft quota".

Der genutzte Speicher nur für den Paketadmin selbst kann mit '''du''' abgefragt werden: Einloggen als Paket-Admin und '''du -h''' eingeben. Der Befehl listet die aktuellen Größen der einzelnen Verzeichnisse auf und am Ende den gesamt belegten Plattenplatz in MB.

{{Textkasten|gruen||'''Achtung:''' Die Auflistung (mit '''du''') erfolgt ohne den Speicherplatz der User, für deren Verzeichnisse der Paketadmin kein Zugriffsrecht hat, ohne Dateien in /tmp/ und ohne Datenbanken!}}

An dieser Stelle unser Danke an die Mitglieder Andreas Loesch und Timotheus Pokorra die das hervorragende Skript 'pac-du-quota' bereit gestellt haben.

== Unvermutete Speicherbelegung ==

Manchmal wunderst du dich, welche Dateien deinen Speicherplatz belegen?

du und pac-du-quota zeigen nur die Dateien im Home Verzeichnis.

Manche Anwendungen legen im /tmp Verzeichnis für deinen Benutzer Dateien an.

Diese Dateien findest du mit diesem Befehl, für deinen aktuellen Benutzer:

<syntaxhighlight lang=shell>
xyz00-meinbenutzer@hxy:~$ find /tmp/user/$UID
xyz00-meinbenutzer@hxy:~$ ls -la /tmp
</syntaxhighlight>

== Warnung bei Erreichen des Quotas ==

=== Warnungen beim Paketspeicher ===

Wenn die Speicherbelegung (Soft- oder Hard-Quota) beim Paketspeicher überschritten wird, bekommen die dafür eingetragenen E-Mail-Adressen (siehe Ansprechpartner, OPERATIONS_ALERT) jeden Morgen eine E-Mail mit einem Warn-Hinweis.

=== Speicherbelegung von einzelnen Benutzern prüfen ===

Diese automatische E-Mail berücksichtigt nicht die Quotas der einzelnen Benutzer/Postfächer.

Dafür kann das folgende Python-Skript genutzt werden: https://codeberg.org/tpokorra/hostsharing-scripts/src/branch/main/check-userquota.py

Es sollte im bin Verzeichnis des Paketnutzers (/home/pacs/xyz00/bin) gespeichert werden.

Es muss mit einem Timer eingerichtet werden:

<syntaxhighlight lang=shell>
xyz00@h00:~$ cat .config/systemd/user/check-userquota.timer
[Unit]
Description=check user quota

[Timer]
OnCalendar=00:55:00
RandomizedDelaySec=3 minutes
Persistent=true

[Install]
WantedBy=timers.target

xyz00@h00:~$ cat .config/systemd/user/check-userquota.service
[Unit]
Description=check user quotas

[Service]
Environment="MAILTO=monitoring@meinedomain.de"
ExecStart=%h/bin/check-userquota.py
</syntaxhighlight>

Aktivieren des Timers mit:

<syntaxhighlight lang=shell>
systemctl --user enable check-userquota.timer --now
</syntaxhighlight>

----
[[Kategorie:Pakete bei HS]]
[[Kategorie:HSDoku]]

Speicherbelegung

2026-04-28T06:37:23Z

Tim00: Warn-Emails bei Speicherüberschreitung

== Paketspeicher ==

Der im gesamten Paket zur Verfügung stehende bzw genutzte Speicher kann wie folgt abgefragt werden:

Einloggen als Paketadmin

{{Textkasten|gruen||xyz00@h01:~$ pac-du-quota}}
Es wird der Speicherplatz (NVMe SSD) und der Zusatz-Speicherplatz (HDD) angezeigt.

oder

{{Textkasten|gruen||xyz00@h01:~$ quota -gs}}
(g > wir nutzen Gruppenquota, s > für Ausgabe in MB). Die Felder bedeuten:

{| class="wikitable" style="margin: 0em 0em 0em 2em; font-size:1em;"
|- style="background-color:orange;"
!Feld !! Bedeutung
|- style="background-color:#CAE1FF;"
|blocks || KB belegt
|- style="background-color:#B9D3EE;"
|quota || normales (gebuchtes) Limit in KB; "soft quota"
|- style="background-color:#CAE1FF;"
|limit || maximales (temporär toleriertes) Limit in KB; "hard quota"
|- style="background-color:#B9D3EE;"
|grace || Anzahl der Tage, die man noch über "quota" bleiben darf (ist nur gesetzt, wenn blocks>quota)
|- style="background-color:#CAE1FF;"
|files ||Anzahl der INodes (entspricht nicht immer, aber fast einem File. Lediglich Hardlinks verbrauchen nur einen INode pro "realer" Datei)
|- style="background-color:#B9D3EE;"
|quota ||normales Limit der INode-Anzahl
|- style="background-color:#CAE1FF;"
|limit ||maximales Limit der INode-Anzahl
|- style="background-color:#B9D3EE;"
|grace || Anzahl der Tage, die man noch über "INode-quota" bleiben darf (ist nur gesetzt, wenn quota überschritten ist)
|-
|}

Um zu prüfen, ob ein Paket die Quota bald erreicht oder schon überschritten hat, muss man '''blocks''' mit '''quota''' in Verhältnis setzen. Wenn '''blocks > quota''', beginnt die ''grace period'', während der ein weiterer Anstieg des Speicherverbrauchs noch toleriert wird. In jedem Fall gilt '''blocks < limit''': die "hard quota" kann nicht überschritten werden und liegt z.B. bei 150% der "soft quota".

Der genutzte Speicher nur für den Paketadmin selbst kann mit '''du''' abgefragt werden: Einloggen als Paket-Admin und '''du -h''' eingeben. Der Befehl listet die aktuellen Größen der einzelnen Verzeichnisse auf und am Ende den gesamt belegten Plattenplatz in MB.

{{Textkasten|gruen||'''Achtung:''' Die Auflistung (mit '''du''') erfolgt ohne den Speicherplatz der User, für deren Verzeichnisse der Paketadmin kein Zugriffsrecht hat, ohne Dateien in /tmp/ und ohne Datenbanken!}}

An dieser Stelle unser Danke an die Mitglieder Andreas Loesch und Timotheus Pokorra die das hervorragende Skript 'pac-du-quota' bereit gestellt haben.

== Unvermutete Speicherbelegung ==

Manchmal wunderst du dich, welche Dateien deinen Speicherplatz belegen?

du und pac-du-quota zeigen nur die Dateien im Home Verzeichnis.

Manche Anwendungen legen im /tmp Verzeichnis für deinen Benutzer Dateien an.

Diese Dateien findest du mit diesem Befehl, für deinen aktuellen Benutzer:

<syntaxhighlight lang=shell>
xyz00-meinbenutzer@hxy:~$ find /tmp/user/$UID
xyz00-meinbenutzer@hxy:~$ ls -la /tmp
</syntaxhighlight>

== Warnung bei Erreichen des Quotas ==

=== Warnungen beim Paketspeicher ===

Wenn die Speicherbelegung (Soft- oder Hard-Quota) beim Paketspeicher überschritten wird, bekommen die dafür eingetragenen E-Mail-Adressen (siehe Ansprechpartner, OPERATIONS_ALERT) jeden Morgen eine E-Mail mit einem Warn-Hinweis.

=== Speicherbelegung von einzelnen Benutzern prüfen ===

Diese automatische E-Mail berücksichtigt nicht die Quotas der einzelnen Benutzer/Postfächer.

Dafür kann das folgende Python-Skript genutzt werden: https://codeberg.org/tpokorra/hostsharing-scripts/src/branch/main/check-userquota.py

Es sollte im bin Verzeichnis des Paketnutzers (/home/pacs/xyz00/bin) gespeichert werden.

Es muss mit einem Timer eingerichtet werden:

<syntaxhighlight lang=shell>
xyz00@h00:~$ cat .config/systemd/user/check-userquota.timer
[Unit]
Description=check user quota

[Timer]
OnCalendar=00:55:00
RandomizedDelaySec=3 minutes
Persistent=true

[Install]
WantedBy=timers.target

xyz00@h00:~$ cat .config/systemd/user/check-userquota.service
[Unit]
Description=check user quotas

[Service]
Environment="MAILTO=monitoring@meinedomain.de"
ExecStart=%h/bin/check-userquota.py
</syntaxhighlight>

Aktivieren des Timers mit:

<syntaxhighlight lang=shell>
systemctl --user enable check-userquota --now
</syntaxhighlight>

----
[[Kategorie:Pakete bei HS]]
[[Kategorie:HSDoku]]

Speicherbelegung

2026-04-28T06:31:49Z

Tim00: Warn-Emails bei Speicherüberschreitung

== Paketspeicher ==

Der im gesamten Paket zur Verfügung stehende bzw genutzte Speicher kann wie folgt abgefragt werden:

Einloggen als Paketadmin

{{Textkasten|gruen||xyz00@h01:~$ pac-du-quota}}
Es wird der Speicherplatz (NVMe SSD) und der Zusatz-Speicherplatz (HDD) angezeigt.

oder

{{Textkasten|gruen||xyz00@h01:~$ quota -gs}}
(g > wir nutzen Gruppenquota, s > für Ausgabe in MB). Die Felder bedeuten:

{| class="wikitable" style="margin: 0em 0em 0em 2em; font-size:1em;"
|- style="background-color:orange;"
!Feld !! Bedeutung
|- style="background-color:#CAE1FF;"
|blocks || KB belegt
|- style="background-color:#B9D3EE;"
|quota || normales (gebuchtes) Limit in KB; "soft quota"
|- style="background-color:#CAE1FF;"
|limit || maximales (temporär toleriertes) Limit in KB; "hard quota"
|- style="background-color:#B9D3EE;"
|grace || Anzahl der Tage, die man noch über "quota" bleiben darf (ist nur gesetzt, wenn blocks>quota)
|- style="background-color:#CAE1FF;"
|files ||Anzahl der INodes (entspricht nicht immer, aber fast einem File. Lediglich Hardlinks verbrauchen nur einen INode pro "realer" Datei)
|- style="background-color:#B9D3EE;"
|quota ||normales Limit der INode-Anzahl
|- style="background-color:#CAE1FF;"
|limit ||maximales Limit der INode-Anzahl
|- style="background-color:#B9D3EE;"
|grace || Anzahl der Tage, die man noch über "INode-quota" bleiben darf (ist nur gesetzt, wenn quota überschritten ist)
|-
|}

Um zu prüfen, ob ein Paket die Quota bald erreicht oder schon überschritten hat, muss man '''blocks''' mit '''quota''' in Verhältnis setzen. Wenn '''blocks > quota''', beginnt die ''grace period'', während der ein weiterer Anstieg des Speicherverbrauchs noch toleriert wird. In jedem Fall gilt '''blocks < limit''': die "hard quota" kann nicht überschritten werden und liegt z.B. bei 150% der "soft quota".

Der genutzte Speicher nur für den Paketadmin selbst kann mit '''du''' abgefragt werden: Einloggen als Paket-Admin und '''du -h''' eingeben. Der Befehl listet die aktuellen Größen der einzelnen Verzeichnisse auf und am Ende den gesamt belegten Plattenplatz in MB.

{{Textkasten|gruen||'''Achtung:''' Die Auflistung (mit '''du''') erfolgt ohne den Speicherplatz der User, für deren Verzeichnisse der Paketadmin kein Zugriffsrecht hat, ohne Dateien in /tmp/ und ohne Datenbanken!}}

An dieser Stelle unser Danke an die Mitglieder Andreas Loesch und Timotheus Pokorra die das hervorragende Skript 'pac-du-quota' bereit gestellt haben.

== Unvermutete Speicherbelegung ==

Manchmal wunderst du dich, welche Dateien deinen Speicherplatz belegen?

du und pac-du-quota zeigen nur die Dateien im Home Verzeichnis.

Manche Anwendungen legen im /tmp Verzeichnis für deinen Benutzer Dateien an.

Diese Dateien findest du mit diesem Befehl, für deinen aktuellen Benutzer:

<syntaxhighlight lang=shell>
xyz00-meinbenutzer@hxy:~$ find /tmp/user/$UID
xyz00-meinbenutzer@hxy:~$ ls -la /tmp
</syntaxhighlight>

== Warnung bei Erreichen des Quotas ==

== Warnungen beim Paketspeicher ==

Wenn die Speicherbelegung (Soft- oder Hard-Quota) beim Paketspeicher überschritten wird, bekommen die dafür eingetragenen E-Mail-Adressen jeden Morgen eine E-Mail mit einem Warn-Hinweis.

== Speicherbelegung von einzelnen Benutzern prüfen ==

Diese automatische E-Mail berücksichtigt nicht die Quotas der einzelnen Benutzer/Postfächer.

Dafür kann das folgende Python-Skript genutzt werden: https://codeberg.org/tpokorra/hostsharing-scripts/src/branch/main/check-userquota.py

Es sollte im bin Verzeichnis des Paketnutzers (/home/pacs/xyz00/bin) gespeichert werden.

Es muss mit einem Timer eingerichtet werden:

<syntaxhighlight lang=shell>
xyz00@h00:~$ cat .config/systemd/user/check-userquota.timer
[Unit]
Description=check user quota

[Timer]
OnCalendar=00:55:00
RandomizedDelaySec=3 minutes
Persistent=true

[Install]
WantedBy=timers.target

xyz00@h00:~$ cat .config/systemd/user/check-userquota.service
[Unit]
Description=check user quotas

[Service]
Environment="MAILTO=monitoring@meinedomain.de"
ExecStart=%h/bin/check-userquota.py
</syntaxhighlight>

Aktivieren des Timers mit:

<syntaxhighlight lang=shell>
systemctl --user enable check-userquota --now
</syntaxhighlight>

----
[[Kategorie:Pakete bei HS]]
[[Kategorie:HSDoku]]

Nextcloud

2026-04-27T08:18:03Z

Tim00: /* weiterführende Links */ kaputten Link ersetzt

= Nextcloud =

[https://nextcloud.com/ Nextcloud] ist eine PHP-basierte Open Source Lösung für gängige Cloud-Anwendungen, u.a.:

* Filesharing unter Nutzern derselben Nextcloud, und mit der Öffentlichkeit
* Single-Sign-On Authentifizierung (SSO)
* Videokonferenzen (WebRTC)
* Online-Office Anwendung [https://www.collaboraoffice.com/ Collabora Online]

Beispiel-Funktionalität, die über Plugins, sogenannte [https://apps.nextcloud.com/ "Apps"], bereit gestellt werden kann:

* Kalender, Aufgabenverwaltung, Adressbuch
* Datei-Kollaboration (Kommentare zu Dateien, Verschlagwortung)
* Feedreader
* E-Mail-Programm
* Fotogalerie
* Musik- und Videowiedergabe

= Nextcloud installieren =

== Vorbereitungen ==

In ''hsadmin'', zum Beispiel mit ''hsscript'':

''hsadmin''-Shell starten mit:

<syntaxhighlight lang=shell>
hsscript -u xyz00 -i
Password: ********
</syntaxhighlight>

Dann nacheinander anlegen:

* Linux User als Domain-Administrator
* Subdomain ''cloud.example.org''
* PostgreSQL-User
* PostgreSQL Datenbank

<syntaxhighlight lang=shell>
xyz00@hsadmin> user.add({set:{name:'xyz00-cloud',password:'geheim',shell:'/bin/bash',comment:'Nextcloud'}})
xyz00@hsadmin> domain.add({set:{name:'cloud.example.org',user:'xyz00-cloud'}})
xyz00@hsadmin> postgresqluser.add({set:{name:'xyz00_nextclusr',password:'geheim'}})
xyz00@hsadmin> postgresqldb.add({set:{name:'xyz00_nextcloud',owner:'xyz00_nextclusr'}})
</syntaxhighlight>

== Nextcloud installieren ==

Anmelden als Linux-User ''xyz00-cloud'':

<syntaxhighlight lang=shell>
ssh -l xyz00-cloud xyz00.hostsharing.net
</syntaxhighlight>

''htdocs'' Verzeichnis vorbereiten

<syntaxhighlight lang=shell>
cd
mkdir nextcloud
cd doms/cloud.example.org
rm -rf subs/www subs-ssl/www htdocs-ssl
ln -s $HOME/nextcloud htdocs-ssl
</syntaxhighlight>

Falls der ''Redirect'' auf die Domain ''example.org'' umleitet statt auf die Subdomain ''cloud.example.org'', kann diese Aktion helfen:

<syntaxhighlight lang=shell>
cd doms/cloud.example.org
mkdir -p subs-ssl/www
cp htdocs/.htaccess subs-ssl/www/.htaccess
</syntaxhighlight>

Nextcloud herunterladen und entpacken.

<syntaxhighlight lang=shell>
cd
wget https://download.nextcloud.com/server/releases/nextcloud-30.0.6.zip
unzip nextcloud-30.0.6.zip
rm nextcloud-30.0.6.zip
mkdir data tmp
chmod 700 data tmp
</syntaxhighlight>

Um Probleme mit der Anmeldung der Nextcloud App am Mobilgerät zu vermeiden, müssen folgende Zeilen in der Datei <code>doms/cloud.example.org/.htaccess</code> eingefügt werden:

<syntaxhighlight lang=htaccess>
RewriteEngine On
RewriteCond %{HTTP:Authorization} ^(.*)
RewriteRule .* - [e=HTTP_AUTHORIZATION:%1]
</syntaxhighlight>

== Nextcloud konfigurieren ==

Im Verzeichnis "$HOME/doms/cloud.example.org/fastcgi-ssl/" eine Datei "php.ini" anlegen mit folgendem Inhalt:

<syntaxhighlight lang=ini>
memory_limit=512M
session.save_path=/home/pacs/xyz00/users/cloud/tmp
</syntaxhighlight>

Dann mit einem Editor diese Datei bearbeiten: In der zweiten Zeile den korrekten Pfad des vorher angelegten tmp-Verzeichnisses eintragen.

Im Browser auf die Seite
http://cloud.example.org gehen und den Anweisungen folgen.

Auf der ersten Seite sind anzugeben:

* Login und Passwort für den Administrator definieren
* PostgreSQL als Datenbanksystem
* PostgreSQL-User und Passwort aus dem ersten Schritt oben
* Name der PostgreSQL-Datenbank aus dem ersten Schritt
* "localhost" als Datenbankserver (Nextcloud 23.0.2 empfiehlt hier die Angabe des Ports, diesen also lt. [[PostgreSQL]] angeben)
* Das Verzeichnis "/home/pacs/xyz00/users/cloud/data/" als Daten-Verzeichnis (bitte beachten: das im Eingabefeld voreingestellte verweist auf das Verzeichnis "/home/pacs/xyz00/users/cloud/'''nextcloud'''/data/")

'''Achtung!''' Die Felder für die Datenbank sind auf dem Startscreen hinter einem unscheinbaren Link versteckt. Um man das Formular für die Datenbank-Daten zu gelangen, muss man auf den Link klicken. Anschließend kann man die gewünschte Datenbank auswählen und die entsprechenden Daten eintragen. '''Das sollte geschehen, bevor man die Installation abschließt!''' Tut man dies nicht, wird Nextcloud mit SQLite installiert. Eine Änderung der Datenbank soll zwar laut Dokumentation auch später noch möglich sein, ging aber bei einem Test schief.

In der Konfigurationsdatei der Nextcloud (in ''~/nextcloud/config/config.php'') lassen sich weitere Voreinstellungen treffen:

<syntaxhighlight lang=php line>
'maintenance_window_start' => 1, // Wartungsfenster ab 1:00 Uhr
'defaultapp' => 'calendar,files', // bei Start wird der Kalender gezeigt
'default_phone_region' => 'DE', // Format Telefonnummern
'default_language' => 'de', // Sprache deutsch
'force_language' => 'de',
'default_locale' => 'de_DE', // Locale (Formatierung Zeitangaben etc.)
'force_locale' => 'de_DE',
</syntaxhighlight>

== Nextcloud beschleunigen ==

Dieser Teil ist optional.

Wenn regelmäßig '''im Browser''' mit Nextcloud gearbeitet werden soll, ist Nextcloud im Browser oft sehr langsam. Um dies zu verbessern, unterstützt Nextcloud die Anwendung von unterschiedlichen Cache-Verfahren (zum Beispiel Memcache, Redis).

=== Redis Cache ===

Redis ist auf den Hostsharing-Servern vorinstalliert und wird von den Nextcloud-Entwicklern empfohlen. Redis wird als eigener Serverdienst gestartet. '''In Verbindung mit Hostsharing Managed Webspace muss für Redis [https://www.hostsharing.net/paas/managed-webspace/ Arbeitsspeicher für eigene Serverdienste] gebucht werden'''.

Die Konfiguration des Redis-Dientes ist auf der Seite [[Redis]] beschrieben. Hier wird für Nextcloud die Variante mit einem Unixsocket benutzt.

In der Konfiguration der Nextcloud (in ''~/nextcloud/config/config.php'') wird der Redis-Cache wie folgt konfiguriert:

<syntaxhighlight lang=php line>
'memcache.local' => '\\OC\\Memcache\\Redis',
'memcache.distributed' => '\\OC\\Memcache\\Redis',
'memcache.locking' => '\\OC\\Memcache\\Redis',
'redis' =>
array (
'host' => '/home/pacs/xyz00/users/cloud/redis/var/redis-server.sock',
'port' => 0,
'password' => 'mein-redis-passwort',
'timeout' => 1.5,
),
</syntaxhighlight>

Um es perfekt zu machen, nutze ich ''logrotate'' um die Logdateien zu organisieren. Dazu die Konfiguration in ''~/.logrotate''

<syntaxhighlight lang=shell line>
compress
/home/pacs/xyz00/users/cloud/redis/var/redis.log {
rotate 5
daily
missingok
}
</syntaxhighlight>
Mit systemd-Timern werden die Logdateien täglich rotiert:

''~/.config/systemd/user/logrotate.service''
<syntaxhighlight lang=ini line>
[Unit]
Description=rotate log files

[Service]
Type=oneshot
ExecStart=/usr/sbin/logrotate -s %h/.logrotate.state %h/.logrotate
</syntaxhighlight>

''~/.config/systemd/user/logrotate.timer''
<syntaxhighlight lang=ini line>
[Unit]
Description=timer for nextcloud cleanup job

[Timer]
OnCalendar=1:1
Persistent=True

[Install]
WantedBy=timers.target
</syntaxhighlight>

Den Timer aktivieren und starten:
<syntaxhighlight lang=shell line>
$ systemctl --user enable logrotate.timer
$ systemctl --user start logrotate.timer
</syntaxhighlight>

=== Nextcloud Cronjob ===

Für die regelmäßigen Hintergrundaufgaben innerhalb der Nextcloud sollte ein Cronjob eingerichtet werden. Wir lösen dies hier mit einem weiteren Systemd-Timer:

''~/.config/systemd/user/nextcloud_background.service''
<syntaxhighlight lang=ini line>
[Unit]
Description=nextcloud cleanup job

[Service]
Type=oneshot
ExecStart=/usr/bin/php %h/nextcloud/cron.php
</syntaxhighlight>

''~/.config/systemd/user/nextcloud_background.timer''
<syntaxhighlight lang=ini line>
[Unit]
Description=timer for nextcloud cleanup job

[Timer]
OnCalendar=*:0/5
Persistent=True

[Install]
WantedBy=timers.target
</syntaxhighlight>

Den Timer aktivieren und starten:
<syntaxhighlight lang=shell line>
$ systemctl --user enable nextcloud_background.timer
$ systemctl --user start nextcloud_background.timer
</syntaxhighlight>

=== Nextcloud Push ===

Um Vorgänge wie Sync und Benachrichtigungen bei sehr großen Nextcloud Installationen zu beschleunigen, kann der <code>notify_push</code> Dienst hinzuinstalliert werden.

==== Abhängigkeiten und Einschränkungen ====
* <code>notify_push</code> muss Zugriff auf den gleichen Redis-Cache wie die Nextcloud haben
** aufgrund von eingeschränktem Passwort Support sollte ein Redis Socket mit sicheren Berechtigungseinstellungen als Alternative zum Redis Port mit Passwort konfiguriert werden.
* optimaler Weise holt sich <code>notify_push</code> benötigte informationen aus der <code>config.php</code> der bestehenden Nextcloud-Installation
* eine zusätzliche (Sub)domain im gleichen User ist nötig. Andernfalls muss die bestehende <code>.htaccess</code> muss aus o.g. Gründen modifiziert werden, dies könnte bei Nextcloud-Updates verloren gehen(!)
* Bestimmte Portbereiche sind bei Hostsharing eingeschränkt, es empfiehlt sich, direkt beispielsweise Port <code>37867</code> zu nehmen. aus diesem Grund ist das automatische Setup durch das Plugin bei Hostsharing nicht möglich!

==== Installation ====
Siehe auch: https://github.com/nextcloud/notify_push#manual-setup

1. Installieren der Nextcloud-App <code>notify_push</code> – (nach Push suchen, "Client Push" wählen) 
2. falls noch nicht erstellt: <code>mkdir -p ~/.config/systemd/user</code> 
3. mit Lieblingseditor die Datei <code>~/.config/systemd/user/notify_push.service</code> anlegen: 
<syntaxhighlight lang="ini" line>
[Unit]
Description = Push daemon for Nextcloud clients
Documentation = https://github.com/nextcloud/notify_push

[Service]
# Change if you already have something running on this port
Environment = PORT=37867
# We don't want to bind to 0.0.0.0, hence the --bind
ExecStart = /home/pacs/xyz00/users/cloud/bin/notify_push --bind 127.0.0.1 /home/pacs/xyz00/users/cloud/nextcloud/config/config.php
Type=notify

[Install]
WantedBy = default.target
</syntaxhighlight>
4. das Verzeichnis <code>~/bin</code> anlegen und die aktuellste binary herunterladen und ausführbar machen:
<syntaxhighlight lang="shell" line>release=`curl -L https://api.github.com/repos/nextcloud/notify_push/releases/latest -s | jq -r '.tag_name'` && wget --show-progress -qO ~/bin/notify_push https://github.com/nextcloud/notify_push/releases/download/$release/notify_push-x86_64-unknown-linux-musl && chmod +x ~/bin/notify_push</syntaxhighlight>
5. es könnte die folgende Umgebungsvariable zum Bedienen von systemd notwendig werden: <code>export XDG_RUNTIME_DIR=/run/user/$UID</code> 
6. den neuen systemd-Dienst automatisch bei Systemstart, sowie jetzt sofort starten: <code>systemctl enable --now --user notify_push</code> 
7. nun gehen wir in <code>doms/push.cloud.example.com/htdocs-ssl/.htaccess</code> und ersetzen den Inhalt (bevorzugt), oder wir ergänzen die .htaccess der Nextcloud im unteren Teil um die folgenden Zeilen (letzteres kann bei Updates überschrieben werden!):
<syntaxhighlight lang="apache" line>
# bei eigener (sub)domain ist /push/ nicht erforderlich, aber wer weiß, eventuell ist das mit robuster
RewriteCond %{REQUEST_URI} ^/push/ws [NC,OR]
RewriteCond %{HTTP:UPGRADE} ^WebSocket$ [NC,OR]
RewriteCond %{HTTP:CONNECTION} ^Upgrade$ [NC]
RewriteRule .* ws://127.0.0.1:37867/ws [proxy]

RewriteCond %{REQUEST_URI} ^/push [NC]
RewriteRule .* http://127.0.0.1:37867%{REQUEST_URI} [proxy]
</syntaxhighlight>
8. abschließend im Nextcloud Ordner die Konfiguration des Plugins anstoßen: <code>php occ notify_push:setup https://cloud.example.com/push</code> bzw. <code>php occ notify_push:setup https://push.cloud.example.com/push</code> 
9. es ist möglich, das die erkannte IP-Adresse des Hives noch nicht vertraut ist. In diesem Fall wird der obige Befehl scheitern und es muss jene aus der Fehlermeldung des Setups unter <code>trusted_proxies</code> in der <code>config.php</code> ergänzt werden. 

Es wird im Repo außerdem ein Testclient bereitgestellt, der sich testweise mit dem Push-Dienst verbindet

== Nextcloud mit Online Office ==

In Nextcloud können Office-Dokumente (Textverarbeitung, Tabellen und Präsentationen) im Browser bearbeitet werden. Dazu steht bei Hostsharing die Collabora Developer Version zur Verfügung. Bestellung und Konfiguration sind hier im Wiki auf der Seite [[Collabora_Online]] beschrieben.

== Nextcloud mit Nextcloud Talk ==

Über die Nextcloud-App "Talk" können Videokonfererenzen mit Screensharing durchgeführt werden. Für die regelmäßige Nutzung kann es sinnvoll sein, einen eigenen TURN Server zu betreiben. Siehe dazu [[Coturn_Installieren]]

Das Hochleistungs-Backend haben wir mittlerweile bei manchen Mitgliedern bereits im Einsatz. Es wird auf einem Container Server installiert. (siehe auch [[Container#Nextcloud_High_Performance_Backend_mit_Caddy|Nextcloud High Performance Backend auf Container Server]])

Unser Mitglied Timotheus Pokorra bietet auch einen Nextcloud High Performance Backend Server zum Teilen an. Siehe [https://solidevereine.de/organisation/nextcloud/#highperf]

Ohne das Hochleistungs-Backend macht wohl die Audio bzw. Video Funktion kaum Sinn, wenn es mit mehr als 2 Teilnehmern genutzt werden soll. Deswegen empfehlen wir, die Anrufe in Talk zu deaktivieren, und stattdessen die BBB zu benutzen.

Das Deaktivieren der Anrufe geschieht in der Administrationsoberfläche von Nextcloud, unter Talk, "Auf Gruppen beschränken", "Starten von Anrufen begrenzen": "Anrufe deaktivieren"

[[Datei:NextcloudTalkAnrufeDeaktivieren.png]]

Die Warnung wegen dem fehlenden Hochleistungs-Backend lässt sich "entschärfen": in der Einstellungsseite von Talk in der Administrationsoberfläche, ganz oben, deaktiviere: "Vor Verbindungsproblemen bei Anrufen mit mehr als 2 Teilnehmern warnen"

[[Datei:NextcloudTalkWarnungDeaktivieren.png]]

== Virenscanner ==

Einige Nutzer wollen die Dateien in Ihrer Nextcloud regelmäßig auf Viren überprüfen. Auf unseren Servern steht dafür der OpenSource-Virenscanner "ClamAV" zur Verfügung. Wenn dieser Scanner benutzt wird, dann sollten die Einstellungen so gewählt sein, dass der ClamAV-Daemon über eine Socket Verbindung angesprochen wird. Die Einstellungen sind im Screenshot dokumentiert.

* Es wird die App [https://apps.nextcloud.com/apps/files_antivirus Antivirus für Dateien] installiert.
* Bei Modus wird gewählt: <code>ClamAV-Daemon (Socket)</code>
* Bei Socket wird gewählt: <code>/var/run/clamav/clamd.ctl</code>

[[Datei:Nextcloud-ClamAV-Einstellungen.png||nextcloud einstellungen für die virenscanner-app]]

== Volltextsuche ==

Über die Dokumente einer Nextcloud kann ein Volltextindex erstellt werden. Die Volltextsuche ermöglicht über den Index eine Suche über beliebige Begriffe, die in Dokumenten vorkommen.

Voraussetzung ist der Betrieb eines Elasticsearch Servers. Der Betrieb im Managed Webspace erfodert die Buchung von zwei "Serverdiensten". Nutzer eines Managed Server müssen mit einem spürbaren Mehrbedarf an Hauptspeicher rechnen.

Zur Installation von Elasticsearch existiert eine eigene Wikiseite: [[Elasticsearch]].

In der Nextcloud sind folgende ''Apps'' zu installieren:
* Full Text Search
* Full Text Search - Elasticsearch Platform
* Full Text Search - Files

nach der Installation der drei Apps steht in den Einstellungen ein neuer Menüpunkt "Volltextsuche" zur Verfügung.

Hier ist einzustellen:
* Suchplattform: Elasticsearch
* Adresse des Servlets: http://elastic:das-erzeugt-passwort@127.0.0.1:39200
* Index: frei-gewaehlter-name-idx
* Analyzer tokenizer: standard

Die anderen Einstellung nach den eigenen Vorstellungen vornehmen.

Der initiale Aufbau des Suchindex erfolgt über ein "occ"-Kommando auf der Shell:

<syntaxhighlight lang=shell line>
cd nextcloud/
php occ fulltextsearch:index --output
</syntaxhighlight>

Wenn dieser Fehler kommt:
<syntaxhighlight lang=text>
TypeError: Return value of OCA\Files_FullTextSearch\Model\MountPoint::isGlobal()
must be of the type bool, null returned in [...]/apps/files_fulltextsearch/lib/Model/MountPoint.php:103
</syntaxhighlight>
sollte dieser Patch angewendet werden: https://github.com/nextcloud/files_fulltextsearch/issues/125#issuecomment-877789742

Zur Pflege des Indexes wird ein weiterer Hintergrundprozess gestartet:

<syntaxhighlight lang=shell line>
cd nextcloud/
php occ fulltextsearch:live -q
</syntaxhighlight>

Die Monit Konfiguration dafür sieht so aus:

<syntaxhighlight lang=shell line>
#~/bin/start-fulltextsearchlive
#
#!/bin/bash
export HOME=/home/pacs/xyz00/users/cloud
cd $HOME
mkdir -p $HOME/var
cd $HOME/nextcloud
exec php occ fulltextsearch:live -q &
echo $! >$HOME/var/fulltextsearchlive.pid
</syntaxhighlight>

<syntaxhighlight lang=shell line>
#~/bin/stop-fulltextsearchlive
#
#!/bin/bash
export HOME=/home/pacs/xyz00/users/cloud
kill $( cat $HOME/var/fulltextsearchlive.pid )
</syntaxhighlight>

~/.monitrc (siehe oben von der Redis Installation) entsprechend ergänzen:
<syntaxhighlight lang=shell line>
check process fulltextsearchlive with pidfile /home/pacs/xyz00/users/cloud/var/fulltextsearchlive.pid
start program "/home/pacs/xyz00/users/cloud/bin/start-fulltextsearchlive"
stop program "/home/pacs/xyz00/users/cloud/bin/stop-fulltextsearchlive"
</syntaxhighlight>

== Integration mit LDAP ==

Um einheitliche Benutzerzugänge für verschiedene Anwendungen zu ermöglichen, wird oft auf ein zentrales LDAP Verzeichnis gesetzt.

Dieses kann für Nextcloud eingesetzt werden, damit Benutzer nicht lokal in Nextcloud, sondern in LDAP verwaltet werden können.

Siehe auch https://docs.nextcloud.com/server/latest/admin_manual/configuration_user/user_auth_ldap.html

Dazu muss die App "LDAP user and group backend" in den Nextcloud Apps aktiviert werden.

Dann muss die LDAP Anbindung in den Administrationseinstellungen unter "LDAP/AD-Integration" eingerichtet werden.

Der Server mit Port, die BenutzerDN mit Passwort und die BaseDN müssen eingetragen werden.

Es muss auch bestimmt werden, welche Klasse (z.B. inetOrgPerson) die Benutzer brauchen, um Zugriff auf die Nextcloud zu erhalten.

Falls schon Benutzer in der Nextcloud existieren, und diese zu LDAP mitgenommen werden sollen, kann der Anleitung aus diesem Forum Eintrag gefolgt werden: https://help.nextcloud.com/t/migration-to-ldap-keeping-users-and-data/13205

* Voraussetzung ist, dass der Benutzernamen der zu übernehmenden Benutzer in Nextcloud der uid in LDAP entspricht.
* Es wird ein Administrator Benutzer benötigt, der lokal angelegt wurde, und auch lokal bleibt.
* Mit diesem Administrator Benutzer wird die LDAP Anbindung eingerichtet.
* In der Experten Ansicht von LDAP/AD muss bei "Attribut für interne Benutzernamen" eingetragen werden: uid
* Klicke den Schalter "LDAP Benutzernamenzuordnung löschen"
* Klicke den Schalter "LDAP Gruppennamenzuordnung löschen"
* dann in der MySQL Datenbank anmelden, und aus uc_users alle Benutzer bis auf den Administrator Benutzer löschen
* Dann in der Nextcloud Weboberfläche sich alle Benutzer anzeigen lassen
* Nun gelingt die Anmeldung mit den anderen Benutzern mit dem LDAP Passwort, und die Dateien wurden übernommen.

== Optimierung der Geschwindigkeit ==
Manchmal fühlt sich die Nextcloud träge an.

Folgende Änderungen können helfen:

* HTTP/2.0 aktivieren: dem Service von Hostsharing Bescheid geben
* Die App Dashboard deaktivieren, und dafür werden direkt die Dateien angezeigt
* Einblenden der README in den Ordnern abschalten: das kann pro Ordner in der UI geschehen (links unten), oder global: <code>occ config:app:set text workspace_available --value=0</code>. Siehe auch [https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/text_configuration.html#disable-rich-workspaces-globally]

== Default App einstellen ==

In der Datei config.php können wir einstellen, welche App direkt nach der Anmeldung gezeigt wird.

Das ist entweder die Dashboard App, wenn sie aktiviert ist, oder die Dateien App (files).

Falls der Kalender direkt angezeigt werden soll, muss folgende Zeile in der config.php hinzugefügt werden (siehe auch [https://docs.nextcloud.com/server/stable/admin_manual/configuration_server/config_sample_php_parameters.html#defaultapp]):

<syntaxhighlight lang=shell>
'defaultapp' => 'calendar',
</syntaxhighlight>

= Nextcloud Updates =

== Updater über die Shell starten ==

Wenn die NextCloud sich nicht über das Webfrontend updaten lässt, kann der Updater auch per Shell im directory /updater durch ausführen des updater.phar gestartet werden:

<syntaxhighlight lang=shell line>
xyz00-cloud@h00:~$ cd ~/nextcloud
xyz00-cloud@h00:~/nextcloud$ php updater/updater.phar
</syntaxhighlight>

Falls während des Updates kein Backup angelegt werden soll:

<syntaxhighlight lang=shell line>
xyz00-cloud@h00:~$ cd ~/nextcloud
xyz00-cloud@h00:~/nextcloud$ php updater/updater.phar --no-backup
</syntaxhighlight>

Es sollten außerdem ein paar Routine-Aufräumarbeiten durchgeführt werden:

<syntaxhighlight lang=shell line>
xyz00-cloud@h00:~$ cd ~/nextcloud
xyz00-cloud@h00:~/nextcloud$ php occ db:add-missing-primary-keys --no-interaction
xyz00-cloud@h00:~/nextcloud$ php occ db:add-missing-columns --no-interaction
xyz00-cloud@h00:~/nextcloud$ php occ db:add-missing-indices --no-interaction
xyz00-cloud@h00:~/nextcloud$ php occ db:convert-filecache-bigint --no-interaction
xyz00-cloud@h00:~/nextcloud$ php occ maintenance:repair --include-expensive
</syntaxhighlight>

So können die Apps noch alle aktualisiert werden:

<syntaxhighlight lang=shell line>
xyz00-cloud@h00:~$ cd ~/nextcloud
xyz00-cloud@h00:~/nextcloud$ php occ app:update --all -n --no-ansi
</syntaxhighlight>

Für weitere Informationen kann auf die offizielle Doku ab Ziffer 2. zurückgegriffen werden.

* [https://docs.nextcloud.com/server/latest/admin_manual/maintenance/update.html#using-the-command-line-based-updater https://docs.nextcloud.com]

Hier gibt es ein kurzes Video, das die Anmeldung über die Kommandozeile mit Putty erklärt und die Aktualisierung von Nextcloud auf der Kommandozeile:

* [https://tube.solidcharity.net/w/0cf5ee97-ba7c-41df-a56f-8d1fea842ab0 Nextcloud auf der Kommandozeile aktualisieren]

== Wartungsmodus per Shell ein- oder ausschalten ==

So kann der Wartungsmodus angeschaltet werden:

<syntaxhighlight lang=shell line>
xyz00-cloud@h00:~$ cd ~/nextcloud
xyz00-cloud@h00:~/nextcloud$ php occ maintenance:mode --on
</syntaxhighlight>

So kann der Wartungsmodus wieder ausgeschaltet werden, d.h. die Nextcloud ist dann wieder in Betrieb:

<syntaxhighlight lang=shell line>
xyz00-cloud@h00:~$ cd ~/nextcloud
xyz00-cloud@h00:~/nextcloud$ php occ maintenance:mode --off
</syntaxhighlight>

== Webfrontend-Updater Probleme / Lösungen ==

=== Datenbank: Indizes | Primärschlüssel | Konvertierungen ===

Aufgetreten nach erfolgtem Versionsupdate Nextcloud 19 auf Nextcloud 20

Nach dem erfolgten Update lädt automatisch die Seite: '''Sicherheits- und Einrichtungswarnungen''' auf dieser wird angemerkt, dass manuelle Schritte für die Datenbank durchzuführen sind. Dies betrifft Indizes, Primärschlüssel und Konvertierungen.

Per Shell in der directory /nextcloud folgende Kommandos ausführen:

<syntaxhighlight lang=shell line>
xyz00-cloud@h00:~$ cd ~/nextcloud
xyz00-cloud@h00:~/nextcloud$ php occ db:add-missing-primary-keys --no-interaction
xyz00-cloud@h00:~/nextcloud$ php occ db:add-missing-columns --no-interaction
xyz00-cloud@h00:~/nextcloud$ php occ db:add-missing-indices --no-interaction
xyz00-cloud@h00:~/nextcloud$ php occ db:convert-filecache-bigint --no-interaction
xyz00-cloud@h00:~/nextcloud$ php occ maintenance:repair --include-expensive
</syntaxhighlight>

Wichtig ist hier dem durch Nextcloud angegebenen Kommando ein '''php''' voranzustellen.

== Update per Skript ==

Es ist möglich die regelmäßigen Updates weitgehend zu automatisieren. Ein Skript wäre etwa:

<syntaxhighlight lang=shell line>
#!/bin/bash
if [ -f $HOME/nextcloud/occ ]; then
echo "Nextcloud Update";
cd $HOME/nextcloud;
php updater/updater.phar -vv --no-backup --no-interaction
php occ maintenance:mode --on
php occ db:add-missing-primary-keys --no-interaction
php occ db:add-missing-columns --no-interaction
php occ db:add-missing-indices --no-interaction
php occ db:convert-filecache-bigint --no-interaction
php occ maintenance:repair --include-expensive
php occ app:update --all
php occ maintenance:mode --off
else
echo "Keine Nextcloud Installation gefunden";
fi
</syntaxhighlight>

== Update: bei old-stable Version bleiben ==

Normalerweise fragt jede Nextcloud Instanz zentral ab, welches Update zur Verfügung steht, abhängig vom Release Channel. Dabei wird aber relativ schnell auf die nächste Version gewechselt, also z.B. von Nextcloud 31 auf Nextcloud 32, obwohl Nextcloud 31 noch mehrere Monate gepflegt wird, und manche Apps noch nicht bereit sind für Nextcloud 32.

Es kann aber auch eine Alternative eingerichtet werden, in der Datei nextcloud/config/config.php, unter dem Eintrag updater.server.url

Hier wird z.B. auf einen Updater von unserem Mitglied Timotheus Pokorra verwiesen:

<syntaxhighlight lang=php line>
updater_server_url: "https://ncupdater.solidcharity.com/31/"
</syntaxhighlight>

Dahinter läuft ein Skript, mit dem wir noch länger eine bestimmte Version anbieten können: https://codeberg.org/tpokorra/ncupdater

= Daten auf HDD Storage =
== Einrichtung des HDD Storage ==

Um den langsameren aber günstigeren HDD Storage von Hostsharing zu nutzen, kann das data Verzeichnis von SSD auf HDD Storage verschoben werden. Ein symbolischer Link reicht nicht aus, man muss den Pfad in der Nextcloud Konfigurationsdatei anpassen.

<syntaxhighlight lang=shell>
# Nextcloud in Wartungsmodus versetzen
xyz00-cloud@h00:~/nextcloud$ php occ maintenance:mode --on
# Daten auf HDD Storage verschieben
xyz00-cloud@h00:~/nextcloud$ mv data /home/storage/xyz00/users/cloud/
# symbolischen Link anlegen
xyz00-cloud@h00:~/nextcloud$ ln -s /home/storage/xyz00/users/cloud/data data
# Pfad in config.php ändern
nano config/config.php
# Die Zeile mit 'datadirectory' finden und entsprechend ändern:
# 'datadirectory' => '/home/storage/xyz00/users/cloud/data',
# Wartungsmodus beenden
xyz00-cloud@h00:~/nextcloud$ php occ maintenance:mode --off
</syntaxhighlight>

Ein Fallstrick: Im data-Verzeichnis liegt eine versteckte Datei ".ncdata". Beim Move-Befehl "mv" für das komplette Data-Verzeichnis wird diese Datei mit verschoben. Sonst muss die Datei ggf. ins neue data-Verzeichnis kopiert werden!

= Einschränkende Bemerkungen =
== Nextcloud Sync Client ==

Der Nextcloud Sync Client erfüllt eine Funktion ähnlich wie Dropbox, und synchronisiert ganze Ordnerstrukturen.

Gerade wenn man mit mehreren Menschen in einer Nextcloud arbeitet, ist diese Funktion mit Vorsicht zu benutzen.

* Änderungen an der Ordnerstruktur sollten nicht lokal, sondern im Webbrowser vorgenommen werden.
* Wenn die Gefahr besteht, dass mehrere Menschen gleichzeitig eine Datei bearbeiten, sollte die Datei nicht lokal, sondern im Webbrowser bearbeitet werden.
* Aus Sicht des Datenschutzes und der Daten-Minimierung sollte überlegt werden, ob die Daten wirklich auf jeden Laptop und Rechner synchronisiert werden sollen, oder ob es reicht, ausschließlich über den Webbrowser auf die Daten zuzugreifen.

= weiterführende Links =

* [https://docs.nextcloud.com/ Nextcloud Dokumentation]
* [https://apps.nextcloud.com/ Nextcloud Erweiterungen ("Apps")]
* [https://docs.nextcloud.com/server/stable/admin_manual/installation/server_tuning.html Optimierung des Caches z.B. für Previews]
* [https://codeberg.org/tpokorra/hs.ansible/src/branch/main/playbooks/nextcloud Ansible Playbook für Hostsharing]

= Nextcloud Reseller bei HS =

[https://nextcloud.ossaas.de OS SaaS]

----
[[Kategorie:HSDoku]]
[[Kategorie:Installationsanleitungen]]
[[Kategorie:Ansible Playbook]]
[[Kategorie:Software]]
[[Kategorie:CalDAV]]
[[Kategorie:Nextcloud]]

Collabora Online

2026-04-14T06:13:35Z

Tim00: /* Collabora konfigurieren */ IPv6 und IPv4 eintragen

= Collabora installieren =

== Empfohlene Hardwareausrüstung ==

siehe auch https://sdk.collaboraonline.com/docs/installation/Configuration.html#performance

Wir konfigurieren nun Collabora Online so, dass die Anzahl der verfügbaren CPUs automatisch berücksichtigt wird.

== Vorbereitungen ==

Voraussetzungen sind folgende Punkte:

1. Per Mail an service@hostsharing.net die Aktivierung der Paket Option Collabora Online beauftragen mit der Angabe des Paketkürzel xyz00 und des Benutzers xyz00-cloud unter der die Installation läuft.

2. Grundlage bei Hostsharing ist die Installation der Nextcloud laut Wiki Anleitung [[Nextcloud]].

3. Die APP ''Nextcloud Office'' erst installieren wenn der Service die Bestätigung gesendet hat, dass die Aktivierung erfolgt ist. Hinweis: Bei der Nextcloud-Installation wird ''Nextcloud Office'' u.U. automatisch mit installiert. In diesem Fall ist es notwendig, die App zunächst zu deaktivieren: als Admin im Profilmenü "+ Apps" öffnen und sie dort unter "Aktive Apps" deaktivieren.

== Collabora installieren ==

Collabora ist auf allen 64 Bit hive installiert. Es muss hier nun noch die APP Collabora Online in der Nextcloud installiert werden.

'''WICHTIG:''' Die Freigabe vom Service muss erst per Mail vorliegen!!

1. Anmeldung als '''Admin''' in der Nextcloud Installation

2. Rechts oben auf '''Profilmenü''' den Eintrag '''+APP''' auswählen
[[Datei:Hs-collabora-app-install.jpg|300px]]

3. Im '''Suchfeld''' oben "Nextcloud Office" eingeben
[[Datei:Nextcloud-Office-Suche.png|600px]]

4. Auf den Button ''Herunterladen und aktivieren'' klicken

Damit ist die APP Nextcloud Office installiert und muss nun noch konfiguriert werden.

== Collabora konfigurieren ==

Rechts oben unter '''Profilmenü''' den Eintrag '''Einstellungen''' auswählen.

Anschließend im linken Fensterbereich unter dem Menüpunkt '''Verwaltung'''
den Eintrag '''Collabora Online''' auswählen.

[[Bild:Nextcloud-Office-Menue.png|300px]]

Hier muss nun die PaketDomain entsprechend Eingetragen werden.
Wobei '''xyz00'''.hostsharing.net durch Ihr Paket Kürzel zu ersetzten ist.
Es wird kein Port eingetragen!
Anschließend einmal auf den Button ''Anwenden'' klicken.
[[Bild:Nextcloud-Office-URL.png|600px]]

Es wird empfohlen bei 'Allow list for WOPI requests' die aufgelöste IP Adresse des Webpaketes xyz00.hostsharing.net einzutragen. Sodass nur diese Collabora Instanz Dokumente aus der Nextcloud erhalten kann. Die IP erhält man z.B. über den Konsolenbefehl

<syntaxhighlight lang=shell>
dig -t AAAA xyz00.hostsharing.net +short
2a01:37:1000::53df:4fb1:0
dig -t A xyz00.hostsharing.net +short
83.223.79.177
</syntaxhighlight>

Die beiden IP Adressen sollten mit Komma getrennt in der Nextcloud auf der Admin Config Seite von Collabora hinterlegt werden.

Weitere Einstellungen können individuell noch vorgenommen werden.

----
[[Kategorie:HSDoku]]
[[Kategorie:Installationsanleitungen]]
[[Kategorie:Software]]

Discourse installieren

2026-04-14T03:56:59Z

Tim00: /* Am Beispiel von 2026.1.1 auf 2026.1.3 */

{{Textkasten|gelb|Für Managed Server|Ein funktionierender Discourse-Server erfordert mehrere laufende Server-Dienste. Für den Betrieb ist ein Managed Server sinnvoll.}}

{{Textkasten|rot|Support von der Discourse-Community|Die Discourse-Entwickler haben sich entschieden, nur eine mehr oder weniger genormte Installationsmethode (via docker) zu unterstützen. Dies ist so auf der hostsharing-Architektur aufgrund mehrerer Bedenken und Überlegungen nicht möglich. Die Community ist durchaus hilfreich, geht aber davon aus, dass quasi alle Nutzer* eine "supported"e Installation durchgeführt haben. Wenn man in entsprechenden Kanälen nach Hilfe fragt, sollte man unbedingt erwähnen, dass man discourse selber anhand dieser hier lesbaren Anleitung installiert hat, um bereits entsprechenden Kommentaren und Nachfragen vorzugreifen.}}

== Über ==

In diesem Artikel wird die Installation von discourse, Version 2.1.0 (September 2018) beschrieben.

== Vorbereitungen ==

Mit Hilfe von HSAdmin wird angelegt:
# Ein User als Service-User mit ''/bin/bash'' als Shell, zum Beispiel Beispiel: ''xyz00-discourse''
# Eine Domain mit ''xyz00-discourse' als Domain-Administrator, zum Beispiel ''beispiel.discussion''
# Einen Postgresql-User ''xyz00_discourseuser'' mit Passwort ''meinPasswort''
# Eine Postgresql-Datenbank ''xyz00_discoursedb'' mit Datenbank-Owner ''xyz00_discourseuser''

Verwendete IP-Ports der Server-Dienste:
# Redis: localhost:32002
# Discourse-Web: localhost:13000

== Konfiguration der PostgreSQL Datenbank ==

Es müssen noch Erweiterungen für Postgresql installiert werden:

<syntaxhighlight lang=shell line>
psql --user xyz00_discourseuser -c "CREATE EXTENSION IF NOT EXISTS hstore WITH SCHEMA public;"
psql --user xyz00_discourseuser -c "CREATE EXTENSION IF NOT EXISTS pg_trgm WITH SCHEMA public;"
psql --user xyz00_discourseuser -c "CREATE EXTENSION IF NOT EXISTS unaccent WITH SCHEMA public;"
</syntaxhighlight>

== Konfiguration des Redis Server ==

{{Textkasten|gelb|Firewall/Redis Port|Leider unterstützt discourse nicht die Kommunikation mit Redis über Unix-Sockets. Dementsprechend muss der für Redis konfigurierte Port von dem hostsharing-Support in der Firewall freigegeben werden.}}

<syntaxhighlight lang=shell>
cd
mkdir redis/etc redis/lib redis/log redis/run
</syntaxhighlight>

Anlegen einer Datei ''/home/pacs/xyz00/users/discourse/redis/etc/redis.conf'' mit folgendem Inhalt:

<syntaxhighlight lang=shell line>
daemonize no
pidfile /home/pacs/xyz00/users/discourse/redis/run/redis-server.pid
port 32002
tcp-backlog 128
bind 127.0.0.1
timeout 300
loglevel notice
logfile /home/pacs/xyz00/users/discourse/redis/log/redis.log
databases 16
save 900 1
save 300 10
save 60 10000
slave-serve-stale-data yes
appendonly no
dbfilename dump.rdb
dir /home/pacs/xyz00/users/discourse/redis/lib
</syntaxhighlight>

Für Discourse 3.x gilt: "Discourse requires Redis 6.2.0 or up"

Für Debian Buster und Bullseye ist daher das Installieren eines neueren Binaries erforderlich. Bei Debian Bookwork ist bereits Redis 7.0 enthalten (siehe https://packages.debian.org/search?keywords=redis-server).

Hier steht ein entsprechendes Binary für Debian Buster zur Verfügung, das mit dem Public Key von Timotheus geprüft werden kann:

* https://download.solidcharity.com/tarballs/tpokorra/hostsharing/redis-server-6.2.12-debian-buster.tar.gz
* Prüfsignatur: https://download.solidcharity.com/tarballs/tpokorra/hostsharing/redis-server-6.2.12-debian-buster.tar.gz.sig

Prüfen der Signatur:

<syntaxhighlight lang=shell>
gpg --verify redis-server-6.2.12-debian-buster.tar.gz.sig redis-server-6.2.12-debian-buster.tar.gz
</syntaxhighlight>

Das Binary muss nach <code>$HOME/bin</code> verschoben werden, und entsprechend beim Starten des Dienstes eingetragen werden.

== Installation von Ruby ==

Als User ''xyz00-discourse'': Installation von Ruby mit ''rbenv'' mit folgenden Befehlen:

Zunächst ''rbenv'' and ''ruby-build'':

<syntaxhighlight lang=shell line>
git clone https://github.com/rbenv/rbenv.git ~/.rbenv
cd ~/.rbenv && src/configure && make -C src
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.profile
echo 'eval "$(rbenv init -)"' >> ~/.profile
</syntaxhighlight>

starte neue Shell:

<syntaxhighlight lang=shell>
exec bash
</syntaxhighlight>

Überprüfe rbenv-Installation

<syntaxhighlight lang=shell>
type rbenv
</syntaxhighlight>

Installiere ruby-build als rbenv-Plugin

<syntaxhighlight lang=shell>
git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build
</syntaxhighlight>

Nun kann die benötigte Ruby-Version installiert werden:

<syntaxhighlight lang=shell>
rbenv install 2.4
</syntaxhighlight>

== Installation von Discourse selber ==

Weiterhin Als User ''xyz00-discourse'':

<syntaxhighlight lang=shell>
cd ~
git clone https://github.com/discourse/discourse.git discourse
cd ~/discourse
</syntaxhighlight>

Die stabile Version auschecken:

<syntaxhighlight lang=shell>
git checkout stable
</syntaxhighlight>

Ruby Pakete installieren:

<syntaxhighlight lang=shell>
gem install bundler
bundle install -j$(getconf _NPROCESSORS_ONLN) --deployment --without development test
</syntaxhighlight>

== Konfiguration der Discourse Software ==

Anlegen einer Datei ''/home/pacs/xyz00/users/discourse/discourse/config/discourse.conf'' anhand der Beispiel-Datei:

<syntaxhighlight lang=shell>
cd ~/discourse
cp config/discourse_defaults.conf config/discourse.conf
</syntaxhighlight>

Anpassen folgender Inhalte:
<syntaxhighlight lang=ini line>
db_host = 127.0.0.1
db_port = 5432
#db_backup_port = 5432 #(auskommentieren)
db_name = xyz00_discoursedb
db_username = xyz00_discourseuser
db_password = "" #db password
hostname = "discourse.xyz00" # hostname
smtp_address = localhost
smtp_enable_start_tls = false
smtp_openssl_verify_mode = 'none'
developer_emails = # your email-address
redis_host = 127.0.0.1
redis_port = 32002
</syntaxhighlight>
===TODO: Secrets setzen! ===
Die Zufallswerte für die Variablen SECRET_KEY_BASE und OTP_SECRET erzeugt man durch zwei Aufrufe des Kommandos

<syntaxhighlight lang=shell>
RAILS_ENV=production bundle exec rake secret
</syntaxhighlight>

=== Sidekiq für Hintergrund-Aufgaben konfigurieren ===

''config/sidekiq.conf''

Wichtig: development auf production ändern.

Mit diesem Dienst werden z.B. die E-Mails zur Aktivierung oder zum Passwort Reset verschickt.

=== Problem mit Content Security Policy ===

Um ein Problem mit Content Security Policy zu lösen, weil manche Dateien über http nachgeladen werden, muss in der Datei <code>config/site_settings.yml</code> der Default Wert für force_https auf True gesetzt werden:
<syntaxhighlight lang=yaml line>
force_https:
default: true
</syntaxhighlight>
=== Problem beim Aufsetzen der Datenbank vermeiden ===

'''→ Notiz Mai 2024:''' dies scheint aktuell nicht aufzutreten.

Aus irgendeinem Grund wird beim Initialisieren der Datenbank versucht, den TYPE hotlinked_media_status zweimal in der Datenbank anzulegen. Der Grund ist nicht ersichtlich.

Es kann folgende Änderung an der Datei <code>db/migrate/20220428094026_create_post_hotlinked_media.rb</code> vorgenommen werden:
<syntaxhighlight lang=ruby line>
reversible do |dir|
dir.up { execute <<~SQL }
DO $$ BEGIN CREATE TYPE hotlinked_media_status AS ENUM('downloaded', 'too_large', 'download_failed', 'upload_create_failed'); EXCEPTION WHEN duplicate_object THEN null; END $$;
SQL
dir.down { execute <<~SQL }
DROP TYPE hotlinked_media_status
SQL
end
</syntaxhighlight>
=== Initialisieren der Datenbank ===

<syntaxhighlight lang=shell>
export SAFETY_ASSURED=1
# In Version 2.0.4 funktioniert db:migrate noch, ansonsten db:schema:load und seed nutzen!
# In Version 3.0.3 funktioniert db:migrate auch noch, db:schema:load ging nicht weil die Datei structure.sql fehlte
#RAILS_ENV=production bundle exec rails db:schema:load
#RAILS_ENV=production bundle exec rails db:seed
RAILS_ENV=production bundle exec rails db:migrate
</syntaxhighlight>

=== Kompilieren der Assets ===

<syntaxhighlight lang=shell>
RAILS_ENV=production bundle exec rails assets:precompile
</syntaxhighlight>

=== Konfiguration des Web-Servers (am Beispiel Puma) ===

Die Datei ''config/puma.conf'' anpassen (hier nur Änderungen angezeigt):

<syntaxhighlight lang=ini>
APP_ROOT = '/home/pacs/xyz00/users/discourse/discourse'
daemonize false
</syntaxhighlight>

== Starten der Dienste ==

Zum Start aller notwendigen Dienste sollte systemd benutzt werden.

Die folgenden Dateien müssen nach <code>.config/systemd/user/</code> kopiert werden (überlange Zeilen werden hier im Wiki umgebrochen)

redis.service:

<syntaxhighlight lang=ini line>
[Unit]
Description=Redis User Service

[Service]
WorkingDirectory=%h/var/redis
Environment="PATH=/usr/local/bin:/usr/bin:/bin"
ExecStart=%h/bin/redis-server %h/etc/redis.conf
Restart=always
PrivateTmp=true
NoNewPrivileges=true

[Install]
WantedBy=default.target
</syntaxhighlight>

sidekiq.service:

<syntaxhighlight lang=ini line>
[Unit]
Description=Discourse Sidekiq Service

[Service]
WorkingDirectory=%h/discourse
Environment="PATH=/usr/local/bin:/usr/bin:/bin"
Environment="RAILS_ENV=production"
Environment="DB_POOL=8"
Environment="MALLOC_ARENA_MAX=2"
ExecStart=%h/.rbenv/shims/bundle exec sidekiq -C %h/discourse/config/sidekiq.yml
StandardOutput=append:%h/var/log/sidekiq.out.log
StandardError=inherit
Restart=always
PrivateTmp=true
NoNewPrivileges=true

[Install]
WantedBy=default.target
After=redis.service
</syntaxhighlight>

discourse.service:

<syntaxhighlight lang=ini line>
[Unit]
Description=Discourse Web Service

[Service]
WorkingDirectory=%h/discourse
Environment="PATH=/usr/local/bin:/usr/bin:/bin"
Environment="RAILS_ENV=production"
Environment="WEB_CONCURRENCY=2"
Environment="MAX_THREADS=5"
Environment="MALLOC_ARENA_MAX=2"
ExecStart=%h/.rbenv/shims/bundle exec puma -C config/puma.rb -e production -b tcp://127.0.0.1:13000
StandardOutput=append:%h/var/log/puma.out.log
StandardError=inherit
Restart=always
PrivateTmp=true
NoNewPrivileges=true

[Install]
WantedBy=default.target
After=redis.service
</syntaxhighlight>

== Einrichten des Apache VHost ==

<syntaxhighlight lang=shell>
cd ~/doms/beispiel.discuss
rm -rf htdocs-ssl subs/www subs-ssl/www
ln -s ~/live/public htdocs-ssl
touch htdocs-ssl/.htaccess
</syntaxhighlight>

Dann die ''htdocs-ssl/.htaccess'' (durch das gelinkte Verzeichnis entspricht das dem Pfad /home/pacs/xyz00/users/discourse/discourse/public/.htaccess ) mit dem Editor der Wahl öffnen und folgende Konfiguration einfügen:

<syntaxhighlight lang=apache line>
DirectoryIndex disabled

RequestHeader set X-Forwarded-Proto "https"

RewriteEngine On
RewriteBase /
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-l
RewriteRule .* http://127.0.0.1:13000%{REQUEST_URI} [proxy,last]
</syntaxhighlight>
== Wartung ==
=== Backup ===

Discourse macht selbstätig backups und legt diese unter 'public/backups' ab. Enthalten ist ein Datenbank-Dump und die hochgeladenen Dateien.

Im Admin-Bereich lassen sich backups auch manuell antreten.

=== Admin Benutzer einladen ===

Manchmal brauchen wir einen neuen Admin Benutzer, den wir von der Kommandozeile aus einladen möchten.

<syntaxhighlight lang=shell>
cd /discourse
RAILS_ENV=production rake admin:invite[admin@example.org]
</syntaxhighlight>

=== Import aus mbox Archiven ===

Um zum Beispiel ein Mailman2 Archiv zu importieren, wo die Nachrichten als .mbox Datei vorliegen, sind folgende Schritte nötig:

Vorbereitungen an Discourse:

<syntaxhighlight lang=shell>
source .profile
cd discourse
bundle config set frozen false
IMPORT=1 bundle install
bundle config set frozen true
nano script/import_scripts/mbox/settings.yml
# dort ändern:
# data_dir: /home/pacs/xyz00/users/discourse/list-archiv
</syntaxhighlight>

Hochladen der Mailinglisten-Archive:
<syntaxhighlight lang=shell>
mkdir ~/list-archiv
# dort muss es Unterordner mit dem Namen der gewünschten Kategorie geben,
# und die mbox Datei muss auch diesen Namen haben, z.B.:
# ~/list-archiv/beispiel/beispiel.mbox
# ~/list-archiv/example/example.mbox
# um die Beiträge in den entsprechenden Kategorien beispiel und example einzufügen.
</syntaxhighlight>

Durchführen des Imports:
<syntaxhighlight lang=shell>
source .profile
cd discourse
RAILS_ENV=production IMPORT=1 bundle exec rails runner \
script/import_scripts/mbox.rb script/import_scripts/mbox/settings.yml
</syntaxhighlight>

=== Export ===
* Wenn ein Forum beendet wird, möchte man evtl. eine Sicherung als statische HTML Seiten.
** Das wird hier diskutiert: https://meta.discourse.org/t/how-do-i-export-the-complete-forum-as-static-html-pages/71007/3
* Um ein Forum von Discourse zu Flarum umzuziehen, hat Timotheus ein Skript geschrieben.
** Das Migrations-Skript: https://github.com/SolidCharity/discourse_to_flarum
** siehe auch https://discuss.flarum.org/d/4930-discourse-to-flarum-migration-support/29

=== Updates ===

Discourse wird über update via mail informieren (dies kann man m.W. abschalten).

Achtung: bei größeren Updates auch immer Änderungen an der Datei site_settings.yml (https://github.com/discourse/discourse/blob/main/config/site_settings.yml) beachten!

Siehe auch die unterstützten Releases: https://releases.discourse.org/ und die Tags: https://github.com/discourse/discourse/tags

==== Am Beispiel von 2026.1.1 auf 2026.1.3 ====

# Im Web-Backend unter Administration->Backups-> Read-Only Mouds setzen (oder Web Server so konfigurieren, dass keine Zugriffe mehr stattfinden können)
# Backup
# Die lokalen Änderungen sichern:
# cd discourse
# mv ~/plugins.bak/discourse-ai plugins
# git diff v2026.1.1 > diff-2026.1.1.txt
# git fetch
# git checkout -b hostsharing-deployment-v2026.1.3 v2026.1.3
# evtl. Änderungen aus diff-2026.1.1.txt wieder übernehmen und committen
# patch -p1 < diff-2026.1.1.txt
# git commit -a -m "spezifische Änderungen für diese Instanz" --no-verify
# Schauen, ob discourse eine neue Ruby-Version nutzt (z.B. in https://github.com/discourse/discourse_docker/blob/main/image/base/Dockerfile bzw. https://github.com/discourse/discourse/blob/v2026.1.3/Gemfile)
# Ist dies der Fall, dann:
# rbenv install 3.3.8
# rbenv global 3.3.8
# rbenv rehash
# echo "3.3.8" > .ruby-version
# installiere Node 22: https://codeberg.org/tpokorra/hostsharing-scripts/src/branch/main/install-nodejs.sh
# source ~/.profile
# gem update --system
# bundle install
# npm install -g terser uglify-js pnpm@10
# corepack use pnpm@latest-10
# pnpm install
# export $(grep -v '^#' ~/discourse.env | xargs -d '\n')
# source ~/.profile
# Falls die pg extension pg_vector nicht installiert ist: deaktiviere das Plugin während migrate, aber auch für später damit /admin/settings funktioniert (ansonsten in salt pillar pg_vector installieren, und als postgres user: create extension vector;)
## mkdir -p ~/plugins.bak
## mv plugins/discourse-ai ~/plugins.bak
# RAILS_ENV=production bundle exec rake db:migrate
# RAILS_ENV=production bundle exec rake assets:precompile
# Services neu starten
<syntaxhighlight lang=shell>
systemctl --user restart puma
systemctl --user restart sidekiq
systemctl --user restart redis
</syntaxhighlight>
* Zuletzt: Read-Only Modus wieder deaktivieren

=== Debugging ===

Es können folgende Einstellungen in der Datei config/environments/production.rb vorgenommen werden. Danach den Puma Dienst neustarten. Fehlermeldungen und Stacktraces werden dann im Browser ausgegeben.

<syntaxhighlight lang="ini" line>
config.log_level = :debug
config.action_dispatch.show_exceptions = :all
config.action_dispatch.debug_exception_log_level = :error

# Full error reports are enabled and caching is turned off
config.consider_all_requests_local = true
config.action_controller.perform_caching = false
</syntaxhighlight>

=== Erforderliche Anpassungen ===
Weil wir bei Debian Bookworm noch mit ImageMagick 6.9 arbeiten, muss dieser [https://github.com/discourse/discourse/commit/17aa831337e352dfd875f1b4ddc4492bd0835119 Patch] rückgängig gemacht werden:

<syntaxhighlight lang="bash" line>
wget https://github.com/discourse/discourse/commit/17aa831337e352dfd875f1b4ddc4492bd0835119.patch -O ~/imagemagick.patch
patch -p1 --reverse < ~/imagemagick.patch
git commit -a -m "revert imagemagick patch" --no-verify
</syntaxhighlight>

== ToDos ==

* Ein Patch, um Discourse auch via Unix-Socket mit Redis sprechen lassen zu können dürfte relativ einfach sein (es wird ein Wrapper um das redis-gem genutzt).
* Konfiguration von discourse, um mit postgresql via Unix-Socket zu kommunizieren (DISCOURSE_DB_SOCKET environment variable)
* Performance-tuning an diversen Stellen, anhand der discourse_docker-Vorgaben (https://github.com/discourse/discourse_docker), z.B.
** thpoff (huge page settings)
** unicorn (hat eine wesentlich ausgefeiltere Konfigurations-Vorlage, wahrscheinlich bereits ordentlich optimiert)

== Links ==

* https://help.skysilk.com/support/solutions/articles/9000120927-how-to-install-discourse-without-docker-using-skysilk-vps-
* https://github.com/discourse/discourse_docker
* https://github.com/discourse/discourse
* https://codeberg.org/tpokorra/hs.ansible/src/branch/main/playbooks/discourse

== Historie ==

* 2018, 14 . September: Initiale Fassung
* 2019, Januar: Update-Informationen ergänzt
* 2022, Juni: systemd Dienste, Discourse 3.0

----
[[Kategorie:HSDoku]]
[[Kategorie:Installationsanleitungen]]
[[Kategorie:RubyOnRails]]
[[Kategorie:Webforen]]
[[Kategorie:Ansible Playbook]]

Discourse installieren

2026-04-04T18:56:36Z

Tim00: /* Am Beispiel von 2026.1.1 auf 2026.1.3 */

{{Textkasten|gelb|Für Managed Server|Ein funktionierender Discourse-Server erfordert mehrere laufende Server-Dienste. Für den Betrieb ist ein Managed Server sinnvoll.}}

{{Textkasten|rot|Support von der Discourse-Community|Die Discourse-Entwickler haben sich entschieden, nur eine mehr oder weniger genormte Installationsmethode (via docker) zu unterstützen. Dies ist so auf der hostsharing-Architektur aufgrund mehrerer Bedenken und Überlegungen nicht möglich. Die Community ist durchaus hilfreich, geht aber davon aus, dass quasi alle Nutzer* eine "supported"e Installation durchgeführt haben. Wenn man in entsprechenden Kanälen nach Hilfe fragt, sollte man unbedingt erwähnen, dass man discourse selber anhand dieser hier lesbaren Anleitung installiert hat, um bereits entsprechenden Kommentaren und Nachfragen vorzugreifen.}}

== Über ==

In diesem Artikel wird die Installation von discourse, Version 2.1.0 (September 2018) beschrieben.

== Vorbereitungen ==

Mit Hilfe von HSAdmin wird angelegt:
# Ein User als Service-User mit ''/bin/bash'' als Shell, zum Beispiel Beispiel: ''xyz00-discourse''
# Eine Domain mit ''xyz00-discourse' als Domain-Administrator, zum Beispiel ''beispiel.discussion''
# Einen Postgresql-User ''xyz00_discourseuser'' mit Passwort ''meinPasswort''
# Eine Postgresql-Datenbank ''xyz00_discoursedb'' mit Datenbank-Owner ''xyz00_discourseuser''

Verwendete IP-Ports der Server-Dienste:
# Redis: localhost:32002
# Discourse-Web: localhost:13000

== Konfiguration der PostgreSQL Datenbank ==

Es müssen noch Erweiterungen für Postgresql installiert werden:

<syntaxhighlight lang=shell line>
psql --user xyz00_discourseuser -c "CREATE EXTENSION IF NOT EXISTS hstore WITH SCHEMA public;"
psql --user xyz00_discourseuser -c "CREATE EXTENSION IF NOT EXISTS pg_trgm WITH SCHEMA public;"
psql --user xyz00_discourseuser -c "CREATE EXTENSION IF NOT EXISTS unaccent WITH SCHEMA public;"
</syntaxhighlight>

== Konfiguration des Redis Server ==

{{Textkasten|gelb|Firewall/Redis Port|Leider unterstützt discourse nicht die Kommunikation mit Redis über Unix-Sockets. Dementsprechend muss der für Redis konfigurierte Port von dem hostsharing-Support in der Firewall freigegeben werden.}}

<syntaxhighlight lang=shell>
cd
mkdir redis/etc redis/lib redis/log redis/run
</syntaxhighlight>

Anlegen einer Datei ''/home/pacs/xyz00/users/discourse/redis/etc/redis.conf'' mit folgendem Inhalt:

<syntaxhighlight lang=shell line>
daemonize no
pidfile /home/pacs/xyz00/users/discourse/redis/run/redis-server.pid
port 32002
tcp-backlog 128
bind 127.0.0.1
timeout 300
loglevel notice
logfile /home/pacs/xyz00/users/discourse/redis/log/redis.log
databases 16
save 900 1
save 300 10
save 60 10000
slave-serve-stale-data yes
appendonly no
dbfilename dump.rdb
dir /home/pacs/xyz00/users/discourse/redis/lib
</syntaxhighlight>

Für Discourse 3.x gilt: "Discourse requires Redis 6.2.0 or up"

Für Debian Buster und Bullseye ist daher das Installieren eines neueren Binaries erforderlich. Bei Debian Bookwork ist bereits Redis 7.0 enthalten (siehe https://packages.debian.org/search?keywords=redis-server).

Hier steht ein entsprechendes Binary für Debian Buster zur Verfügung, das mit dem Public Key von Timotheus geprüft werden kann:

* https://download.solidcharity.com/tarballs/tpokorra/hostsharing/redis-server-6.2.12-debian-buster.tar.gz
* Prüfsignatur: https://download.solidcharity.com/tarballs/tpokorra/hostsharing/redis-server-6.2.12-debian-buster.tar.gz.sig

Prüfen der Signatur:

<syntaxhighlight lang=shell>
gpg --verify redis-server-6.2.12-debian-buster.tar.gz.sig redis-server-6.2.12-debian-buster.tar.gz
</syntaxhighlight>

Das Binary muss nach <code>$HOME/bin</code> verschoben werden, und entsprechend beim Starten des Dienstes eingetragen werden.

== Installation von Ruby ==

Als User ''xyz00-discourse'': Installation von Ruby mit ''rbenv'' mit folgenden Befehlen:

Zunächst ''rbenv'' and ''ruby-build'':

<syntaxhighlight lang=shell line>
git clone https://github.com/rbenv/rbenv.git ~/.rbenv
cd ~/.rbenv && src/configure && make -C src
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.profile
echo 'eval "$(rbenv init -)"' >> ~/.profile
</syntaxhighlight>

starte neue Shell:

<syntaxhighlight lang=shell>
exec bash
</syntaxhighlight>

Überprüfe rbenv-Installation

<syntaxhighlight lang=shell>
type rbenv
</syntaxhighlight>

Installiere ruby-build als rbenv-Plugin

<syntaxhighlight lang=shell>
git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build
</syntaxhighlight>

Nun kann die benötigte Ruby-Version installiert werden:

<syntaxhighlight lang=shell>
rbenv install 2.4
</syntaxhighlight>

== Installation von Discourse selber ==

Weiterhin Als User ''xyz00-discourse'':

<syntaxhighlight lang=shell>
cd ~
git clone https://github.com/discourse/discourse.git discourse
cd ~/discourse
</syntaxhighlight>

Die stabile Version auschecken:

<syntaxhighlight lang=shell>
git checkout stable
</syntaxhighlight>

Ruby Pakete installieren:

<syntaxhighlight lang=shell>
gem install bundler
bundle install -j$(getconf _NPROCESSORS_ONLN) --deployment --without development test
</syntaxhighlight>

== Konfiguration der Discourse Software ==

Anlegen einer Datei ''/home/pacs/xyz00/users/discourse/discourse/config/discourse.conf'' anhand der Beispiel-Datei:

<syntaxhighlight lang=shell>
cd ~/discourse
cp config/discourse_defaults.conf config/discourse.conf
</syntaxhighlight>

Anpassen folgender Inhalte:
<syntaxhighlight lang=ini line>
db_host = 127.0.0.1
db_port = 5432
#db_backup_port = 5432 #(auskommentieren)
db_name = xyz00_discoursedb
db_username = xyz00_discourseuser
db_password = "" #db password
hostname = "discourse.xyz00" # hostname
smtp_address = localhost
smtp_enable_start_tls = false
smtp_openssl_verify_mode = 'none'
developer_emails = # your email-address
redis_host = 127.0.0.1
redis_port = 32002
</syntaxhighlight>
===TODO: Secrets setzen! ===
Die Zufallswerte für die Variablen SECRET_KEY_BASE und OTP_SECRET erzeugt man durch zwei Aufrufe des Kommandos

<syntaxhighlight lang=shell>
RAILS_ENV=production bundle exec rake secret
</syntaxhighlight>

=== Sidekiq für Hintergrund-Aufgaben konfigurieren ===

''config/sidekiq.conf''

Wichtig: development auf production ändern.

Mit diesem Dienst werden z.B. die E-Mails zur Aktivierung oder zum Passwort Reset verschickt.

=== Problem mit Content Security Policy ===

Um ein Problem mit Content Security Policy zu lösen, weil manche Dateien über http nachgeladen werden, muss in der Datei <code>config/site_settings.yml</code> der Default Wert für force_https auf True gesetzt werden:
<syntaxhighlight lang=yaml line>
force_https:
default: true
</syntaxhighlight>
=== Problem beim Aufsetzen der Datenbank vermeiden ===

'''→ Notiz Mai 2024:''' dies scheint aktuell nicht aufzutreten.

Aus irgendeinem Grund wird beim Initialisieren der Datenbank versucht, den TYPE hotlinked_media_status zweimal in der Datenbank anzulegen. Der Grund ist nicht ersichtlich.

Es kann folgende Änderung an der Datei <code>db/migrate/20220428094026_create_post_hotlinked_media.rb</code> vorgenommen werden:
<syntaxhighlight lang=ruby line>
reversible do |dir|
dir.up { execute <<~SQL }
DO $$ BEGIN CREATE TYPE hotlinked_media_status AS ENUM('downloaded', 'too_large', 'download_failed', 'upload_create_failed'); EXCEPTION WHEN duplicate_object THEN null; END $$;
SQL
dir.down { execute <<~SQL }
DROP TYPE hotlinked_media_status
SQL
end
</syntaxhighlight>
=== Initialisieren der Datenbank ===

<syntaxhighlight lang=shell>
export SAFETY_ASSURED=1
# In Version 2.0.4 funktioniert db:migrate noch, ansonsten db:schema:load und seed nutzen!
# In Version 3.0.3 funktioniert db:migrate auch noch, db:schema:load ging nicht weil die Datei structure.sql fehlte
#RAILS_ENV=production bundle exec rails db:schema:load
#RAILS_ENV=production bundle exec rails db:seed
RAILS_ENV=production bundle exec rails db:migrate
</syntaxhighlight>

=== Kompilieren der Assets ===

<syntaxhighlight lang=shell>
RAILS_ENV=production bundle exec rails assets:precompile
</syntaxhighlight>

=== Konfiguration des Web-Servers (am Beispiel Puma) ===

Die Datei ''config/puma.conf'' anpassen (hier nur Änderungen angezeigt):

<syntaxhighlight lang=ini>
APP_ROOT = '/home/pacs/xyz00/users/discourse/discourse'
daemonize false
</syntaxhighlight>

== Starten der Dienste ==

Zum Start aller notwendigen Dienste sollte systemd benutzt werden.

Die folgenden Dateien müssen nach <code>.config/systemd/user/</code> kopiert werden (überlange Zeilen werden hier im Wiki umgebrochen)

redis.service:

<syntaxhighlight lang=ini line>
[Unit]
Description=Redis User Service

[Service]
WorkingDirectory=%h/var/redis
Environment="PATH=/usr/local/bin:/usr/bin:/bin"
ExecStart=%h/bin/redis-server %h/etc/redis.conf
Restart=always
PrivateTmp=true
NoNewPrivileges=true

[Install]
WantedBy=default.target
</syntaxhighlight>

sidekiq.service:

<syntaxhighlight lang=ini line>
[Unit]
Description=Discourse Sidekiq Service

[Service]
WorkingDirectory=%h/discourse
Environment="PATH=/usr/local/bin:/usr/bin:/bin"
Environment="RAILS_ENV=production"
Environment="DB_POOL=8"
Environment="MALLOC_ARENA_MAX=2"
ExecStart=%h/.rbenv/shims/bundle exec sidekiq -C %h/discourse/config/sidekiq.yml
StandardOutput=append:%h/var/log/sidekiq.out.log
StandardError=inherit
Restart=always
PrivateTmp=true
NoNewPrivileges=true

[Install]
WantedBy=default.target
After=redis.service
</syntaxhighlight>

discourse.service:

<syntaxhighlight lang=ini line>
[Unit]
Description=Discourse Web Service

[Service]
WorkingDirectory=%h/discourse
Environment="PATH=/usr/local/bin:/usr/bin:/bin"
Environment="RAILS_ENV=production"
Environment="WEB_CONCURRENCY=2"
Environment="MAX_THREADS=5"
Environment="MALLOC_ARENA_MAX=2"
ExecStart=%h/.rbenv/shims/bundle exec puma -C config/puma.rb -e production -b tcp://127.0.0.1:13000
StandardOutput=append:%h/var/log/puma.out.log
StandardError=inherit
Restart=always
PrivateTmp=true
NoNewPrivileges=true

[Install]
WantedBy=default.target
After=redis.service
</syntaxhighlight>

== Einrichten des Apache VHost ==

<syntaxhighlight lang=shell>
cd ~/doms/beispiel.discuss
rm -rf htdocs-ssl subs/www subs-ssl/www
ln -s ~/live/public htdocs-ssl
touch htdocs-ssl/.htaccess
</syntaxhighlight>

Dann die ''htdocs-ssl/.htaccess'' (durch das gelinkte Verzeichnis entspricht das dem Pfad /home/pacs/xyz00/users/discourse/discourse/public/.htaccess ) mit dem Editor der Wahl öffnen und folgende Konfiguration einfügen:

<syntaxhighlight lang=apache line>
DirectoryIndex disabled

RequestHeader set X-Forwarded-Proto "https"

RewriteEngine On
RewriteBase /
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-l
RewriteRule .* http://127.0.0.1:13000%{REQUEST_URI} [proxy,last]
</syntaxhighlight>
== Wartung ==
=== Backup ===

Discourse macht selbstätig backups und legt diese unter 'public/backups' ab. Enthalten ist ein Datenbank-Dump und die hochgeladenen Dateien.

Im Admin-Bereich lassen sich backups auch manuell antreten.

=== Admin Benutzer einladen ===

Manchmal brauchen wir einen neuen Admin Benutzer, den wir von der Kommandozeile aus einladen möchten.

<syntaxhighlight lang=shell>
cd /discourse
RAILS_ENV=production rake admin:invite[admin@example.org]
</syntaxhighlight>

=== Import aus mbox Archiven ===

Um zum Beispiel ein Mailman2 Archiv zu importieren, wo die Nachrichten als .mbox Datei vorliegen, sind folgende Schritte nötig:

Vorbereitungen an Discourse:

<syntaxhighlight lang=shell>
source .profile
cd discourse
bundle config set frozen false
IMPORT=1 bundle install
bundle config set frozen true
nano script/import_scripts/mbox/settings.yml
# dort ändern:
# data_dir: /home/pacs/xyz00/users/discourse/list-archiv
</syntaxhighlight>

Hochladen der Mailinglisten-Archive:
<syntaxhighlight lang=shell>
mkdir ~/list-archiv
# dort muss es Unterordner mit dem Namen der gewünschten Kategorie geben,
# und die mbox Datei muss auch diesen Namen haben, z.B.:
# ~/list-archiv/beispiel/beispiel.mbox
# ~/list-archiv/example/example.mbox
# um die Beiträge in den entsprechenden Kategorien beispiel und example einzufügen.
</syntaxhighlight>

Durchführen des Imports:
<syntaxhighlight lang=shell>
source .profile
cd discourse
RAILS_ENV=production IMPORT=1 bundle exec rails runner \
script/import_scripts/mbox.rb script/import_scripts/mbox/settings.yml
</syntaxhighlight>

=== Export ===
* Wenn ein Forum beendet wird, möchte man evtl. eine Sicherung als statische HTML Seiten.
** Das wird hier diskutiert: https://meta.discourse.org/t/how-do-i-export-the-complete-forum-as-static-html-pages/71007/3
* Um ein Forum von Discourse zu Flarum umzuziehen, hat Timotheus ein Skript geschrieben.
** Das Migrations-Skript: https://github.com/SolidCharity/discourse_to_flarum
** siehe auch https://discuss.flarum.org/d/4930-discourse-to-flarum-migration-support/29

=== Updates ===

Discourse wird über update via mail informieren (dies kann man m.W. abschalten).

Achtung: bei größeren Updates auch immer Änderungen an der Datei site_settings.yml (https://github.com/discourse/discourse/blob/main/config/site_settings.yml) beachten!

Siehe auch die unterstützten Releases: https://releases.discourse.org/ und die Tags: https://github.com/discourse/discourse/tags

==== Am Beispiel von 2026.1.1 auf 2026.1.3 ====

# Im Web-Backend unter Administration->Backups-> Read-Only Mouds setzen (oder Web Server so konfigurieren, dass keine Zugriffe mehr stattfinden können)
# Backup
# Die lokalen Änderungen sichern:
# cd discourse
# mv ~/plugins.bak/discourse-ai plugins
# git diff v2026.1.1 > diff-2026.1.1.txt
# git fetch
# git checkout -b hostsharing-deployment-v2026.1.3 v2026.1.3
# evtl. Änderungen aus diff-2026.1.1.txt wieder übernehmen und committen
# patch -p1 < diff-2026.1.1.txt
# git commit -a -m "spezifische Änderungen für diese Instanz" --no-verify
# Schauen, ob discourse eine neue Ruby-Version nutzt (z.B. in https://github.com/discourse/discourse_docker/blob/main/image/base/Dockerfile bzw. https://github.com/discourse/discourse/blob/v2026.1.3/Gemfile)
# Ist dies der Fall, dann:
# rbenv install 3.3.8
# rbenv global 3.3.8
# rbenv rehash
# echo "3.3.8" > .ruby-version
# installiere Node 22: https://codeberg.org/tpokorra/hostsharing-scripts/src/branch/main/install-nodejs.sh
# source ~/.profile
# gem update --system
# bundle install
# npm install -g terser uglify-js pnpm@10
# corepack use pnpm@latest-10
# pnpm install
# export $(grep -v '^#' ~/discourse.env | xargs -d '\n')
# source ~/.profile
# wir haben keine pg extension pg_vector, daher deaktivieren wir das Plugin während migrate, aber auch für später damit /admin/settings funktioniert:
# mkdir -p ~/plugins.bak
# mv plugins/discourse-ai ~/plugins.bak
# RAILS_ENV=production bundle exec rake db:migrate
# RAILS_ENV=production bundle exec rake assets:precompile
# Services neu starten
<syntaxhighlight lang=shell>
systemctl --user restart puma
systemctl --user restart sidekiq
systemctl --user restart redis
</syntaxhighlight>
* Zuletzt: Read-Only Modus wieder deaktivieren

=== Debugging ===

Es können folgende Einstellungen in der Datei config/environments/production.rb vorgenommen werden. Danach den Puma Dienst neustarten. Fehlermeldungen und Stacktraces werden dann im Browser ausgegeben.

<syntaxhighlight lang="ini" line>
config.log_level = :debug
config.action_dispatch.show_exceptions = :all
config.action_dispatch.debug_exception_log_level = :error

# Full error reports are enabled and caching is turned off
config.consider_all_requests_local = true
config.action_controller.perform_caching = false
</syntaxhighlight>

=== Erforderliche Anpassungen ===
Weil wir bei Debian Bookworm noch mit ImageMagick 6.9 arbeiten, muss dieser [https://github.com/discourse/discourse/commit/17aa831337e352dfd875f1b4ddc4492bd0835119 Patch] rückgängig gemacht werden:

<syntaxhighlight lang="bash" line>
wget https://github.com/discourse/discourse/commit/17aa831337e352dfd875f1b4ddc4492bd0835119.patch -O ~/imagemagick.patch
patch -p1 --reverse < ~/imagemagick.patch
git commit -a -m "revert imagemagick patch" --no-verify
</syntaxhighlight>

== ToDos ==

* Ein Patch, um Discourse auch via Unix-Socket mit Redis sprechen lassen zu können dürfte relativ einfach sein (es wird ein Wrapper um das redis-gem genutzt).
* Konfiguration von discourse, um mit postgresql via Unix-Socket zu kommunizieren (DISCOURSE_DB_SOCKET environment variable)
* Performance-tuning an diversen Stellen, anhand der discourse_docker-Vorgaben (https://github.com/discourse/discourse_docker), z.B.
** thpoff (huge page settings)
** unicorn (hat eine wesentlich ausgefeiltere Konfigurations-Vorlage, wahrscheinlich bereits ordentlich optimiert)

== Links ==

* https://help.skysilk.com/support/solutions/articles/9000120927-how-to-install-discourse-without-docker-using-skysilk-vps-
* https://github.com/discourse/discourse_docker
* https://github.com/discourse/discourse
* https://codeberg.org/tpokorra/hs.ansible/src/branch/main/playbooks/discourse

== Historie ==

* 2018, 14 . September: Initiale Fassung
* 2019, Januar: Update-Informationen ergänzt
* 2022, Juni: systemd Dienste, Discourse 3.0

----
[[Kategorie:HSDoku]]
[[Kategorie:Installationsanleitungen]]
[[Kategorie:RubyOnRails]]
[[Kategorie:Webforen]]
[[Kategorie:Ansible Playbook]]

Collabora Online

2026-03-14T04:51:44Z

Tim00: /* Empfohlene Hardwareausrüstung */

= Collabora installieren =

== Empfohlene Hardwareausrüstung ==

siehe auch https://sdk.collaboraonline.com/docs/installation/Configuration.html#performance

Wir konfigurieren nun Collabora Online so, dass die Anzahl der verfügbaren CPUs automatisch berücksichtigt wird.

== Vorbereitungen ==

Voraussetzungen sind folgende Punkte:

1. Per Mail an service@hostsharing.net die Aktivierung der Paket Option Collabora Online beauftragen mit der Angabe des Paketkürzel xyz00 und des Benutzers xyz00-cloud unter der die Installation läuft.

2. Grundlage bei Hostsharing ist die Installation der Nextcloud laut Wiki Anleitung [[Nextcloud]].

3. Die APP ''Nextcloud Office'' erst installieren wenn der Service die Bestätigung gesendet hat, dass die Aktivierung erfolgt ist. Hinweis: Bei der Nextcloud-Installation wird ''Nextcloud Office'' u.U. automatisch mit installiert. In diesem Fall ist es notwendig, die App zunächst zu deaktivieren: als Admin im Profilmenü "+ Apps" öffnen und sie dort unter "Aktive Apps" deaktivieren.

== Collabora installieren ==

Collabora ist auf allen 64 Bit hive installiert. Es muss hier nun noch die APP Collabora Online in der Nextcloud installiert werden.

'''WICHTIG:''' Die Freigabe vom Service muss erst per Mail vorliegen!!

1. Anmeldung als '''Admin''' in der Nextcloud Installation

2. Rechts oben auf '''Profilmenü''' den Eintrag '''+APP''' auswählen
[[Datei:Hs-collabora-app-install.jpg|300px]]

3. Im '''Suchfeld''' oben "Nextcloud Office" eingeben
[[Datei:Nextcloud-Office-Suche.png|600px]]

4. Auf den Button ''Herunterladen und aktivieren'' klicken

Damit ist die APP Nextcloud Office installiert und muss nun noch konfiguriert werden.

== Collabora konfigurieren ==

Rechts oben unter '''Profilmenü''' den Eintrag '''Einstellungen''' auswählen.

Anschließend im linken Fensterbereich unter dem Menüpunkt '''Verwaltung'''
den Eintrag '''Collabora Online''' auswählen.

[[Bild:Nextcloud-Office-Menue.png|300px]]

Hier muss nun die PaketDomain entsprechend Eingetragen werden.
Wobei '''xyz00'''.hostsharing.net durch Ihr Paket Kürzel zu ersetzten ist.
Es wird kein Port eingetragen!
Anschließend einmal auf den Button ''Anwenden'' klicken.
[[Bild:Nextcloud-Office-URL.png|600px]]

Es wird empfohlen bei 'Allow list for WOPI requests' die aufgelöste IP Adresse des Webpaketes xyz00.hostsharing.net einzutragen. Sodass nur diese Collabora Instanz Dokumente aus der Nextcloud erhalten kann. Die IP erhält man z.B. über den Konsolenbefehl

<syntaxhighlight lang=shell>
dig xyz00.hostsharing.net
</syntaxhighlight>

Die Relevante Zeile im Output sieht ungefähr so aus:

<syntaxhighlight lang=output line>
;; ANSWER SECTION:
xyz00.hostsharing.net. 3807 IN A 83.223.79.177
</syntaxhighlight>

Die IP Adresse ist die, die dann auch in der Nextcloud auf der Admin Config Seite von Collabora hinterlegt werden muss.

Weitere Einstellungen können individuell noch vorgenommen werden.

----
[[Kategorie:HSDoku]]
[[Kategorie:Installationsanleitungen]]
[[Kategorie:Software]]

ImapCopy

2026-03-13T14:56:56Z

Tim00: /* Config Web.de -> HS Benutzer */

== ImapCopy ==

ImapCopy ist ein Werkzeug, mit dem man ein komplettes IMAP-Postfach in ein IMAP-Postfach auf einem anderen Server (bei einem anderen Anbieter) kopieren kann. Wir verwenden es für die Migration von Postfächern. Eine Alternative ist [[OfflineIMAP]].

== Installation ImapCopy ==

ImapCopy ist auf den HS Hives schon installiert

== Einrichtung allgemein ==

Anmelden per ssh als ein Benutzer in einem HS-Paket.

<syntaxhighlight lang="bash">
xyz00-imapcopy@h01:~$
</syntaxhighlight>

Dort wird ein Arbeitsverzeichnis erstellt

<syntaxhighlight lang="bash">
xyz00-imapcopy@h01:~$ mkdir imapcopy
xyz00-imapcopy@h01:~$ cd imapcopy
</syntaxhighlight>

Die Konfiguration wird in einer Datei ImapCopy.cfg gespeichert

<syntaxhighlight lang="bash">
xyz00-imapcopy@h01:~/imapcopy$ vi ImapCopy.cfg
</syntaxhighlight>

=== Config Web.de -> HS Benutzer ===

Muster Inhalt der Datei ImapCopy.cfg

<syntaxhighlight lang="bash" line>
#############################################################
# imapcopy config
# all lines beginning with # are comments and will be ignored
#############################################################

##############
# Sourceserver
##############
#SourceServer imap.web.de
#SourcePort 143
SourceServer 127.0.0.1
SourcePort 10143

###################
# Destinationserver
###################
#DestServer xyz00.hostsharing.net
#DestPort 143
DestServer 127.0.0.1
DestPort 20143

#########
# Options
#########
#
# DebugSrc and DebugDest will show all traffic between IMAPCopy and Server
#
#DebugSrc
#DebugDst

#################
# Folders to skip
#################
#skipfolder INBOX.Trash
#skipfolder INBOX.Sent
#skipfolder "INBOX.Sent Objects"

#################
# Folders to copy
#################
#copyfolder INBOX
#copyfolder "INBOX.My personal files"
#copyfolder INBOX.Net-Connection.dy
#copyfolder INBOX.test

#######################################################
# Rootfolder
# Can be specified to copy the Folder-Structure under
# a separate folder instead of inbox
#######################################################
#DstRootFolder "Your old Mails"

###############################################################
# Specify Flags that are supported on the destination server
# (AllowFlags) or flags that should be filtered out (DenyFlags)
# If not specified, all Flags are copyied 1:1
# If AllowFlags is specified, all not specified Flags will be
# removed and not copied to the destination
# If DenyFlags is specified, those flags will be removed and
# the remaining ones will be copied
# Both (AllowFlags and DenyFlags) could be specified but
# would (in most cases) make no sense
##############################################################
#AllowFlags "\Seen\Answered\Flagged\Deleted\Draft Junk NonJunk $MDNSent $Forwared"
DenyFlags "\Recent"

##############################################################
# Timezone conversion
# The imap rfc is not clear on what kind of time offsets
# can be used. +XXXX -XXXX will be supported on all servers
# You can add as many entries as needed in the form
# converttimezone SRC DST
# to convert zones that your target server rejects
##############################################################
converttimezone "UTC" "+0000"
converttimezone "UT" "+0000"

#############################
# List of users and passwords
#############################
# SourceUser SourcePassword DestinationUser DestinationPassword
Copy "xyz@web.de" "Euer-Passwort" "xyz00-imap" "Benutzer-Passwort"
</syntaxhighlight>

=== Config gmail.com -> HS Benutzer ===

Da ImapCopy nicht direkt SSL unterstützt benötigt z.b. gmail und ggf einige andere die weiter unten beschrieben Lösung mit einem stunnel.

== Testen einer Verbindung ==

Zum testen ob die Daten alle OK sind auf der shell einfach:

<syntaxhighlight lang="bash">
xyz00-imapcopy@h01:~/imapcopy$ imapcopy -t
</syntaxhighlight>

eingeben.

== Daten austauschen ==

Wir empfehlen: Benutze eine <code>screen</code> Sitzung, damit die Übertragung nicht durch einen Verbindungsabbruch durcheinander kommt!

<syntaxhighlight lang="bash">
xyz00-imapcopy@h01:~/imapcopy$ screen
xyz00-imapcopy@h01:~/imapcopy$ imapcopy
</syntaxhighlight>

== Hilfe ==

<syntaxhighlight lang="bash">
xyz00-imapcopy@h01:~/imapcopy$ imapcopy -h
xyz00-imapcopy@h01:~/imapcopy$ man imapcopy
</syntaxhighlight>

== Python Skript zur Massenverarbeitung ==

Wenn viele Postfächer umgezogen werden sollen, ist es hilfreich, wenn die Befehle und die Passwörter generiert werden können.

Dafür haben wir ein Python-Skript, das in diesem Repository zur Verfügung steht:
* [https://codeberg.org/tpokorra/hostsharing-scripts/src/branch/main/create_and_move_mailboxes.py create_and_move_mailboxes.py]
* mit einer entsprechenden Konfigurations-Datei: [https://codeberg.org/tpokorra/hostsharing-scripts/src/branch/main/create_and_move_mailboxes_config-sample.py create_and_move_mailboxes_config-sample.py]

In der Konfigurations-Datei werden die Postfächer mit E-Mail-Adresse und Aliasen, und die Verteiler konfiguriert.

Die Passwörter werden nur einmal generiert, und in einer sqlite Datenbank gespeichert.

<syntaxhighlight lang="bash" line>
# dem Kunden die neuen Passwörter mitteilen:
ACTION=info python3 create_and_move_mailboxes.py
# Anweisungen in hsscript ausführen:
ACTION=hsadmin python3 create_and_move_mailboxes.py
# Anweisungen in ImapCopy einfügen:
ACTION=imapcopy python3 create_and_move_mailboxes.py
</syntaxhighlight>

== ssl via stunnel ==

Es wird eine Konfuguration Datei , hier stunnel-to-gmail.conf, benötigt.

<syntaxhighlight lang="bash">
xyz00-imapcopy@h01:~/imapcopy$ vi stunnel-to-gmail.conf
</syntaxhighlight>

Inhalt der Datei stunnel-to-gmail.conf:

<syntaxhighlight lang="ini" line>
foreground=yes

; Some performance tunings
socket = l:TCP_NODELAY=1
socket = r:TCP_NODELAY=1

; Some debugging stuff useful for troubleshooting
debug = 7

; Pfad for pid file
pid = /tmp/stunnel4-xyz00.pid

; Use it for client mode
client = yes

; Service-level configuration

[imap]
accept = 127.0.0.1:10143
connect = imap.gmail.com:993
retry = yes

[imap]
accept = 127.0.0.1:20143
connect = xyz00.hostsharing.net:993
retry = yes
</syntaxhighlight>

=== Änderung in der ImapCopy.cfg ===

<syntaxhighlight lang="ini" line>
##############
# Sourceserver
##############
SourceServer 127.0.0.1
SourcePort 10143

###################
# Destinationserver
###################
DestServer 127.0.0.1
DestPort 20143

#############################
# List of users and passwords
#############################
# SourceUser SourcePassword DestinationUser DestinationPassword
Copy "xyz@gmail.com" "passwort" "xyz00-imap" "passwort"
</syntaxhighlight>

=== stunnel aufbauen ===

Wir öffnen eine zweite Shell, starten dort screen, um kein Problem bei Verbindungsabbrüchen zu haben, und starten dann den stunnel:

<syntaxhighlight lang="bash" line>
xyz00-imapcopy@h01:~/imapcopy$ screen
xyz00-imapcopy@h01:~/imapcopy$ stunnel4 stunnel-to-gmail.conf
</syntaxhighlight>

=== Verbindung prüfen und herstellen ===

Siehe -> Testen einer Verbindung
und -> Daten austauschen

[[Kategorie:HSDoku]]
[[Kategorie:Installationsanleitungen]]
[[Kategorie:Glossar]]
[[Kategorie:Software]]
[[Kategorie:E-Mail]]

Speicherbelegung

2026-03-12T14:13:58Z

Tim00: /* Unvermutete Speicherbelegung */

Discourse installieren

2026-03-12T05:28:00Z

Tim00: /* Am Beispiel von 2025.12.0 auf 2026.1.1 */

{{Textkasten|gelb|Für Managed Server|Ein funktionierender Discourse-Server erfordert mehrere laufende Server-Dienste. Für den Betrieb ist ein Managed Server sinnvoll.}}

{{Textkasten|rot|Support von der Discourse-Community|Die Discourse-Entwickler haben sich entschieden, nur eine mehr oder weniger genormte Installationsmethode (via docker) zu unterstützen. Dies ist so auf der hostsharing-Architektur aufgrund mehrerer Bedenken und Überlegungen nicht möglich. Die Community ist durchaus hilfreich, geht aber davon aus, dass quasi alle Nutzer* eine "supported"e Installation durchgeführt haben. Wenn man in entsprechenden Kanälen nach Hilfe fragt, sollte man unbedingt erwähnen, dass man discourse selber anhand dieser hier lesbaren Anleitung installiert hat, um bereits entsprechenden Kommentaren und Nachfragen vorzugreifen.}}

== Über ==

In diesem Artikel wird die Installation von discourse, Version 2.1.0 (September 2018) beschrieben.

== Vorbereitungen ==

Mit Hilfe von HSAdmin wird angelegt:
# Ein User als Service-User mit ''/bin/bash'' als Shell, zum Beispiel Beispiel: ''xyz00-discourse''
# Eine Domain mit ''xyz00-discourse' als Domain-Administrator, zum Beispiel ''beispiel.discussion''
# Einen Postgresql-User ''xyz00_discourseuser'' mit Passwort ''meinPasswort''
# Eine Postgresql-Datenbank ''xyz00_discoursedb'' mit Datenbank-Owner ''xyz00_discourseuser''

Verwendete IP-Ports der Server-Dienste:
# Redis: localhost:32002
# Discourse-Web: localhost:13000

== Konfiguration der PostgreSQL Datenbank ==

Es müssen noch Erweiterungen für Postgresql installiert werden:

<syntaxhighlight lang=shell line>
psql --user xyz00_discourseuser -c "CREATE EXTENSION IF NOT EXISTS hstore WITH SCHEMA public;"
psql --user xyz00_discourseuser -c "CREATE EXTENSION IF NOT EXISTS pg_trgm WITH SCHEMA public;"
psql --user xyz00_discourseuser -c "CREATE EXTENSION IF NOT EXISTS unaccent WITH SCHEMA public;"
</syntaxhighlight>

== Konfiguration des Redis Server ==

{{Textkasten|gelb|Firewall/Redis Port|Leider unterstützt discourse nicht die Kommunikation mit Redis über Unix-Sockets. Dementsprechend muss der für Redis konfigurierte Port von dem hostsharing-Support in der Firewall freigegeben werden.}}

<syntaxhighlight lang=shell>
cd
mkdir redis/etc redis/lib redis/log redis/run
</syntaxhighlight>

Anlegen einer Datei ''/home/pacs/xyz00/users/discourse/redis/etc/redis.conf'' mit folgendem Inhalt:

<syntaxhighlight lang=shell line>
daemonize no
pidfile /home/pacs/xyz00/users/discourse/redis/run/redis-server.pid
port 32002
tcp-backlog 128
bind 127.0.0.1
timeout 300
loglevel notice
logfile /home/pacs/xyz00/users/discourse/redis/log/redis.log
databases 16
save 900 1
save 300 10
save 60 10000
slave-serve-stale-data yes
appendonly no
dbfilename dump.rdb
dir /home/pacs/xyz00/users/discourse/redis/lib
</syntaxhighlight>

Für Discourse 3.x gilt: "Discourse requires Redis 6.2.0 or up"

Für Debian Buster und Bullseye ist daher das Installieren eines neueren Binaries erforderlich. Bei Debian Bookwork ist bereits Redis 7.0 enthalten (siehe https://packages.debian.org/search?keywords=redis-server).

Hier steht ein entsprechendes Binary für Debian Buster zur Verfügung, das mit dem Public Key von Timotheus geprüft werden kann:

* https://download.solidcharity.com/tarballs/tpokorra/hostsharing/redis-server-6.2.12-debian-buster.tar.gz
* Prüfsignatur: https://download.solidcharity.com/tarballs/tpokorra/hostsharing/redis-server-6.2.12-debian-buster.tar.gz.sig

Prüfen der Signatur:

<syntaxhighlight lang=shell>
gpg --verify redis-server-6.2.12-debian-buster.tar.gz.sig redis-server-6.2.12-debian-buster.tar.gz
</syntaxhighlight>

Das Binary muss nach <code>$HOME/bin</code> verschoben werden, und entsprechend beim Starten des Dienstes eingetragen werden.

== Installation von Ruby ==

Als User ''xyz00-discourse'': Installation von Ruby mit ''rbenv'' mit folgenden Befehlen:

Zunächst ''rbenv'' and ''ruby-build'':

<syntaxhighlight lang=shell line>
git clone https://github.com/rbenv/rbenv.git ~/.rbenv
cd ~/.rbenv && src/configure && make -C src
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.profile
echo 'eval "$(rbenv init -)"' >> ~/.profile
</syntaxhighlight>

starte neue Shell:

<syntaxhighlight lang=shell>
exec bash
</syntaxhighlight>

Überprüfe rbenv-Installation

<syntaxhighlight lang=shell>
type rbenv
</syntaxhighlight>

Installiere ruby-build als rbenv-Plugin

<syntaxhighlight lang=shell>
git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build
</syntaxhighlight>

Nun kann die benötigte Ruby-Version installiert werden:

<syntaxhighlight lang=shell>
rbenv install 2.4
</syntaxhighlight>

== Installation von Discourse selber ==

Weiterhin Als User ''xyz00-discourse'':

<syntaxhighlight lang=shell>
cd ~
git clone https://github.com/discourse/discourse.git discourse
cd ~/discourse
</syntaxhighlight>

Die stabile Version auschecken:

<syntaxhighlight lang=shell>
git checkout stable
</syntaxhighlight>

Ruby Pakete installieren:

<syntaxhighlight lang=shell>
gem install bundler
bundle install -j$(getconf _NPROCESSORS_ONLN) --deployment --without development test
</syntaxhighlight>

== Konfiguration der Discourse Software ==

Anlegen einer Datei ''/home/pacs/xyz00/users/discourse/discourse/config/discourse.conf'' anhand der Beispiel-Datei:

<syntaxhighlight lang=shell>
cd ~/discourse
cp config/discourse_defaults.conf config/discourse.conf
</syntaxhighlight>

Anpassen folgender Inhalte:
<syntaxhighlight lang=ini line>
db_host = 127.0.0.1
db_port = 5432
#db_backup_port = 5432 #(auskommentieren)
db_name = xyz00_discoursedb
db_username = xyz00_discourseuser
db_password = "" #db password
hostname = "discourse.xyz00" # hostname
smtp_address = localhost
smtp_enable_start_tls = false
smtp_openssl_verify_mode = 'none'
developer_emails = # your email-address
redis_host = 127.0.0.1
redis_port = 32002
</syntaxhighlight>
===TODO: Secrets setzen! ===
Die Zufallswerte für die Variablen SECRET_KEY_BASE und OTP_SECRET erzeugt man durch zwei Aufrufe des Kommandos

<syntaxhighlight lang=shell>
RAILS_ENV=production bundle exec rake secret
</syntaxhighlight>

=== Sidekiq für Hintergrund-Aufgaben konfigurieren ===

''config/sidekiq.conf''

Wichtig: development auf production ändern.

Mit diesem Dienst werden z.B. die E-Mails zur Aktivierung oder zum Passwort Reset verschickt.

=== Problem mit Content Security Policy ===

Um ein Problem mit Content Security Policy zu lösen, weil manche Dateien über http nachgeladen werden, muss in der Datei <code>config/site_settings.yml</code> der Default Wert für force_https auf True gesetzt werden:
<syntaxhighlight lang=yaml line>
force_https:
default: true
</syntaxhighlight>
=== Problem beim Aufsetzen der Datenbank vermeiden ===

'''→ Notiz Mai 2024:''' dies scheint aktuell nicht aufzutreten.

Aus irgendeinem Grund wird beim Initialisieren der Datenbank versucht, den TYPE hotlinked_media_status zweimal in der Datenbank anzulegen. Der Grund ist nicht ersichtlich.

Es kann folgende Änderung an der Datei <code>db/migrate/20220428094026_create_post_hotlinked_media.rb</code> vorgenommen werden:
<syntaxhighlight lang=ruby line>
reversible do |dir|
dir.up { execute <<~SQL }
DO $$ BEGIN CREATE TYPE hotlinked_media_status AS ENUM('downloaded', 'too_large', 'download_failed', 'upload_create_failed'); EXCEPTION WHEN duplicate_object THEN null; END $$;
SQL
dir.down { execute <<~SQL }
DROP TYPE hotlinked_media_status
SQL
end
</syntaxhighlight>
=== Initialisieren der Datenbank ===

<syntaxhighlight lang=shell>
export SAFETY_ASSURED=1
# In Version 2.0.4 funktioniert db:migrate noch, ansonsten db:schema:load und seed nutzen!
# In Version 3.0.3 funktioniert db:migrate auch noch, db:schema:load ging nicht weil die Datei structure.sql fehlte
#RAILS_ENV=production bundle exec rails db:schema:load
#RAILS_ENV=production bundle exec rails db:seed
RAILS_ENV=production bundle exec rails db:migrate
</syntaxhighlight>

=== Kompilieren der Assets ===

<syntaxhighlight lang=shell>
RAILS_ENV=production bundle exec rails assets:precompile
</syntaxhighlight>

=== Konfiguration des Web-Servers (am Beispiel Puma) ===

Die Datei ''config/puma.conf'' anpassen (hier nur Änderungen angezeigt):

<syntaxhighlight lang=ini>
APP_ROOT = '/home/pacs/xyz00/users/discourse/discourse'
daemonize false
</syntaxhighlight>

== Starten der Dienste ==

Zum Start aller notwendigen Dienste sollte systemd benutzt werden.

Die folgenden Dateien müssen nach <code>.config/systemd/user/</code> kopiert werden (überlange Zeilen werden hier im Wiki umgebrochen)

redis.service:

<syntaxhighlight lang=ini line>
[Unit]
Description=Redis User Service

[Service]
WorkingDirectory=%h/var/redis
Environment="PATH=/usr/local/bin:/usr/bin:/bin"
ExecStart=%h/bin/redis-server %h/etc/redis.conf
Restart=always
PrivateTmp=true
NoNewPrivileges=true

[Install]
WantedBy=default.target
</syntaxhighlight>

sidekiq.service:

<syntaxhighlight lang=ini line>
[Unit]
Description=Discourse Sidekiq Service

[Service]
WorkingDirectory=%h/discourse
Environment="PATH=/usr/local/bin:/usr/bin:/bin"
Environment="RAILS_ENV=production"
Environment="DB_POOL=8"
Environment="MALLOC_ARENA_MAX=2"
ExecStart=%h/.rbenv/shims/bundle exec sidekiq -C %h/discourse/config/sidekiq.yml
StandardOutput=append:%h/var/log/sidekiq.out.log
StandardError=inherit
Restart=always
PrivateTmp=true
NoNewPrivileges=true

[Install]
WantedBy=default.target
After=redis.service
</syntaxhighlight>

discourse.service:

<syntaxhighlight lang=ini line>
[Unit]
Description=Discourse Web Service

[Service]
WorkingDirectory=%h/discourse
Environment="PATH=/usr/local/bin:/usr/bin:/bin"
Environment="RAILS_ENV=production"
Environment="WEB_CONCURRENCY=2"
Environment="MAX_THREADS=5"
Environment="MALLOC_ARENA_MAX=2"
ExecStart=%h/.rbenv/shims/bundle exec puma -C config/puma.rb -e production -b tcp://127.0.0.1:13000
StandardOutput=append:%h/var/log/puma.out.log
StandardError=inherit
Restart=always
PrivateTmp=true
NoNewPrivileges=true

[Install]
WantedBy=default.target
After=redis.service
</syntaxhighlight>

== Einrichten des Apache VHost ==

<syntaxhighlight lang=shell>
cd ~/doms/beispiel.discuss
rm -rf htdocs-ssl subs/www subs-ssl/www
ln -s ~/live/public htdocs-ssl
touch htdocs-ssl/.htaccess
</syntaxhighlight>

Dann die ''htdocs-ssl/.htaccess'' (durch das gelinkte Verzeichnis entspricht das dem Pfad /home/pacs/xyz00/users/discourse/discourse/public/.htaccess ) mit dem Editor der Wahl öffnen und folgende Konfiguration einfügen:

<syntaxhighlight lang=apache line>
DirectoryIndex disabled

RequestHeader set X-Forwarded-Proto "https"

RewriteEngine On
RewriteBase /
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-l
RewriteRule .* http://127.0.0.1:13000%{REQUEST_URI} [proxy,last]
</syntaxhighlight>
== Wartung ==
=== Backup ===

Discourse macht selbstätig backups und legt diese unter 'public/backups' ab. Enthalten ist ein Datenbank-Dump und die hochgeladenen Dateien.

Im Admin-Bereich lassen sich backups auch manuell antreten.

=== Admin Benutzer einladen ===

Manchmal brauchen wir einen neuen Admin Benutzer, den wir von der Kommandozeile aus einladen möchten.

<syntaxhighlight lang=shell>
cd /discourse
RAILS_ENV=production rake admin:invite[admin@example.org]
</syntaxhighlight>

=== Import aus mbox Archiven ===

Um zum Beispiel ein Mailman2 Archiv zu importieren, wo die Nachrichten als .mbox Datei vorliegen, sind folgende Schritte nötig:

Vorbereitungen an Discourse:

<syntaxhighlight lang=shell>
source .profile
cd discourse
bundle config set frozen false
IMPORT=1 bundle install
bundle config set frozen true
nano script/import_scripts/mbox/settings.yml
# dort ändern:
# data_dir: /home/pacs/xyz00/users/discourse/list-archiv
</syntaxhighlight>

Hochladen der Mailinglisten-Archive:
<syntaxhighlight lang=shell>
mkdir ~/list-archiv
# dort muss es Unterordner mit dem Namen der gewünschten Kategorie geben,
# und die mbox Datei muss auch diesen Namen haben, z.B.:
# ~/list-archiv/beispiel/beispiel.mbox
# ~/list-archiv/example/example.mbox
# um die Beiträge in den entsprechenden Kategorien beispiel und example einzufügen.
</syntaxhighlight>

Durchführen des Imports:
<syntaxhighlight lang=shell>
source .profile
cd discourse
RAILS_ENV=production IMPORT=1 bundle exec rails runner \
script/import_scripts/mbox.rb script/import_scripts/mbox/settings.yml
</syntaxhighlight>

=== Export ===
* Wenn ein Forum beendet wird, möchte man evtl. eine Sicherung als statische HTML Seiten.
** Das wird hier diskutiert: https://meta.discourse.org/t/how-do-i-export-the-complete-forum-as-static-html-pages/71007/3
* Um ein Forum von Discourse zu Flarum umzuziehen, hat Timotheus ein Skript geschrieben.
** Das Migrations-Skript: https://github.com/SolidCharity/discourse_to_flarum
** siehe auch https://discuss.flarum.org/d/4930-discourse-to-flarum-migration-support/29

=== Updates ===

Discourse wird über update via mail informieren (dies kann man m.W. abschalten).

Achtung: bei größeren Updates auch immer Änderungen an der Datei site_settings.yml (https://github.com/discourse/discourse/blob/main/config/site_settings.yml) beachten!

Siehe auch die unterstützten Releases: https://releases.discourse.org/ und die Tags: https://github.com/discourse/discourse/tags

==== Am Beispiel von 2025.12.0 auf 2026.1.1 ====

# Im Web-Backend unter Administration->Backups-> Read-Only Mouds setzen (oder Web Server so konfigurieren, dass keine Zugriffe mehr stattfinden können)
# Backup
# Die lokalen Änderungen sichern:
# cd discourse
# mv ~/plugins.bak/discourse-ai plugins
# git diff v2025.12.0 > diff-2025.12.0.txt
# git fetch
# git checkout -b hostsharing-deployment-v2026.1.1 v2026.1.1
# evtl. Änderungen aus diff-2025.12.0.txt wieder übernehmen und committen
# patch -p1 < diff-2025.12.0.txt
# git commit -a -m "spezifische Änderungen für diese Instanz" --no-verify
# Schauen, ob discourse eine neue Ruby-Version nutzt (z.B. in https://github.com/discourse/discourse_docker/blob/main/image/base/Dockerfile bzw. https://github.com/discourse/discourse/blob/v2026.1.1/Gemfile)
# Ist dies der Fall, dann:
# rbenv install 3.3.8
# rbenv global 3.3.8
# rbenv rehash
# echo "3.3.8" > .ruby-version
# installiere Node 22: https://codeberg.org/tpokorra/hostsharing-scripts/src/branch/main/install-nodejs.sh
# source ~/.profile
# gem update --system
# bundle install
# npm install -g terser uglify-js pnpm@10
# corepack use pnpm@latest-10
# pnpm install
# export $(grep -v '^#' ~/discourse.env | xargs -d '\n')
# source ~/.profile
# wir haben keine pg extension pg_vector, daher deaktivieren wir das Plugin während migrate, aber auch für später damit /admin/settings funktioniert:
# mkdir -p ~/plugins.bak
# mv plugins/discourse-ai ~/plugins.bak
# RAILS_ENV=production bundle exec rake db:migrate
# RAILS_ENV=production bundle exec rake assets:precompile
# Services neu starten
<syntaxhighlight lang=shell>
systemctl --user restart puma
systemctl --user restart sidekiq
systemctl --user restart redis
</syntaxhighlight>
* Zuletzt: Read-Only Modus wieder deaktivieren

=== Debugging ===

Es können folgende Einstellungen in der Datei config/environments/production.rb vorgenommen werden. Danach den Puma Dienst neustarten. Fehlermeldungen und Stacktraces werden dann im Browser ausgegeben.

<syntaxhighlight lang="ini" line>
config.log_level = :debug
config.action_dispatch.show_exceptions = :all
config.action_dispatch.debug_exception_log_level = :error

# Full error reports are enabled and caching is turned off
config.consider_all_requests_local = true
config.action_controller.perform_caching = false
</syntaxhighlight>

=== Erforderliche Anpassungen ===
Weil wir bei Debian Bookworm noch mit ImageMagick 6.9 arbeiten, muss dieser [https://github.com/discourse/discourse/commit/17aa831337e352dfd875f1b4ddc4492bd0835119 Patch] rückgängig gemacht werden:

<syntaxhighlight lang="bash" line>
wget https://github.com/discourse/discourse/commit/17aa831337e352dfd875f1b4ddc4492bd0835119.patch -O ~/imagemagick.patch
patch -p1 --reverse < ~/imagemagick.patch
git commit -a -m "revert imagemagick patch" --no-verify
</syntaxhighlight>

== ToDos ==

* Ein Patch, um Discourse auch via Unix-Socket mit Redis sprechen lassen zu können dürfte relativ einfach sein (es wird ein Wrapper um das redis-gem genutzt).
* Konfiguration von discourse, um mit postgresql via Unix-Socket zu kommunizieren (DISCOURSE_DB_SOCKET environment variable)
* Performance-tuning an diversen Stellen, anhand der discourse_docker-Vorgaben (https://github.com/discourse/discourse_docker), z.B.
** thpoff (huge page settings)
** unicorn (hat eine wesentlich ausgefeiltere Konfigurations-Vorlage, wahrscheinlich bereits ordentlich optimiert)

== Links ==

* https://help.skysilk.com/support/solutions/articles/9000120927-how-to-install-discourse-without-docker-using-skysilk-vps-
* https://github.com/discourse/discourse_docker
* https://github.com/discourse/discourse
* https://codeberg.org/tpokorra/hs.ansible/src/branch/main/playbooks/discourse

== Historie ==

* 2018, 14 . September: Initiale Fassung
* 2019, Januar: Update-Informationen ergänzt
* 2022, Juni: systemd Dienste, Discourse 3.0

----
[[Kategorie:HSDoku]]
[[Kategorie:Installationsanleitungen]]
[[Kategorie:RubyOnRails]]
[[Kategorie:Webforen]]
[[Kategorie:Ansible Playbook]]

Umzug aller Postfächer einer Domain

2026-03-10T17:24:03Z

Tim00: /* Szenario */

== Szenario ==

Das neue Mitglied hat bisher eine Domain und mehrere Postfächer bei einem Anbieter. Nun soll die Domain, die Webseite, die Postfächer und evtl. auch andere Anwendungen, z.B. eine Nextcloud, zu Hostsharing umgezogen werden.

Wir betrachten hier erstmal nur den Umzug der Postfächer und der E-Mail Adressen. Die weiteren Schritte können im Anschluss durchgeführt werden.

== Durchzuführende Schritte ==

=== Vorbereitungen an den Einstellungen der Domain ===
==== TTL heruntersetzen ====
Beim bisherigen Anbieter sollte die TTL auf dem MX Eintrag der Domain auf 600 Sekunden gesetzt werden (10 Minuten).
Das sollte spätestens einen Tag vor dem Umzug erledigt werden, um den Default-Wert der TTL von bis zu 24 Stunden zu vermeiden.
Dadurch wird die Zeitspanne verringert, in der während des Umzugs nach dem Ändern des MX Eintrages sich der neue Mailempfangsserver im DNS herumspricht.

Der aktuelle TTL lässt sich mit diesem Befehl prüfen:

<syntaxhighlight lang=shell>
dig -t MX meinedomain.de
meinedomain.de. 86400 IN MX 0 xyz.mail.protection.outlook.com.
</syntaxhighlight>

==== SPF Eintrag erweitern ====
Es sollte der SPF TXT Eintrag um <code>include:spf.hostsharing.net</code> erweitert werden.

=== Vorbereitungen in HSAdmin ===

Es sollte in HSAdmin auf https://admin.hostsharing.net folgende Dinge angelegt werden:

* die Domain meinedomain.de sollte angelegt werden
* es sollten die Postfächer als Unix Benutzer angelegt werden, und temporäre Passwörter vergeben werden.
* es sollten die E-Mail Adressen, Aliase und Weiterleitungen eingerichtet werden.

Es kann dafür auch dieses Python-Skript benutzt werden: https://codeberg.org/tpokorra/hostsharing-scripts/src/branch/main/create_and_move_mailboxes.py

=== Ankündigung an die Nutzenden ===

Rechtzeitig muss eine Anleitung und die neuen Zugangsdaten an die Nutzenden weitergegeben werden. Am besten sollten diese Menschen auch über einen anderen Kanal zu erreichen sein, falls es Probleme beim Wechsel auf das neue Postfach gibt.

Folgende Sachen sollten erwähnt werden:

* Umstellung der Zugangsdaten. Siehe auch Screenshots für Thunderbird auf https://www.hostsharing.net/doc/managed-operations-platform/email/
* Möglichkeit von Webmail: https://webmail.hostsharing.net
** dabei sollte beachtet werden:
*** Absender Adresse muss bei der ersten Anmeldung korrigiert werden.
*** evtl. müssen in den Einstellungen die Unterordner abonniert werden, sonst werden sie im Posteingang nicht angezeigt
* Ändern des temporären Passworts
** nach dem erfolgreichen Umzug der Postfächer muss jede Benutzerin das Passwort öndern
** das geschieht auf https://admin.hostsharing.net: anmelden, und dann oben rechts auf den eigenen Benutzernamen klicken

=== Der tatsächliche Umzug ===

Folgende Schritte müssen während des Umzugs in dieser Reihenfolge passieren:

* der MX Eintrag auf der Domain muss geändert werden. Alte MX Einträge müssen entfernt werden, und die 3 Einträge mailin1.hostsharing.net, mailin2.hostsharing.net und mailin3.hostsharing.net müssen eingefügt werden.
* die Passwörter für die alten Postfächer müssen zurückgesetzt werden, es reicht ein Passwort für alle.
* die Inhalte der Postfächer werden über imapcopy in die Postfächer bei Hostsharing kopiert.

=== Nacharbeiten ===

Nach dem erfolgreichen Umzug:

* die Benutzer ändern die Passwörter ihrer neuen Postfächer
* die Benutzer konfigurieren den E-Mail Client mit den neuen Zugangsdaten

Wenn sich der Staub gelegt hat, können danach die Webseite, weitere Anwendungen, und schließlich die gesamte Domain zu Hostsharing umgezogen werden.

Umzug aller Postfächer einer Domain

2026-03-10T15:47:17Z

Tim00: /* Durchzuführende Schritte */

== Szenario ==

Das neue Mitglied hat bisher eine Domain und mehrere Postfächer bei einem Anbieter. Nun soll die Domain, die Webseite, die Postfächer und evtl. auch andere Anwendungen, z.B. eine Nextcloud, zu Hostsharing umgezogen werden.

Wir betrachten hier erstmal nur dem Umzug der Postfächer und der E-Mail Adressen. Die weiteren Schritte können im Anschluss durchgeführt werden.

== Durchzuführende Schritte ==

=== Vorbereitungen an den Einstellungen der Domain ===
==== TTL heruntersetzen ====
Beim bisherigen Anbieter sollte die TTL auf dem MX Eintrag der Domain auf 600 Sekunden gesetzt werden (10 Minuten).
Das sollte spätestens einen Tag vor dem Umzug erledigt werden, um den Default-Wert der TTL von bis zu 24 Stunden zu vermeiden.
Dadurch wird die Zeitspanne verringert, in der während des Umzugs nach dem Ändern des MX Eintrages sich der neue Mailempfangsserver im DNS herumspricht.

Der aktuelle TTL lässt sich mit diesem Befehl prüfen:

<syntaxhighlight lang=shell>
dig -t MX meinedomain.de
meinedomain.de. 86400 IN MX 0 xyz.mail.protection.outlook.com.
</syntaxhighlight>

==== SPF Eintrag erweitern ====
Es sollte der SPF TXT Eintrag um <code>include:spf.hostsharing.net</code> erweitert werden.

=== Vorbereitungen in HSAdmin ===

Es sollte in HSAdmin auf https://admin.hostsharing.net folgende Dinge angelegt werden:

* die Domain meinedomain.de sollte angelegt werden
* es sollten die Postfächer als Unix Benutzer angelegt werden, und temporäre Passwörter vergeben werden.
* es sollten die E-Mail Adressen, Aliase und Weiterleitungen eingerichtet werden.

Es kann dafür auch dieses Python-Skript benutzt werden: https://codeberg.org/tpokorra/hostsharing-scripts/src/branch/main/create_and_move_mailboxes.py

=== Ankündigung an die Nutzenden ===

Rechtzeitig muss eine Anleitung und die neuen Zugangsdaten an die Nutzenden weitergegeben werden. Am besten sollten diese Menschen auch über einen anderen Kanal zu erreichen sein, falls es Probleme beim Wechsel auf das neue Postfach gibt.

Folgende Sachen sollten erwähnt werden:

* Umstellung der Zugangsdaten. Siehe auch Screenshots für Thunderbird auf https://www.hostsharing.net/doc/managed-operations-platform/email/
* Möglichkeit von Webmail: https://webmail.hostsharing.net
** dabei sollte beachtet werden:
*** Absender Adresse muss bei der ersten Anmeldung korrigiert werden.
*** evtl. müssen in den Einstellungen die Unterordner abonniert werden, sonst werden sie im Posteingang nicht angezeigt
* Ändern des temporären Passworts
** nach dem erfolgreichen Umzug der Postfächer muss jede Benutzerin das Passwort öndern
** das geschieht auf https://admin.hostsharing.net: anmelden, und dann oben rechts auf den eigenen Benutzernamen klicken

=== Der tatsächliche Umzug ===

Folgende Schritte müssen während des Umzugs in dieser Reihenfolge passieren:

* der MX Eintrag auf der Domain muss geändert werden. Alte MX Einträge müssen entfernt werden, und die 3 Einträge mailin1.hostsharing.net, mailin2.hostsharing.net und mailin3.hostsharing.net müssen eingefügt werden.
* die Passwörter für die alten Postfächer müssen zurückgesetzt werden, es reicht ein Passwort für alle.
* die Inhalte der Postfächer werden über imapcopy in die Postfächer bei Hostsharing kopiert.

=== Nacharbeiten ===

Nach dem erfolgreichen Umzug:

* die Benutzer ändern die Passwörter ihrer neuen Postfächer
* die Benutzer konfigurieren den E-Mail Client mit den neuen Zugangsdaten

Wenn sich der Staub gelegt hat, können danach die Webseite, weitere Anwendungen, und schließlich die gesamte Domain zu Hostsharing umgezogen werden.

Umzug aller Postfächer einer Domain

2026-03-10T15:46:04Z

Tim00: /* SPF Eintrag erweitern */

== Szenario ==

Das neue Mitglied hat bisher eine Domain und mehrere Postfächer bei einem Anbieter. Nun soll die Domain, die Webseite, die Postfächer und evtl. auch andere Anwendungen, z.B. eine Nextcloud, zu Hostsharing umgezogen werden.

Wir betrachten hier erstmal nur dem Umzug der Postfächer und der E-Mail Adressen. Die weiteren Schritte können im Anschluss durchgeführt werden.

== Durchzuführende Schritte ==

=== TTL heruntersetzen ===
Beim bisherigen Anbieter sollte die TTL auf dem MX Eintrag der Domain auf 600 Sekunden gesetzt werden (10 Minuten).
Das sollte spätestens einen Tag vor dem Umzug erledigt werden, um den Default-Wert der TTL von bis zu 24 Stunden zu vermeiden.
Dadurch wird die Zeitspanne verringert, in der während des Umzugs nach dem Ändern des MX Eintrages sich der neue Mailempfangsserver im DNS herumspricht.

Der aktuelle TTL lässt sich mit diesem Befehl prüfen:

<syntaxhighlight lang=shell>
dig -t MX meinedomain.de
meinedomain.de. 86400 IN MX 0 xyz.mail.protection.outlook.com.
</syntaxhighlight>

=== SPF Eintrag erweitern ===
Es sollte der SPF TXT Eintrag um <code>include:spf.hostsharing.net</code> erweitert werden.

=== Vorbereitungen in HSAdmin ===

Es sollte in HSAdmin auf https://admin.hostsharing.net folgende Dinge angelegt werden:

* die Domain meinedomain.de sollte angelegt werden
* es sollten die Postfächer als Unix Benutzer angelegt werden, und temporäre Passwörter vergeben werden.
* es sollten die E-Mail Adressen, Aliase und Weiterleitungen eingerichtet werden.

Es kann dafür auch dieses Python-Skript benutzt werden: https://codeberg.org/tpokorra/hostsharing-scripts/src/branch/main/create_and_move_mailboxes.py

=== Ankündigung an die Nutzenden ===

Rechtzeitig muss eine Anleitung und die neuen Zugangsdaten an die Nutzenden weitergegeben werden. Am besten sollten diese Menschen auch über einen anderen Kanal zu erreichen sein, falls es Probleme beim Wechsel auf das neue Postfach gibt.

Folgende Sachen sollten erwähnt werden:

* Umstellung der Zugangsdaten. Siehe auch Screenshots für Thunderbird auf https://www.hostsharing.net/doc/managed-operations-platform/email/
* Möglichkeit von Webmail: https://webmail.hostsharing.net
** dabei sollte beachtet werden:
*** Absender Adresse muss bei der ersten Anmeldung korrigiert werden.
*** evtl. müssen in den Einstellungen die Unterordner abonniert werden, sonst werden sie im Posteingang nicht angezeigt
* Ändern des temporären Passworts
** nach dem erfolgreichen Umzug der Postfächer muss jede Benutzerin das Passwort öndern
** das geschieht auf https://admin.hostsharing.net: anmelden, und dann oben rechts auf den eigenen Benutzernamen klicken

=== Der tatsächliche Umzug ===

Folgende Schritte müssen während des Umzugs in dieser Reihenfolge passieren:

* der MX Eintrag auf der Domain muss geändert werden. Alte MX Einträge müssen entfernt werden, und die 3 Einträge mailin1.hostsharing.net, mailin2.hostsharing.net und mailin3.hostsharing.net müssen eingefügt werden.
* die Passwörter für die alten Postfächer müssen zurückgesetzt werden, es reicht ein Passwort für alle.
* die Inhalte der Postfächer werden über imapcopy in die Postfächer bei Hostsharing kopiert.

=== Nacharbeiten ===

Nach dem erfolgreichen Umzug:

* die Benutzer ändern die Passwörter ihrer neuen Postfächer
* die Benutzer konfigurieren den E-Mail Client mit den neuen Zugangsdaten

Wenn sich der Staub gelegt hat, können danach die Webseite, weitere Anwendungen, und schließlich die gesamte Domain zu Hostsharing umgezogen werden.

Umzug aller Postfächer einer Domain

2026-03-10T15:45:25Z

Tim00: /* TTL heruntersetzen */

== Szenario ==

Das neue Mitglied hat bisher eine Domain und mehrere Postfächer bei einem Anbieter. Nun soll die Domain, die Webseite, die Postfächer und evtl. auch andere Anwendungen, z.B. eine Nextcloud, zu Hostsharing umgezogen werden.

Wir betrachten hier erstmal nur dem Umzug der Postfächer und der E-Mail Adressen. Die weiteren Schritte können im Anschluss durchgeführt werden.

== Durchzuführende Schritte ==

=== TTL heruntersetzen ===
Beim bisherigen Anbieter sollte die TTL auf dem MX Eintrag der Domain auf 600 Sekunden gesetzt werden (10 Minuten).
Das sollte spätestens einen Tag vor dem Umzug erledigt werden, um den Default-Wert der TTL von bis zu 24 Stunden zu vermeiden.
Dadurch wird die Zeitspanne verringert, in der während des Umzugs nach dem Ändern des MX Eintrages sich der neue Mailempfangsserver im DNS herumspricht.

Der aktuelle TTL lässt sich mit diesem Befehl prüfen:

<syntaxhighlight lang=shell>
dig -t MX meinedomain.de
meinedomain.de. 86400 IN MX 0 xyz.mail.protection.outlook.com.
</syntaxhighlight>

=== SPF Eintrag erweitern ===
Es sollte der SPF TXT Eintrag um spf.hostsharing.net erweitert werden.

=== Vorbereitungen in HSAdmin ===

Es sollte in HSAdmin auf https://admin.hostsharing.net folgende Dinge angelegt werden:

* die Domain meinedomain.de sollte angelegt werden
* es sollten die Postfächer als Unix Benutzer angelegt werden, und temporäre Passwörter vergeben werden.
* es sollten die E-Mail Adressen, Aliase und Weiterleitungen eingerichtet werden.

Es kann dafür auch dieses Python-Skript benutzt werden: https://codeberg.org/tpokorra/hostsharing-scripts/src/branch/main/create_and_move_mailboxes.py

=== Ankündigung an die Nutzenden ===

Rechtzeitig muss eine Anleitung und die neuen Zugangsdaten an die Nutzenden weitergegeben werden. Am besten sollten diese Menschen auch über einen anderen Kanal zu erreichen sein, falls es Probleme beim Wechsel auf das neue Postfach gibt.

Folgende Sachen sollten erwähnt werden:

* Umstellung der Zugangsdaten. Siehe auch Screenshots für Thunderbird auf https://www.hostsharing.net/doc/managed-operations-platform/email/
* Möglichkeit von Webmail: https://webmail.hostsharing.net
** dabei sollte beachtet werden:
*** Absender Adresse muss bei der ersten Anmeldung korrigiert werden.
*** evtl. müssen in den Einstellungen die Unterordner abonniert werden, sonst werden sie im Posteingang nicht angezeigt
* Ändern des temporären Passworts
** nach dem erfolgreichen Umzug der Postfächer muss jede Benutzerin das Passwort öndern
** das geschieht auf https://admin.hostsharing.net: anmelden, und dann oben rechts auf den eigenen Benutzernamen klicken

=== Der tatsächliche Umzug ===

Folgende Schritte müssen während des Umzugs in dieser Reihenfolge passieren:

* der MX Eintrag auf der Domain muss geändert werden. Alte MX Einträge müssen entfernt werden, und die 3 Einträge mailin1.hostsharing.net, mailin2.hostsharing.net und mailin3.hostsharing.net müssen eingefügt werden.
* die Passwörter für die alten Postfächer müssen zurückgesetzt werden, es reicht ein Passwort für alle.
* die Inhalte der Postfächer werden über imapcopy in die Postfächer bei Hostsharing kopiert.

=== Nacharbeiten ===

Nach dem erfolgreichen Umzug:

* die Benutzer ändern die Passwörter ihrer neuen Postfächer
* die Benutzer konfigurieren den E-Mail Client mit den neuen Zugangsdaten

Wenn sich der Staub gelegt hat, können danach die Webseite, weitere Anwendungen, und schließlich die gesamte Domain zu Hostsharing umgezogen werden.

Umzug aller Postfächer einer Domain

2026-03-10T15:44:03Z

Tim00: /* Ankündigung an die Nutzenden */

== Szenario ==

Das neue Mitglied hat bisher eine Domain und mehrere Postfächer bei einem Anbieter. Nun soll die Domain, die Webseite, die Postfächer und evtl. auch andere Anwendungen, z.B. eine Nextcloud, zu Hostsharing umgezogen werden.

Wir betrachten hier erstmal nur dem Umzug der Postfächer und der E-Mail Adressen. Die weiteren Schritte können im Anschluss durchgeführt werden.

== Durchzuführende Schritte ==

=== TTL heruntersetzen ===
Beim bisherigen Anbieter sollte die TTL auf dem MX Eintrag der Domain auf 600 Sekunden gesetzt werden (10 Minuten).
Das sollte spätestens einen Tag vor dem Umzug erledigt werden, um den Default-Wert der TTL von bis zu 24 Stunden zu vermeiden.
Dadurch wird die Zeitspanne verringert, in der während des Umzugs nach dem Ändern des MX Eintrages sich der neue Mailempfangsserver im DNS herumspricht.

Der aktuelle TTL lässt sich mit diesem Befehl prüfen:

<syntaxhighlight lang=shell>
dig -t MX meinedomain.de
meinedomain.de. 86400 IN MX 0 xyz.mail.protection.outlook.com.
</syntaxhighlight>

=== Vorbereitungen in HSAdmin ===

Es sollte in HSAdmin auf https://admin.hostsharing.net folgende Dinge angelegt werden:

* die Domain meinedomain.de sollte angelegt werden
* es sollten die Postfächer als Unix Benutzer angelegt werden, und temporäre Passwörter vergeben werden.
* es sollten die E-Mail Adressen, Aliase und Weiterleitungen eingerichtet werden.

Es kann dafür auch dieses Python-Skript benutzt werden: https://codeberg.org/tpokorra/hostsharing-scripts/src/branch/main/create_and_move_mailboxes.py

=== Ankündigung an die Nutzenden ===

Rechtzeitig muss eine Anleitung und die neuen Zugangsdaten an die Nutzenden weitergegeben werden. Am besten sollten diese Menschen auch über einen anderen Kanal zu erreichen sein, falls es Probleme beim Wechsel auf das neue Postfach gibt.

Folgende Sachen sollten erwähnt werden:

* Umstellung der Zugangsdaten. Siehe auch Screenshots für Thunderbird auf https://www.hostsharing.net/doc/managed-operations-platform/email/
* Möglichkeit von Webmail: https://webmail.hostsharing.net
** dabei sollte beachtet werden:
*** Absender Adresse muss bei der ersten Anmeldung korrigiert werden.
*** evtl. müssen in den Einstellungen die Unterordner abonniert werden, sonst werden sie im Posteingang nicht angezeigt
* Ändern des temporären Passworts
** nach dem erfolgreichen Umzug der Postfächer muss jede Benutzerin das Passwort öndern
** das geschieht auf https://admin.hostsharing.net: anmelden, und dann oben rechts auf den eigenen Benutzernamen klicken

=== Der tatsächliche Umzug ===

Folgende Schritte müssen während des Umzugs in dieser Reihenfolge passieren:

* der MX Eintrag auf der Domain muss geändert werden. Alte MX Einträge müssen entfernt werden, und die 3 Einträge mailin1.hostsharing.net, mailin2.hostsharing.net und mailin3.hostsharing.net müssen eingefügt werden.
* die Passwörter für die alten Postfächer müssen zurückgesetzt werden, es reicht ein Passwort für alle.
* die Inhalte der Postfächer werden über imapcopy in die Postfächer bei Hostsharing kopiert.

=== Nacharbeiten ===

Nach dem erfolgreichen Umzug:

* die Benutzer ändern die Passwörter ihrer neuen Postfächer
* die Benutzer konfigurieren den E-Mail Client mit den neuen Zugangsdaten

Wenn sich der Staub gelegt hat, können danach die Webseite, weitere Anwendungen, und schließlich die gesamte Domain zu Hostsharing umgezogen werden.

Umzug aller Postfächer einer Domain

2026-03-10T15:39:38Z

Tim00: /* Ankündigung an die Nutzenden */

== Szenario ==

Das neue Mitglied hat bisher eine Domain und mehrere Postfächer bei einem Anbieter. Nun soll die Domain, die Webseite, die Postfächer und evtl. auch andere Anwendungen, z.B. eine Nextcloud, zu Hostsharing umgezogen werden.

Wir betrachten hier erstmal nur dem Umzug der Postfächer und der E-Mail Adressen. Die weiteren Schritte können im Anschluss durchgeführt werden.

== Durchzuführende Schritte ==

=== TTL heruntersetzen ===
Beim bisherigen Anbieter sollte die TTL auf dem MX Eintrag der Domain auf 600 Sekunden gesetzt werden (10 Minuten).
Das sollte spätestens einen Tag vor dem Umzug erledigt werden, um den Default-Wert der TTL von bis zu 24 Stunden zu vermeiden.
Dadurch wird die Zeitspanne verringert, in der während des Umzugs nach dem Ändern des MX Eintrages sich der neue Mailempfangsserver im DNS herumspricht.

Der aktuelle TTL lässt sich mit diesem Befehl prüfen:

<syntaxhighlight lang=shell>
dig -t MX meinedomain.de
meinedomain.de. 86400 IN MX 0 xyz.mail.protection.outlook.com.
</syntaxhighlight>

=== Vorbereitungen in HSAdmin ===

Es sollte in HSAdmin auf https://admin.hostsharing.net folgende Dinge angelegt werden:

* die Domain meinedomain.de sollte angelegt werden
* es sollten die Postfächer als Unix Benutzer angelegt werden, und temporäre Passwörter vergeben werden.
* es sollten die E-Mail Adressen, Aliase und Weiterleitungen eingerichtet werden.

Es kann dafür auch dieses Python-Skript benutzt werden: https://codeberg.org/tpokorra/hostsharing-scripts/src/branch/main/create_and_move_mailboxes.py

=== Ankündigung an die Nutzenden ===

Rechtzeitig muss eine Anleitung und die neuen Zugangsdaten an die Nutzenden weitergegeben werden. Am besten sollten diese Menschen auch über einen anderen Kanal zu erreichen sein, falls es Probleme beim Wechsel auf das neue Postfach gibt.

Folgende Sachen sollten erwähnt werden:

* Umstellung der Zugangsdaten. Siehe auch Screenshots für Thunderbird auf https://www.hostsharing.net/doc/managed-operations-platform/email/
* Möglichkeit von Webmail: https://webmail.hostsharing.net
** dabei sollte beachtet werden:
*** Absender Adresse muss bei der ersten Anmeldung korrigiert werden.
*** evtl. müssen in den Einstellungen die Unterordner abonniert werden, sonst werden sie im Posteingang nicht angezeigt
* Ändern des temporären Passworts
** nach dem erfolgreichen Umzug der Postfächer muss jede Benutzerin das Passwort öndern
** das geschieht auf https://admin.hostsharing.net: anmelden, und dann oben rechts auf den eigenen Benutzernamen klicken

Umzug aller Postfächer einer Domain

2026-03-10T15:39:17Z

Tim00: /* Ankündigung an die Nutzenden */

== Szenario ==

Das neue Mitglied hat bisher eine Domain und mehrere Postfächer bei einem Anbieter. Nun soll die Domain, die Webseite, die Postfächer und evtl. auch andere Anwendungen, z.B. eine Nextcloud, zu Hostsharing umgezogen werden.

Wir betrachten hier erstmal nur dem Umzug der Postfächer und der E-Mail Adressen. Die weiteren Schritte können im Anschluss durchgeführt werden.

== Durchzuführende Schritte ==

=== TTL heruntersetzen ===
Beim bisherigen Anbieter sollte die TTL auf dem MX Eintrag der Domain auf 600 Sekunden gesetzt werden (10 Minuten).
Das sollte spätestens einen Tag vor dem Umzug erledigt werden, um den Default-Wert der TTL von bis zu 24 Stunden zu vermeiden.
Dadurch wird die Zeitspanne verringert, in der während des Umzugs nach dem Ändern des MX Eintrages sich der neue Mailempfangsserver im DNS herumspricht.

Der aktuelle TTL lässt sich mit diesem Befehl prüfen:

<syntaxhighlight lang=shell>
dig -t MX meinedomain.de
meinedomain.de. 86400 IN MX 0 xyz.mail.protection.outlook.com.
</syntaxhighlight>

=== Vorbereitungen in HSAdmin ===

Es sollte in HSAdmin auf https://admin.hostsharing.net folgende Dinge angelegt werden:

* die Domain meinedomain.de sollte angelegt werden
* es sollten die Postfächer als Unix Benutzer angelegt werden, und temporäre Passwörter vergeben werden.
* es sollten die E-Mail Adressen, Aliase und Weiterleitungen eingerichtet werden.

Es kann dafür auch dieses Python-Skript benutzt werden: https://codeberg.org/tpokorra/hostsharing-scripts/src/branch/main/create_and_move_mailboxes.py

=== Ankündigung an die Nutzenden ===

Rechtzeitig muss eine Anleitung und die neuen Zugangsdaten an die Nutzenden weitergegeben werden. Am besten sollten diese Menschen auch über einen anderen Kanal zu erreichen sein, falls es Probleme beim Wechsel auf das neue Postfach gibt.

Folgende Sachen sollten erwähnt werden:

* Umstellung der Zugangsdaten. Siehe auch Screenshots für Thunderbird auf https://www.hostsharing.net/doc/managed-operations-platform/email/
* Möglichkeit von Webmail: https://webmail.hostsharing.net
* dabei sollte beachtet werden:
* Absender Adresse muss bei der ersten Anmeldung korrigiert werden.
* evtl. müssen in den Einstellungen die Unterordner abonniert werden, sonst werden sie im Posteingang nicht angezeigt
* Ändern des temporären Passworts
* nach dem erfolgreichen Umzug der Postfächer muss jede Benutzerin das Passwort öndern
* das geschieht auf https://admin.hostsharing.net: anmelden, und dann oben rechts auf den eigenen Benutzernamen klicken

Umzug aller Postfächer einer Domain

2026-03-10T15:00:12Z

Tim00: Die Seite wurde neu angelegt: „== Szenario == Das neue Mitglied hat bisher eine Domain und mehrere Postfächer bei einem Anbieter. Nun soll die Domain, die Webseite, die Postfächer und evtl. auch andere Anwendungen, z.B. eine Nextcloud, zu Hostsharing umgezogen werden. Wir betrachten hier erstmal nur dem Umzug der Postfächer und der E-Mail Adressen. Die weiteren Schritte können im Anschluss durchgeführt werden. == Durchzuführende Schritte == === TTL heruntersetzen === Beim bis…“

Domains

2026-03-10T14:48:03Z

Tim00: /* Aktionen */

{{HSDoku-DomainLinks}}
__NOTOC__

= Domains bei Hostsharing =

aktuelle Dokumentation:

{{Kerndoku|https://www.hostsharing.net/doc/managed-operations-platform/domain/}}

Die Domainverwaltung bei Hostsharing ist in zwei unabhängige Bereiche aufgeteilt:

* Die '''Domaineinrichtung''' in den HS-Paketen, zur Erstellung des Domainverzeichnisses unter [[~/]]doms im Paket und [[Aufschaltung]] einer Domain auf HS [[DNS|Name]]-, Mail- und Webserver. Dies geschieht mit [[hsadmin]] im Webfrontend oder auf der Kommandozeile.

* Das '''[http://www.domain-bestellsystem.de Domainbestellsystem]''' des HS-Partnerunternehmens Partnergate zur [[Konnektierung]], also der eigentlichen Registrierung von Domains bei einem Registrar, und zur Vergabe weiterer Aufträgen an Registrierungstellen. Jedes Mitglied von Hostsharing erhielt für dieses Domainbestellsystem Zugangsdaten, bestehend aus einem Benutzernamen der Form hs-xyz und einem Passwort.

Bei anderen Hostern ist eine Domainbestellung teilweise eine feste Kopplung der Registrierung einer Domain mit Konnektierung und gleichzeitiger Aufschaltung auf bestimmte Nameserver und Webpakete. HS ist hier wesentlich flexibler. Der über HS angebotene Zugang zum Domain-Bestellsystem erlaubt es, Domains zu registrieren und auf frei wählbare DNS-Server zu konnektieren. Auf den HS Nameservern und Paketen lassen sich gleichzeitig beliebige weltweit registrierbare Domains einrichten. Hostsharing unterstützt damit die Einrichtung und den Betrieb von Domains die von beliebigen (auch sehr exotischen) Registrierungsstellen verwaltet und abgerechnet werden können.

= Aktionen =

Typische Domainaktionen beinhalten also koordinierte Änderungen sowohl in der Domainregistrierung als auch der HS-Einrichtung, wie in folgenden Seiten aufgezeigt:

* Eine Domain einrichten: [[Domainregistrierung]]
* Eine Domain kündigen: [[Domainkündigung]]
* Verwalten von Domains, Subdomains, Eigentümer, Nameserver: [[Domainverwaltung]]
* Umzug von allen Postfächern einer Domain von einem anderen Anbieter zu Hostsharing: [[Umzug aller Postfächer einer Domain]]

= Weiterführende Links =

Was ist eine [[Domain]] 
Was ist ein [[Handles|Domainhandle]] 
[[FAQ#Domains|Einträge zu Domains in der HS FAQ]]

----
[[Kategorie:HSDoku]]
[[Kategorie:Domains]]

ImapCopy

2026-03-06T17:16:25Z

Tim00: /* Python Skript zur Massenverarbeitung */

== ImapCopy ==

ImapCopy ist ein Werkzeug, mit dem man ein komplettes IMAP-Postfach in ein IMAP-Postfach auf einem anderen Server (bei einem anderen Anbieter) kopieren kann. Wir verwenden es für die Migration von Postfächern. Eine Alternative ist [[OfflineIMAP]].

== Installation ImapCopy ==

ImapCopy ist auf den HS Hives schon installiert

== Einrichtung allgemein ==

Anmelden per ssh als ein Benutzer in einem HS-Paket.

<syntaxhighlight lang="bash">
xyz00-imapcopy@h01:~$
</syntaxhighlight>

Dort wird ein Arbeitsverzeichnis erstellt

<syntaxhighlight lang="bash">
xyz00-imapcopy@h01:~$ mkdir imapcopy
xyz00-imapcopy@h01:~$ cd imapcopy
</syntaxhighlight>

Die Konfiguration wird in einer Datei ImapCopy.cfg gespeichert

<syntaxhighlight lang="bash">
xyz00-imapcopy@h01:~/imapcopy$ vi ImapCopy.cfg
</syntaxhighlight>

=== Config Web.de -> HS Benutzer ===

Muster Inhalt der Datei ImapCopy.cfg

<syntaxhighlight lang="bash" line>
#############################################################
# imapcopy config
# all lines beginning with # are comments and will be ignored
#############################################################

##############
# Sourceserver
##############
SourceServer imap.web.de
SourcePort 143

###################
# Destinationserver
###################
DestServer xyz00.hostsharing.net
DestPort 143

#########
# Options
#########
#
# DebugSrc and DebugDest will show all traffic between IMAPCopy and Server
#
#DebugSrc
#DebugDst

#################
# Folders to skip
#################
#skipfolder INBOX.Trash
#skipfolder INBOX.Sent
#skipfolder "INBOX.Sent Objects"

#################
# Folders to copy
#################
#copyfolder INBOX
#copyfolder "INBOX.My personal files"
#copyfolder INBOX.Net-Connection.dy
#copyfolder INBOX.test

#######################################################
# Rootfolder
# Can be specified to copy the Folder-Structure under
# a separate folder instead of inbox
#######################################################
#DstRootFolder "Your old Mails"

###############################################################
# Specify Flags that are supported on the destination server
# (AllowFlags) or flags that should be filtered out (DenyFlags)
# If not specified, all Flags are copyied 1:1
# If AllowFlags is specified, all not specified Flags will be
# removed and not copied to the destination
# If DenyFlags is specified, those flags will be removed and
# the remaining ones will be copied
# Both (AllowFlags and DenyFlags) could be specified but
# would (in most cases) make no sense
##############################################################
#AllowFlags "\Seen\Answered\Flagged\Deleted\Draft Junk NonJunk $MDNSent $Forwared"
DenyFlags "\Recent"

##############################################################
# Timezone conversion
# The imap rfc is not clear on what kind of time offsets
# can be used. +XXXX -XXXX will be supported on all servers
# You can add as many entries as needed in the form
# converttimezone SRC DST
# to convert zones that your target server rejects
##############################################################
converttimezone "UTC" "+0000"
converttimezone "UT" "+0000"

#############################
# List of users and passwords
#############################
# SourceUser SourcePassword DestinationUser DestinationPassword
Copy "xyz@web.de" "Euer-Passwort" "xyz00-imap" "Benutzer-Passwort"
</syntaxhighlight>

=== Config gmail.com -> HS Benutzer ===

Da ImapCopy nicht direkt SSL unterstützt benötigt z.b. gmail und ggf einige andere die weiter unten beschrieben Lösung mit einem stunnel.

== Testen einer Verbindung ==

Zum testen ob die Daten alle OK sind auf der shell einfach:

<syntaxhighlight lang="bash">
xyz00-imapcopy@h01:~/imapcopy$ imapcopy -t
</syntaxhighlight>

eingeben.

== Daten austauschen ==

Wir empfehlen: Benutze eine <code>screen</code> Sitzung, damit die Übertragung nicht durch einen Verbindungsabbruch durcheinander kommt!

<syntaxhighlight lang="bash">
xyz00-imapcopy@h01:~/imapcopy$ screen
xyz00-imapcopy@h01:~/imapcopy$ imapcopy
</syntaxhighlight>

== Hilfe ==

<syntaxhighlight lang="bash">
xyz00-imapcopy@h01:~/imapcopy$ imapcopy -h
xyz00-imapcopy@h01:~/imapcopy$ man imapcopy
</syntaxhighlight>

== Python Skript zur Massenverarbeitung ==

Wenn viele Postfächer umgezogen werden sollen, ist es hilfreich, wenn die Befehle und die Passwörter generiert werden können.

Dafür haben wir ein Python-Skript, das in diesem Repository zur Verfügung steht:
* [https://codeberg.org/tpokorra/hostsharing-scripts/src/branch/main/create_and_move_mailboxes.py create_and_move_mailboxes.py]
* mit einer entsprechenden Konfigurations-Datei: [https://codeberg.org/tpokorra/hostsharing-scripts/src/branch/main/create_and_move_mailboxes_config-sample.py create_and_move_mailboxes_config-sample.py]

In der Konfigurations-Datei werden die Postfächer mit E-Mail-Adresse und Aliasen, und die Verteiler konfiguriert.

Die Passwörter werden nur einmal generiert, und in einer sqlite Datenbank gespeichert.

<syntaxhighlight lang="bash" line>
# dem Kunden die neuen Passwörter mitteilen:
ACTION=info python3 create_and_move_mailboxes.py
# Anweisungen in hsscript ausführen:
ACTION=hsadmin python3 create_and_move_mailboxes.py
# Anweisungen in ImapCopy einfügen:
ACTION=imapcopy python3 create_and_move_mailboxes.py
</syntaxhighlight>

== ssl via stunnel ==

Es wird eine Konfuguration Datei , hier stunnel-to-gmail.conf, benötigt.

<syntaxhighlight lang="bash">
xyz00-imapcopy@h01:~/imapcopy$ vi stunnel-to-gmail.conf
</syntaxhighlight>

Inhalt der Datei stunnel-to-gmail.conf:

<syntaxhighlight lang="ini" line>
foreground=yes

; Some performance tunings
socket = l:TCP_NODELAY=1
socket = r:TCP_NODELAY=1

; Some debugging stuff useful for troubleshooting
debug = 7

; Pfad for pid file
pid = /tmp/stunnel4-xyz00.pid

; Use it for client mode
client = yes

; Service-level configuration

[imap]
accept = 127.0.0.1:10143
connect = imap.gmail.com:993
retry = yes

[imap]
accept = 127.0.0.1:20143
connect = xyz00.hostsharing.net:993
retry = yes
</syntaxhighlight>

=== Änderung in der ImapCopy.cfg ===

<syntaxhighlight lang="ini" line>
##############
# Sourceserver
##############
SourceServer 127.0.0.1
SourcePort 10143

###################
# Destinationserver
###################
DestServer 127.0.0.1
DestPort 20143

#############################
# List of users and passwords
#############################
# SourceUser SourcePassword DestinationUser DestinationPassword
Copy "xyz@gmail.com" "passwort" "xyz00-imap" "passwort"
</syntaxhighlight>

=== stunnel aufbauen ===

Wir öffnen eine zweite Shell, starten dort screen, um kein Problem bei Verbindungsabbrüchen zu haben, und starten dann den stunnel:

<syntaxhighlight lang="bash" line>
xyz00-imapcopy@h01:~/imapcopy$ screen
xyz00-imapcopy@h01:~/imapcopy$ stunnel4 stunnel-to-gmail.conf
</syntaxhighlight>

=== Verbindung prüfen und herstellen ===

Siehe -> Testen einer Verbindung
und -> Daten austauschen

[[Kategorie:HSDoku]]
[[Kategorie:Installationsanleitungen]]
[[Kategorie:Glossar]]
[[Kategorie:Software]]
[[Kategorie:E-Mail]]

ImapCopy

2026-03-06T17:13:06Z

Tim00: /* ssl via stunnel */

== ImapCopy ==

ImapCopy ist ein Werkzeug, mit dem man ein komplettes IMAP-Postfach in ein IMAP-Postfach auf einem anderen Server (bei einem anderen Anbieter) kopieren kann. Wir verwenden es für die Migration von Postfächern. Eine Alternative ist [[OfflineIMAP]].

== Installation ImapCopy ==

ImapCopy ist auf den HS Hives schon installiert

== Einrichtung allgemein ==

Anmelden per ssh als ein Benutzer in einem HS-Paket.

<syntaxhighlight lang="bash">
xyz00-imapcopy@h01:~$
</syntaxhighlight>

Dort wird ein Arbeitsverzeichnis erstellt

<syntaxhighlight lang="bash">
xyz00-imapcopy@h01:~$ mkdir imapcopy
xyz00-imapcopy@h01:~$ cd imapcopy
</syntaxhighlight>

Die Konfiguration wird in einer Datei ImapCopy.cfg gespeichert

<syntaxhighlight lang="bash">
xyz00-imapcopy@h01:~/imapcopy$ vi ImapCopy.cfg
</syntaxhighlight>

=== Config Web.de -> HS Benutzer ===

Muster Inhalt der Datei ImapCopy.cfg

<syntaxhighlight lang="bash" line>
#############################################################
# imapcopy config
# all lines beginning with # are comments and will be ignored
#############################################################

##############
# Sourceserver
##############
SourceServer imap.web.de
SourcePort 143

###################
# Destinationserver
###################
DestServer xyz00.hostsharing.net
DestPort 143

#########
# Options
#########
#
# DebugSrc and DebugDest will show all traffic between IMAPCopy and Server
#
#DebugSrc
#DebugDst

#################
# Folders to skip
#################
#skipfolder INBOX.Trash
#skipfolder INBOX.Sent
#skipfolder "INBOX.Sent Objects"

#################
# Folders to copy
#################
#copyfolder INBOX
#copyfolder "INBOX.My personal files"
#copyfolder INBOX.Net-Connection.dy
#copyfolder INBOX.test

#######################################################
# Rootfolder
# Can be specified to copy the Folder-Structure under
# a separate folder instead of inbox
#######################################################
#DstRootFolder "Your old Mails"

###############################################################
# Specify Flags that are supported on the destination server
# (AllowFlags) or flags that should be filtered out (DenyFlags)
# If not specified, all Flags are copyied 1:1
# If AllowFlags is specified, all not specified Flags will be
# removed and not copied to the destination
# If DenyFlags is specified, those flags will be removed and
# the remaining ones will be copied
# Both (AllowFlags and DenyFlags) could be specified but
# would (in most cases) make no sense
##############################################################
#AllowFlags "\Seen\Answered\Flagged\Deleted\Draft Junk NonJunk $MDNSent $Forwared"
DenyFlags "\Recent"

##############################################################
# Timezone conversion
# The imap rfc is not clear on what kind of time offsets
# can be used. +XXXX -XXXX will be supported on all servers
# You can add as many entries as needed in the form
# converttimezone SRC DST
# to convert zones that your target server rejects
##############################################################
converttimezone "UTC" "+0000"
converttimezone "UT" "+0000"

#############################
# List of users and passwords
#############################
# SourceUser SourcePassword DestinationUser DestinationPassword
Copy "xyz@web.de" "Euer-Passwort" "xyz00-imap" "Benutzer-Passwort"
</syntaxhighlight>

=== Config gmail.com -> HS Benutzer ===

Da ImapCopy nicht direkt SSL unterstützt benötigt z.b. gmail und ggf einige andere die weiter unten beschrieben Lösung mit einem stunnel.

== Testen einer Verbindung ==

Zum testen ob die Daten alle OK sind auf der shell einfach:

<syntaxhighlight lang="bash">
xyz00-imapcopy@h01:~/imapcopy$ imapcopy -t
</syntaxhighlight>

eingeben.

== Daten austauschen ==

Wir empfehlen: Benutze eine <code>screen</code> Sitzung, damit die Übertragung nicht durch einen Verbindungsabbruch durcheinander kommt!

<syntaxhighlight lang="bash">
xyz00-imapcopy@h01:~/imapcopy$ screen
xyz00-imapcopy@h01:~/imapcopy$ imapcopy
</syntaxhighlight>

== Hilfe ==

<syntaxhighlight lang="bash">
xyz00-imapcopy@h01:~/imapcopy$ imapcopy -h
xyz00-imapcopy@h01:~/imapcopy$ man imapcopy
</syntaxhighlight>

== Python Skript zur Massenverarbeitung ==

== ssl via stunnel ==

Es wird eine Konfuguration Datei , hier stunnel-to-gmail.conf, benötigt.

<syntaxhighlight lang="bash">
xyz00-imapcopy@h01:~/imapcopy$ vi stunnel-to-gmail.conf
</syntaxhighlight>

Inhalt der Datei stunnel-to-gmail.conf:

<syntaxhighlight lang="ini" line>
foreground=yes

; Some performance tunings
socket = l:TCP_NODELAY=1
socket = r:TCP_NODELAY=1

; Some debugging stuff useful for troubleshooting
debug = 7

; Pfad for pid file
pid = /tmp/stunnel4-xyz00.pid

; Use it for client mode
client = yes

; Service-level configuration

[imap]
accept = 127.0.0.1:10143
connect = imap.gmail.com:993
retry = yes

[imap]
accept = 127.0.0.1:20143
connect = xyz00.hostsharing.net:993
retry = yes
</syntaxhighlight>

=== Änderung in der ImapCopy.cfg ===

<syntaxhighlight lang="ini" line>
##############
# Sourceserver
##############
SourceServer 127.0.0.1
SourcePort 10143

###################
# Destinationserver
###################
DestServer 127.0.0.1
DestPort 20143

#############################
# List of users and passwords
#############################
# SourceUser SourcePassword DestinationUser DestinationPassword
Copy "xyz@gmail.com" "passwort" "xyz00-imap" "passwort"
</syntaxhighlight>

=== stunnel aufbauen ===

Wir öffnen eine zweite Shell, starten dort screen, um kein Problem bei Verbindungsabbrüchen zu haben, und starten dann den stunnel:

<syntaxhighlight lang="bash" line>
xyz00-imapcopy@h01:~/imapcopy$ screen
xyz00-imapcopy@h01:~/imapcopy$ stunnel4 stunnel-to-gmail.conf
</syntaxhighlight>

=== Verbindung prüfen und herstellen ===

Siehe -> Testen einer Verbindung
und -> Daten austauschen

[[Kategorie:HSDoku]]
[[Kategorie:Installationsanleitungen]]
[[Kategorie:Glossar]]
[[Kategorie:Software]]
[[Kategorie:E-Mail]]

ImapCopy

2026-03-06T17:09:27Z

Tim00: /* Installation ImapCopy */

== ImapCopy ==

ImapCopy ist ein Werkzeug, mit dem man ein komplettes IMAP-Postfach in ein IMAP-Postfach auf einem anderen Server (bei einem anderen Anbieter) kopieren kann. Wir verwenden es für die Migration von Postfächern. Eine Alternative ist [[OfflineIMAP]].

== Installation ImapCopy ==

ImapCopy ist auf den HS Hives schon installiert

== Einrichtung allgemein ==

Anmelden per ssh als ein Benutzer in einem HS-Paket.

<syntaxhighlight lang="bash">
xyz00-imapcopy@h01:~$
</syntaxhighlight>

Dort wird ein Arbeitsverzeichnis erstellt

<syntaxhighlight lang="bash">
xyz00-imapcopy@h01:~$ mkdir imapcopy
xyz00-imapcopy@h01:~$ cd imapcopy
</syntaxhighlight>

Die Konfiguration wird in einer Datei ImapCopy.cfg gespeichert

<syntaxhighlight lang="bash">
xyz00-imapcopy@h01:~/imapcopy$ vi ImapCopy.cfg
</syntaxhighlight>

=== Config Web.de -> HS Benutzer ===

Muster Inhalt der Datei ImapCopy.cfg

<syntaxhighlight lang="bash" line>
#############################################################
# imapcopy config
# all lines beginning with # are comments and will be ignored
#############################################################

##############
# Sourceserver
##############
SourceServer imap.web.de
SourcePort 143

###################
# Destinationserver
###################
DestServer xyz00.hostsharing.net
DestPort 143

#########
# Options
#########
#
# DebugSrc and DebugDest will show all traffic between IMAPCopy and Server
#
#DebugSrc
#DebugDst

#################
# Folders to skip
#################
#skipfolder INBOX.Trash
#skipfolder INBOX.Sent
#skipfolder "INBOX.Sent Objects"

#################
# Folders to copy
#################
#copyfolder INBOX
#copyfolder "INBOX.My personal files"
#copyfolder INBOX.Net-Connection.dy
#copyfolder INBOX.test

#######################################################
# Rootfolder
# Can be specified to copy the Folder-Structure under
# a separate folder instead of inbox
#######################################################
#DstRootFolder "Your old Mails"

###############################################################
# Specify Flags that are supported on the destination server
# (AllowFlags) or flags that should be filtered out (DenyFlags)
# If not specified, all Flags are copyied 1:1
# If AllowFlags is specified, all not specified Flags will be
# removed and not copied to the destination
# If DenyFlags is specified, those flags will be removed and
# the remaining ones will be copied
# Both (AllowFlags and DenyFlags) could be specified but
# would (in most cases) make no sense
##############################################################
#AllowFlags "\Seen\Answered\Flagged\Deleted\Draft Junk NonJunk $MDNSent $Forwared"
DenyFlags "\Recent"

##############################################################
# Timezone conversion
# The imap rfc is not clear on what kind of time offsets
# can be used. +XXXX -XXXX will be supported on all servers
# You can add as many entries as needed in the form
# converttimezone SRC DST
# to convert zones that your target server rejects
##############################################################
converttimezone "UTC" "+0000"
converttimezone "UT" "+0000"

#############################
# List of users and passwords
#############################
# SourceUser SourcePassword DestinationUser DestinationPassword
Copy "xyz@web.de" "Euer-Passwort" "xyz00-imap" "Benutzer-Passwort"
</syntaxhighlight>

=== Config gmail.com -> HS Benutzer ===

Da ImapCopy nicht direkt SSL unterstützt benötigt z.b. gmail und ggf einige andere die weiter unten beschrieben Lösung mit einem stunnel.

== Testen einer Verbindung ==

Zum testen ob die Daten alle OK sind auf der shell einfach:

<syntaxhighlight lang="bash">
xyz00-imapcopy@h01:~/imapcopy$ imapcopy -t
</syntaxhighlight>

eingeben.

== Daten austauschen ==

Wir empfehlen: Benutze eine <code>screen</code> Sitzung, damit die Übertragung nicht durch einen Verbindungsabbruch durcheinander kommt!

<syntaxhighlight lang="bash">
xyz00-imapcopy@h01:~/imapcopy$ screen
xyz00-imapcopy@h01:~/imapcopy$ imapcopy
</syntaxhighlight>

== Hilfe ==

<syntaxhighlight lang="bash">
xyz00-imapcopy@h01:~/imapcopy$ imapcopy -h
xyz00-imapcopy@h01:~/imapcopy$ man imapcopy
</syntaxhighlight>

== ssl via stunnel ==

Es wird eine Konfuguration Datei , hier stunnel-to-gmail.conf, benötigt.

<syntaxhighlight lang="bash">
xyz00-imapcopy@h01:~/imapcopy$ vi stunnel-to-gmail.conf
</syntaxhighlight>

Inhalt der Datei stunnel-to-gmail.conf:

<syntaxhighlight lang="ini" line>
foreground=yes

; Some performance tunings
socket = l:TCP_NODELAY=1
socket = r:TCP_NODELAY=1

; Some debugging stuff useful for troubleshooting
debug = 7

; Pfad for pid file
pid = /tmp/stunnel4-xyz00.pid

; Use it for client mode
client = yes

; Service-level configuration

[imap]
accept = 127.0.0.1:10143
connect = imap.gmail.com:993
retry = yes

[imap]
accept = 127.0.0.1:20143
connect = xyz00.hostsharing.net:993
retry = yes
</syntaxhighlight>

=== Änderung in der ImapCopy.cfg ===

<syntaxhighlight lang="ini" line>
##############
# Sourceserver
##############
SourceServer 127.0.0.1
SourcePort 10143

###################
# Destinationserver
###################
DestServer 127.0.0.1
DestPort 20143

#############################
# List of users and passwords
#############################
# SourceUser SourcePassword DestinationUser DestinationPassword
Copy "xyz@gmail.com" "passwort" "xyz00-imap" "passwort"
</syntaxhighlight>

=== stunnel aufbauen ===

Wir öffnen eine zweite Shell, starten dort screen, um kein Problem bei Verbindungsabbrüchen zu haben, und starten dann den stunnel:

<syntaxhighlight lang="bash" line>
xyz00-imapcopy@h01:~/imapcopy$ screen
xyz00-imapcopy@h01:~/imapcopy$ stunnel4 stunnel-to-gmail.conf
</syntaxhighlight>

=== Verbindung prüfen und herstellen ===

Siehe -> Testen einer Verbindung
und -> Daten austauschen

[[Kategorie:HSDoku]]
[[Kategorie:Installationsanleitungen]]
[[Kategorie:Glossar]]
[[Kategorie:Software]]
[[Kategorie:E-Mail]]

Discourse installieren

2026-03-05T19:46:50Z

Tim00: /* Am Beispiel von 2025.12.0 auf 2026.1.1 */

{{Textkasten|gelb|Für Managed Server|Ein funktionierender Discourse-Server erfordert mehrere laufende Server-Dienste. Für den Betrieb ist ein Managed Server sinnvoll.}}

{{Textkasten|rot|Support von der Discourse-Community|Die Discourse-Entwickler haben sich entschieden, nur eine mehr oder weniger genormte Installationsmethode (via docker) zu unterstützen. Dies ist so auf der hostsharing-Architektur aufgrund mehrerer Bedenken und Überlegungen nicht möglich. Die Community ist durchaus hilfreich, geht aber davon aus, dass quasi alle Nutzer* eine "supported"e Installation durchgeführt haben. Wenn man in entsprechenden Kanälen nach Hilfe fragt, sollte man unbedingt erwähnen, dass man discourse selber anhand dieser hier lesbaren Anleitung installiert hat, um bereits entsprechenden Kommentaren und Nachfragen vorzugreifen.}}

== Über ==

In diesem Artikel wird die Installation von discourse, Version 2.1.0 (September 2018) beschrieben.

== Vorbereitungen ==

Mit Hilfe von HSAdmin wird angelegt:
# Ein User als Service-User mit ''/bin/bash'' als Shell, zum Beispiel Beispiel: ''xyz00-discourse''
# Eine Domain mit ''xyz00-discourse' als Domain-Administrator, zum Beispiel ''beispiel.discussion''
# Einen Postgresql-User ''xyz00_discourseuser'' mit Passwort ''meinPasswort''
# Eine Postgresql-Datenbank ''xyz00_discoursedb'' mit Datenbank-Owner ''xyz00_discourseuser''

Verwendete IP-Ports der Server-Dienste:
# Redis: localhost:32002
# Discourse-Web: localhost:13000

== Konfiguration der PostgreSQL Datenbank ==

Es müssen noch Erweiterungen für Postgresql installiert werden:

<syntaxhighlight lang=shell line>
psql --user xyz00_discourseuser -c "CREATE EXTENSION IF NOT EXISTS hstore WITH SCHEMA public;"
psql --user xyz00_discourseuser -c "CREATE EXTENSION IF NOT EXISTS pg_trgm WITH SCHEMA public;"
psql --user xyz00_discourseuser -c "CREATE EXTENSION IF NOT EXISTS unaccent WITH SCHEMA public;"
</syntaxhighlight>

== Konfiguration des Redis Server ==

{{Textkasten|gelb|Firewall/Redis Port|Leider unterstützt discourse nicht die Kommunikation mit Redis über Unix-Sockets. Dementsprechend muss der für Redis konfigurierte Port von dem hostsharing-Support in der Firewall freigegeben werden.}}

<syntaxhighlight lang=shell>
cd
mkdir redis/etc redis/lib redis/log redis/run
</syntaxhighlight>

Anlegen einer Datei ''/home/pacs/xyz00/users/discourse/redis/etc/redis.conf'' mit folgendem Inhalt:

<syntaxhighlight lang=shell line>
daemonize no
pidfile /home/pacs/xyz00/users/discourse/redis/run/redis-server.pid
port 32002
tcp-backlog 128
bind 127.0.0.1
timeout 300
loglevel notice
logfile /home/pacs/xyz00/users/discourse/redis/log/redis.log
databases 16
save 900 1
save 300 10
save 60 10000
slave-serve-stale-data yes
appendonly no
dbfilename dump.rdb
dir /home/pacs/xyz00/users/discourse/redis/lib
</syntaxhighlight>

Für Discourse 3.x gilt: "Discourse requires Redis 6.2.0 or up"

Für Debian Buster und Bullseye ist daher das Installieren eines neueren Binaries erforderlich. Bei Debian Bookwork ist bereits Redis 7.0 enthalten (siehe https://packages.debian.org/search?keywords=redis-server).

Hier steht ein entsprechendes Binary für Debian Buster zur Verfügung, das mit dem Public Key von Timotheus geprüft werden kann:

* https://download.solidcharity.com/tarballs/tpokorra/hostsharing/redis-server-6.2.12-debian-buster.tar.gz
* Prüfsignatur: https://download.solidcharity.com/tarballs/tpokorra/hostsharing/redis-server-6.2.12-debian-buster.tar.gz.sig

Prüfen der Signatur:

<syntaxhighlight lang=shell>
gpg --verify redis-server-6.2.12-debian-buster.tar.gz.sig redis-server-6.2.12-debian-buster.tar.gz
</syntaxhighlight>

Das Binary muss nach <code>$HOME/bin</code> verschoben werden, und entsprechend beim Starten des Dienstes eingetragen werden.

== Installation von Ruby ==

Als User ''xyz00-discourse'': Installation von Ruby mit ''rbenv'' mit folgenden Befehlen:

Zunächst ''rbenv'' and ''ruby-build'':

<syntaxhighlight lang=shell line>
git clone https://github.com/rbenv/rbenv.git ~/.rbenv
cd ~/.rbenv && src/configure && make -C src
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.profile
echo 'eval "$(rbenv init -)"' >> ~/.profile
</syntaxhighlight>

starte neue Shell:

<syntaxhighlight lang=shell>
exec bash
</syntaxhighlight>

Überprüfe rbenv-Installation

<syntaxhighlight lang=shell>
type rbenv
</syntaxhighlight>

Installiere ruby-build als rbenv-Plugin

<syntaxhighlight lang=shell>
git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build
</syntaxhighlight>

Nun kann die benötigte Ruby-Version installiert werden:

<syntaxhighlight lang=shell>
rbenv install 2.4
</syntaxhighlight>

== Installation von Discourse selber ==

Weiterhin Als User ''xyz00-discourse'':

<syntaxhighlight lang=shell>
cd ~
git clone https://github.com/discourse/discourse.git discourse
cd ~/discourse
</syntaxhighlight>

Die stabile Version auschecken:

<syntaxhighlight lang=shell>
git checkout stable
</syntaxhighlight>

Ruby Pakete installieren:

<syntaxhighlight lang=shell>
gem install bundler
bundle install -j$(getconf _NPROCESSORS_ONLN) --deployment --without development test
</syntaxhighlight>

== Konfiguration der Discourse Software ==

Anlegen einer Datei ''/home/pacs/xyz00/users/discourse/discourse/config/discourse.conf'' anhand der Beispiel-Datei:

<syntaxhighlight lang=shell>
cd ~/discourse
cp config/discourse_defaults.conf config/discourse.conf
</syntaxhighlight>

Anpassen folgender Inhalte:
<syntaxhighlight lang=ini line>
db_host = 127.0.0.1
db_port = 5432
#db_backup_port = 5432 #(auskommentieren)
db_name = xyz00_discoursedb
db_username = xyz00_discourseuser
db_password = "" #db password
hostname = "discourse.xyz00" # hostname
smtp_address = localhost
smtp_enable_start_tls = false
smtp_openssl_verify_mode = 'none'
developer_emails = # your email-address
redis_host = 127.0.0.1
redis_port = 32002
</syntaxhighlight>
===TODO: Secrets setzen! ===
Die Zufallswerte für die Variablen SECRET_KEY_BASE und OTP_SECRET erzeugt man durch zwei Aufrufe des Kommandos

<syntaxhighlight lang=shell>
RAILS_ENV=production bundle exec rake secret
</syntaxhighlight>

=== Sidekiq für Hintergrund-Aufgaben konfigurieren ===

''config/sidekiq.conf''

Wichtig: development auf production ändern.

Mit diesem Dienst werden z.B. die E-Mails zur Aktivierung oder zum Passwort Reset verschickt.

=== Problem mit Content Security Policy ===

Um ein Problem mit Content Security Policy zu lösen, weil manche Dateien über http nachgeladen werden, muss in der Datei <code>config/site_settings.yml</code> der Default Wert für force_https auf True gesetzt werden:
<syntaxhighlight lang=yaml line>
force_https:
default: true
</syntaxhighlight>
=== Problem beim Aufsetzen der Datenbank vermeiden ===

'''→ Notiz Mai 2024:''' dies scheint aktuell nicht aufzutreten.

Aus irgendeinem Grund wird beim Initialisieren der Datenbank versucht, den TYPE hotlinked_media_status zweimal in der Datenbank anzulegen. Der Grund ist nicht ersichtlich.

Es kann folgende Änderung an der Datei <code>db/migrate/20220428094026_create_post_hotlinked_media.rb</code> vorgenommen werden:
<syntaxhighlight lang=ruby line>
reversible do |dir|
dir.up { execute <<~SQL }
DO $$ BEGIN CREATE TYPE hotlinked_media_status AS ENUM('downloaded', 'too_large', 'download_failed', 'upload_create_failed'); EXCEPTION WHEN duplicate_object THEN null; END $$;
SQL
dir.down { execute <<~SQL }
DROP TYPE hotlinked_media_status
SQL
end
</syntaxhighlight>
=== Initialisieren der Datenbank ===

<syntaxhighlight lang=shell>
export SAFETY_ASSURED=1
# In Version 2.0.4 funktioniert db:migrate noch, ansonsten db:schema:load und seed nutzen!
# In Version 3.0.3 funktioniert db:migrate auch noch, db:schema:load ging nicht weil die Datei structure.sql fehlte
#RAILS_ENV=production bundle exec rails db:schema:load
#RAILS_ENV=production bundle exec rails db:seed
RAILS_ENV=production bundle exec rails db:migrate
</syntaxhighlight>

=== Kompilieren der Assets ===

<syntaxhighlight lang=shell>
RAILS_ENV=production bundle exec rails assets:precompile
</syntaxhighlight>

=== Konfiguration des Web-Servers (am Beispiel Puma) ===

Die Datei ''config/puma.conf'' anpassen (hier nur Änderungen angezeigt):

<syntaxhighlight lang=ini>
APP_ROOT = '/home/pacs/xyz00/users/discourse/discourse'
daemonize false
</syntaxhighlight>

== Starten der Dienste ==

Zum Start aller notwendigen Dienste sollte systemd benutzt werden.

Die folgenden Dateien müssen nach <code>.config/systemd/user/</code> kopiert werden (überlange Zeilen werden hier im Wiki umgebrochen)

redis.service:

<syntaxhighlight lang=ini line>
[Unit]
Description=Redis User Service

[Service]
WorkingDirectory=%h/var/redis
Environment="PATH=/usr/local/bin:/usr/bin:/bin"
ExecStart=%h/bin/redis-server %h/etc/redis.conf
Restart=always
PrivateTmp=true
NoNewPrivileges=true

[Install]
WantedBy=default.target
</syntaxhighlight>

sidekiq.service:

<syntaxhighlight lang=ini line>
[Unit]
Description=Discourse Sidekiq Service

[Service]
WorkingDirectory=%h/discourse
Environment="PATH=/usr/local/bin:/usr/bin:/bin"
Environment="RAILS_ENV=production"
Environment="DB_POOL=8"
Environment="MALLOC_ARENA_MAX=2"
ExecStart=%h/.rbenv/shims/bundle exec sidekiq -C %h/discourse/config/sidekiq.yml
StandardOutput=append:%h/var/log/sidekiq.out.log
StandardError=inherit
Restart=always
PrivateTmp=true
NoNewPrivileges=true

[Install]
WantedBy=default.target
After=redis.service
</syntaxhighlight>

discourse.service:

<syntaxhighlight lang=ini line>
[Unit]
Description=Discourse Web Service

[Service]
WorkingDirectory=%h/discourse
Environment="PATH=/usr/local/bin:/usr/bin:/bin"
Environment="RAILS_ENV=production"
Environment="WEB_CONCURRENCY=2"
Environment="MAX_THREADS=5"
Environment="MALLOC_ARENA_MAX=2"
ExecStart=%h/.rbenv/shims/bundle exec puma -C config/puma.rb -e production -b tcp://127.0.0.1:13000
StandardOutput=append:%h/var/log/puma.out.log
StandardError=inherit
Restart=always
PrivateTmp=true
NoNewPrivileges=true

[Install]
WantedBy=default.target
After=redis.service
</syntaxhighlight>

== Einrichten des Apache VHost ==

<syntaxhighlight lang=shell>
cd ~/doms/beispiel.discuss
rm -rf htdocs-ssl subs/www subs-ssl/www
ln -s ~/live/public htdocs-ssl
touch htdocs-ssl/.htaccess
</syntaxhighlight>

Dann die ''htdocs-ssl/.htaccess'' (durch das gelinkte Verzeichnis entspricht das dem Pfad /home/pacs/xyz00/users/discourse/discourse/public/.htaccess ) mit dem Editor der Wahl öffnen und folgende Konfiguration einfügen:

<syntaxhighlight lang=apache line>
DirectoryIndex disabled

RequestHeader set X-Forwarded-Proto "https"

RewriteEngine On
RewriteBase /
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-l
RewriteRule .* http://127.0.0.1:13000%{REQUEST_URI} [proxy,last]
</syntaxhighlight>
== Wartung ==
=== Backup ===

Discourse macht selbstätig backups und legt diese unter 'public/backups' ab. Enthalten ist ein Datenbank-Dump und die hochgeladenen Dateien.

Im Admin-Bereich lassen sich backups auch manuell antreten.

=== Admin Benutzer einladen ===

Manchmal brauchen wir einen neuen Admin Benutzer, den wir von der Kommandozeile aus einladen möchten.

<syntaxhighlight lang=shell>
cd /discourse
RAILS_ENV=production rake admin:invite[admin@example.org]
</syntaxhighlight>

=== Import aus mbox Archiven ===

Um zum Beispiel ein Mailman2 Archiv zu importieren, wo die Nachrichten als .mbox Datei vorliegen, sind folgende Schritte nötig:

Vorbereitungen an Discourse:

<syntaxhighlight lang=shell>
source .profile
cd discourse
bundle config set frozen false
IMPORT=1 bundle install
bundle config set frozen true
nano script/import_scripts/mbox/settings.yml
# dort ändern:
# data_dir: /home/pacs/xyz00/users/discourse/list-archiv
</syntaxhighlight>

Hochladen der Mailinglisten-Archive:
<syntaxhighlight lang=shell>
mkdir ~/list-archiv
# dort muss es Unterordner mit dem Namen der gewünschten Kategorie geben,
# und die mbox Datei muss auch diesen Namen haben, z.B.:
# ~/list-archiv/beispiel/beispiel.mbox
# ~/list-archiv/example/example.mbox
# um die Beiträge in den entsprechenden Kategorien beispiel und example einzufügen.
</syntaxhighlight>

Durchführen des Imports:
<syntaxhighlight lang=shell>
source .profile
cd discourse
RAILS_ENV=production IMPORT=1 bundle exec rails runner \
script/import_scripts/mbox.rb script/import_scripts/mbox/settings.yml
</syntaxhighlight>

=== Export ===
* Wenn ein Forum beendet wird, möchte man evtl. eine Sicherung als statische HTML Seiten.
** Das wird hier diskutiert: https://meta.discourse.org/t/how-do-i-export-the-complete-forum-as-static-html-pages/71007/3
* Um ein Forum von Discourse zu Flarum umzuziehen, hat Timotheus ein Skript geschrieben.
** Das Migrations-Skript: https://github.com/SolidCharity/discourse_to_flarum
** siehe auch https://discuss.flarum.org/d/4930-discourse-to-flarum-migration-support/29

=== Updates ===

Discourse wird über update via mail informieren (dies kann man m.W. abschalten).

Achtung: bei größeren Updates auch immer Änderungen an der Datei site_settings.yml (https://github.com/discourse/discourse/blob/main/config/site_settings.yml) beachten!

Siehe auch die unterstützten Releases: https://releases.discourse.org/ und die Tags: https://github.com/discourse/discourse/tags

==== Am Beispiel von 2025.12.0 auf 2026.1.1 ====

# Im Web-Backend unter Administration->Backups-> Read-Only Mouds setzen (oder Web Server so konfigurieren, dass keine Zugriffe mehr stattfinden können)
# Backup
# Die lokalen Änderungen sichern:
# cd discourse
# mv ~/plugins.bak/discourse-ai plugins
# git diff v2025.12.0 > diff-2025.12.0.txt
# git fetch
# git checkout -b hostsharing-deployment-v2026.1.1 v2026.1.1
# evtl. Änderungen aus diff-2025.12.0.txt wieder übernehmen und committen
# patch -p1 < diff-2025.12.0.txt
# git commit -a -m "spezifische Änderungen für diese Instanz" --no-verify
# Schauen, ob discourse eine neue Ruby-Version nutzt (z.B. in https://github.com/discourse/discourse_docker/blob/main/image/base/Dockerfile bzw. https://github.com/discourse/discourse/blob/v2026.1.1/Gemfile)
# Ist dies der Fall, dann:
# rbenv install 3.3.8
# rbenv global 3.3.8
# rbenv rehash
# echo "3.3.8" > .ruby-version
# installiere Node 22: https://codeberg.org/tpokorra/hostsharing-scripts/src/branch/main/install-nodejs.sh
# source ~/.profile
# gem update --system
# bundle install
# npm install -g terser uglify-js pnpm@9
# corepack use pnpm@latest-10
# pnpm install
# export $(grep -v '^#' ~/discourse.env | xargs -d '\n')
# source ~/.profile
# wir haben keine pg extension pg_vector, daher deaktivieren wir das Plugin während migrate, aber auch für später damit /admin/settings funktioniert:
# mkdir -p ~/plugins.bak
# mv plugins/discourse-ai ~/plugins.bak
# RAILS_ENV=production bundle exec rake db:migrate
# RAILS_ENV=production bundle exec rake assets:precompile
# Services neu starten
<syntaxhighlight lang=shell>
systemctl --user restart puma
systemctl --user restart sidekiq
systemctl --user restart redis
</syntaxhighlight>
* Zuletzt: Read-Only Modus wieder deaktivieren

=== Debugging ===

Es können folgende Einstellungen in der Datei config/environments/production.rb vorgenommen werden. Danach den Puma Dienst neustarten. Fehlermeldungen und Stacktraces werden dann im Browser ausgegeben.

<syntaxhighlight lang="ini" line>
config.log_level = :debug
config.action_dispatch.show_exceptions = :all
config.action_dispatch.debug_exception_log_level = :error

# Full error reports are enabled and caching is turned off
config.consider_all_requests_local = true
config.action_controller.perform_caching = false
</syntaxhighlight>

=== Erforderliche Anpassungen ===
Weil wir bei Debian Bookworm noch mit ImageMagick 6.9 arbeiten, muss dieser [https://github.com/discourse/discourse/commit/17aa831337e352dfd875f1b4ddc4492bd0835119 Patch] rückgängig gemacht werden:

<syntaxhighlight lang="bash" line>
wget https://github.com/discourse/discourse/commit/17aa831337e352dfd875f1b4ddc4492bd0835119.patch -O ~/imagemagick.patch
patch -p1 --reverse < ~/imagemagick.patch
git commit -a -m "revert imagemagick patch" --no-verify
</syntaxhighlight>

== ToDos ==

* Ein Patch, um Discourse auch via Unix-Socket mit Redis sprechen lassen zu können dürfte relativ einfach sein (es wird ein Wrapper um das redis-gem genutzt).
* Konfiguration von discourse, um mit postgresql via Unix-Socket zu kommunizieren (DISCOURSE_DB_SOCKET environment variable)
* Performance-tuning an diversen Stellen, anhand der discourse_docker-Vorgaben (https://github.com/discourse/discourse_docker), z.B.
** thpoff (huge page settings)
** unicorn (hat eine wesentlich ausgefeiltere Konfigurations-Vorlage, wahrscheinlich bereits ordentlich optimiert)

== Links ==

* https://help.skysilk.com/support/solutions/articles/9000120927-how-to-install-discourse-without-docker-using-skysilk-vps-
* https://github.com/discourse/discourse_docker
* https://github.com/discourse/discourse
* https://codeberg.org/tpokorra/hs.ansible/src/branch/main/playbooks/discourse

== Historie ==

* 2018, 14 . September: Initiale Fassung
* 2019, Januar: Update-Informationen ergänzt
* 2022, Juni: systemd Dienste, Discourse 3.0

----
[[Kategorie:HSDoku]]
[[Kategorie:Installationsanleitungen]]
[[Kategorie:RubyOnRails]]
[[Kategorie:Webforen]]
[[Kategorie:Ansible Playbook]]

Discourse installieren

2026-03-05T19:39:00Z

Tim00: siehe Ruby Version in Gemfile

{{Textkasten|gelb|Für Managed Server|Ein funktionierender Discourse-Server erfordert mehrere laufende Server-Dienste. Für den Betrieb ist ein Managed Server sinnvoll.}}

{{Textkasten|rot|Support von der Discourse-Community|Die Discourse-Entwickler haben sich entschieden, nur eine mehr oder weniger genormte Installationsmethode (via docker) zu unterstützen. Dies ist so auf der hostsharing-Architektur aufgrund mehrerer Bedenken und Überlegungen nicht möglich. Die Community ist durchaus hilfreich, geht aber davon aus, dass quasi alle Nutzer* eine "supported"e Installation durchgeführt haben. Wenn man in entsprechenden Kanälen nach Hilfe fragt, sollte man unbedingt erwähnen, dass man discourse selber anhand dieser hier lesbaren Anleitung installiert hat, um bereits entsprechenden Kommentaren und Nachfragen vorzugreifen.}}

== Über ==

In diesem Artikel wird die Installation von discourse, Version 2.1.0 (September 2018) beschrieben.

== Vorbereitungen ==

Mit Hilfe von HSAdmin wird angelegt:
# Ein User als Service-User mit ''/bin/bash'' als Shell, zum Beispiel Beispiel: ''xyz00-discourse''
# Eine Domain mit ''xyz00-discourse' als Domain-Administrator, zum Beispiel ''beispiel.discussion''
# Einen Postgresql-User ''xyz00_discourseuser'' mit Passwort ''meinPasswort''
# Eine Postgresql-Datenbank ''xyz00_discoursedb'' mit Datenbank-Owner ''xyz00_discourseuser''

Verwendete IP-Ports der Server-Dienste:
# Redis: localhost:32002
# Discourse-Web: localhost:13000

== Konfiguration der PostgreSQL Datenbank ==

Es müssen noch Erweiterungen für Postgresql installiert werden:

<syntaxhighlight lang=shell line>
psql --user xyz00_discourseuser -c "CREATE EXTENSION IF NOT EXISTS hstore WITH SCHEMA public;"
psql --user xyz00_discourseuser -c "CREATE EXTENSION IF NOT EXISTS pg_trgm WITH SCHEMA public;"
psql --user xyz00_discourseuser -c "CREATE EXTENSION IF NOT EXISTS unaccent WITH SCHEMA public;"
</syntaxhighlight>

== Konfiguration des Redis Server ==

{{Textkasten|gelb|Firewall/Redis Port|Leider unterstützt discourse nicht die Kommunikation mit Redis über Unix-Sockets. Dementsprechend muss der für Redis konfigurierte Port von dem hostsharing-Support in der Firewall freigegeben werden.}}

<syntaxhighlight lang=shell>
cd
mkdir redis/etc redis/lib redis/log redis/run
</syntaxhighlight>

Anlegen einer Datei ''/home/pacs/xyz00/users/discourse/redis/etc/redis.conf'' mit folgendem Inhalt:

<syntaxhighlight lang=shell line>
daemonize no
pidfile /home/pacs/xyz00/users/discourse/redis/run/redis-server.pid
port 32002
tcp-backlog 128
bind 127.0.0.1
timeout 300
loglevel notice
logfile /home/pacs/xyz00/users/discourse/redis/log/redis.log
databases 16
save 900 1
save 300 10
save 60 10000
slave-serve-stale-data yes
appendonly no
dbfilename dump.rdb
dir /home/pacs/xyz00/users/discourse/redis/lib
</syntaxhighlight>

Für Discourse 3.x gilt: "Discourse requires Redis 6.2.0 or up"

Für Debian Buster und Bullseye ist daher das Installieren eines neueren Binaries erforderlich. Bei Debian Bookwork ist bereits Redis 7.0 enthalten (siehe https://packages.debian.org/search?keywords=redis-server).

Hier steht ein entsprechendes Binary für Debian Buster zur Verfügung, das mit dem Public Key von Timotheus geprüft werden kann:

* https://download.solidcharity.com/tarballs/tpokorra/hostsharing/redis-server-6.2.12-debian-buster.tar.gz
* Prüfsignatur: https://download.solidcharity.com/tarballs/tpokorra/hostsharing/redis-server-6.2.12-debian-buster.tar.gz.sig

Prüfen der Signatur:

<syntaxhighlight lang=shell>
gpg --verify redis-server-6.2.12-debian-buster.tar.gz.sig redis-server-6.2.12-debian-buster.tar.gz
</syntaxhighlight>

Das Binary muss nach <code>$HOME/bin</code> verschoben werden, und entsprechend beim Starten des Dienstes eingetragen werden.

== Installation von Ruby ==

Als User ''xyz00-discourse'': Installation von Ruby mit ''rbenv'' mit folgenden Befehlen:

Zunächst ''rbenv'' and ''ruby-build'':

<syntaxhighlight lang=shell line>
git clone https://github.com/rbenv/rbenv.git ~/.rbenv
cd ~/.rbenv && src/configure && make -C src
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.profile
echo 'eval "$(rbenv init -)"' >> ~/.profile
</syntaxhighlight>

starte neue Shell:

<syntaxhighlight lang=shell>
exec bash
</syntaxhighlight>

Überprüfe rbenv-Installation

<syntaxhighlight lang=shell>
type rbenv
</syntaxhighlight>

Installiere ruby-build als rbenv-Plugin

<syntaxhighlight lang=shell>
git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build
</syntaxhighlight>

Nun kann die benötigte Ruby-Version installiert werden:

<syntaxhighlight lang=shell>
rbenv install 2.4
</syntaxhighlight>

== Installation von Discourse selber ==

Weiterhin Als User ''xyz00-discourse'':

<syntaxhighlight lang=shell>
cd ~
git clone https://github.com/discourse/discourse.git discourse
cd ~/discourse
</syntaxhighlight>

Die stabile Version auschecken:

<syntaxhighlight lang=shell>
git checkout stable
</syntaxhighlight>

Ruby Pakete installieren:

<syntaxhighlight lang=shell>
gem install bundler
bundle install -j$(getconf _NPROCESSORS_ONLN) --deployment --without development test
</syntaxhighlight>

== Konfiguration der Discourse Software ==

Anlegen einer Datei ''/home/pacs/xyz00/users/discourse/discourse/config/discourse.conf'' anhand der Beispiel-Datei:

<syntaxhighlight lang=shell>
cd ~/discourse
cp config/discourse_defaults.conf config/discourse.conf
</syntaxhighlight>

Anpassen folgender Inhalte:
<syntaxhighlight lang=ini line>
db_host = 127.0.0.1
db_port = 5432
#db_backup_port = 5432 #(auskommentieren)
db_name = xyz00_discoursedb
db_username = xyz00_discourseuser
db_password = "" #db password
hostname = "discourse.xyz00" # hostname
smtp_address = localhost
smtp_enable_start_tls = false
smtp_openssl_verify_mode = 'none'
developer_emails = # your email-address
redis_host = 127.0.0.1
redis_port = 32002
</syntaxhighlight>
===TODO: Secrets setzen! ===
Die Zufallswerte für die Variablen SECRET_KEY_BASE und OTP_SECRET erzeugt man durch zwei Aufrufe des Kommandos

<syntaxhighlight lang=shell>
RAILS_ENV=production bundle exec rake secret
</syntaxhighlight>

=== Sidekiq für Hintergrund-Aufgaben konfigurieren ===

''config/sidekiq.conf''

Wichtig: development auf production ändern.

Mit diesem Dienst werden z.B. die E-Mails zur Aktivierung oder zum Passwort Reset verschickt.

=== Problem mit Content Security Policy ===

Um ein Problem mit Content Security Policy zu lösen, weil manche Dateien über http nachgeladen werden, muss in der Datei <code>config/site_settings.yml</code> der Default Wert für force_https auf True gesetzt werden:
<syntaxhighlight lang=yaml line>
force_https:
default: true
</syntaxhighlight>
=== Problem beim Aufsetzen der Datenbank vermeiden ===

'''→ Notiz Mai 2024:''' dies scheint aktuell nicht aufzutreten.

Aus irgendeinem Grund wird beim Initialisieren der Datenbank versucht, den TYPE hotlinked_media_status zweimal in der Datenbank anzulegen. Der Grund ist nicht ersichtlich.

Es kann folgende Änderung an der Datei <code>db/migrate/20220428094026_create_post_hotlinked_media.rb</code> vorgenommen werden:
<syntaxhighlight lang=ruby line>
reversible do |dir|
dir.up { execute <<~SQL }
DO $$ BEGIN CREATE TYPE hotlinked_media_status AS ENUM('downloaded', 'too_large', 'download_failed', 'upload_create_failed'); EXCEPTION WHEN duplicate_object THEN null; END $$;
SQL
dir.down { execute <<~SQL }
DROP TYPE hotlinked_media_status
SQL
end
</syntaxhighlight>
=== Initialisieren der Datenbank ===

<syntaxhighlight lang=shell>
export SAFETY_ASSURED=1
# In Version 2.0.4 funktioniert db:migrate noch, ansonsten db:schema:load und seed nutzen!
# In Version 3.0.3 funktioniert db:migrate auch noch, db:schema:load ging nicht weil die Datei structure.sql fehlte
#RAILS_ENV=production bundle exec rails db:schema:load
#RAILS_ENV=production bundle exec rails db:seed
RAILS_ENV=production bundle exec rails db:migrate
</syntaxhighlight>

=== Kompilieren der Assets ===

<syntaxhighlight lang=shell>
RAILS_ENV=production bundle exec rails assets:precompile
</syntaxhighlight>

=== Konfiguration des Web-Servers (am Beispiel Puma) ===

Die Datei ''config/puma.conf'' anpassen (hier nur Änderungen angezeigt):

<syntaxhighlight lang=ini>
APP_ROOT = '/home/pacs/xyz00/users/discourse/discourse'
daemonize false
</syntaxhighlight>

== Starten der Dienste ==

Zum Start aller notwendigen Dienste sollte systemd benutzt werden.

Die folgenden Dateien müssen nach <code>.config/systemd/user/</code> kopiert werden (überlange Zeilen werden hier im Wiki umgebrochen)

redis.service:

<syntaxhighlight lang=ini line>
[Unit]
Description=Redis User Service

[Service]
WorkingDirectory=%h/var/redis
Environment="PATH=/usr/local/bin:/usr/bin:/bin"
ExecStart=%h/bin/redis-server %h/etc/redis.conf
Restart=always
PrivateTmp=true
NoNewPrivileges=true

[Install]
WantedBy=default.target
</syntaxhighlight>

sidekiq.service:

<syntaxhighlight lang=ini line>
[Unit]
Description=Discourse Sidekiq Service

[Service]
WorkingDirectory=%h/discourse
Environment="PATH=/usr/local/bin:/usr/bin:/bin"
Environment="RAILS_ENV=production"
Environment="DB_POOL=8"
Environment="MALLOC_ARENA_MAX=2"
ExecStart=%h/.rbenv/shims/bundle exec sidekiq -C %h/discourse/config/sidekiq.yml
StandardOutput=append:%h/var/log/sidekiq.out.log
StandardError=inherit
Restart=always
PrivateTmp=true
NoNewPrivileges=true

[Install]
WantedBy=default.target
After=redis.service
</syntaxhighlight>

discourse.service:

<syntaxhighlight lang=ini line>
[Unit]
Description=Discourse Web Service

[Service]
WorkingDirectory=%h/discourse
Environment="PATH=/usr/local/bin:/usr/bin:/bin"
Environment="RAILS_ENV=production"
Environment="WEB_CONCURRENCY=2"
Environment="MAX_THREADS=5"
Environment="MALLOC_ARENA_MAX=2"
ExecStart=%h/.rbenv/shims/bundle exec puma -C config/puma.rb -e production -b tcp://127.0.0.1:13000
StandardOutput=append:%h/var/log/puma.out.log
StandardError=inherit
Restart=always
PrivateTmp=true
NoNewPrivileges=true

[Install]
WantedBy=default.target
After=redis.service
</syntaxhighlight>

== Einrichten des Apache VHost ==

<syntaxhighlight lang=shell>
cd ~/doms/beispiel.discuss
rm -rf htdocs-ssl subs/www subs-ssl/www
ln -s ~/live/public htdocs-ssl
touch htdocs-ssl/.htaccess
</syntaxhighlight>

Dann die ''htdocs-ssl/.htaccess'' (durch das gelinkte Verzeichnis entspricht das dem Pfad /home/pacs/xyz00/users/discourse/discourse/public/.htaccess ) mit dem Editor der Wahl öffnen und folgende Konfiguration einfügen:

<syntaxhighlight lang=apache line>
DirectoryIndex disabled

RequestHeader set X-Forwarded-Proto "https"

RewriteEngine On
RewriteBase /
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-l
RewriteRule .* http://127.0.0.1:13000%{REQUEST_URI} [proxy,last]
</syntaxhighlight>
== Wartung ==
=== Backup ===

Discourse macht selbstätig backups und legt diese unter 'public/backups' ab. Enthalten ist ein Datenbank-Dump und die hochgeladenen Dateien.

Im Admin-Bereich lassen sich backups auch manuell antreten.

=== Admin Benutzer einladen ===

Manchmal brauchen wir einen neuen Admin Benutzer, den wir von der Kommandozeile aus einladen möchten.

<syntaxhighlight lang=shell>
cd /discourse
RAILS_ENV=production rake admin:invite[admin@example.org]
</syntaxhighlight>

=== Import aus mbox Archiven ===

Um zum Beispiel ein Mailman2 Archiv zu importieren, wo die Nachrichten als .mbox Datei vorliegen, sind folgende Schritte nötig:

Vorbereitungen an Discourse:

<syntaxhighlight lang=shell>
source .profile
cd discourse
bundle config set frozen false
IMPORT=1 bundle install
bundle config set frozen true
nano script/import_scripts/mbox/settings.yml
# dort ändern:
# data_dir: /home/pacs/xyz00/users/discourse/list-archiv
</syntaxhighlight>

Hochladen der Mailinglisten-Archive:
<syntaxhighlight lang=shell>
mkdir ~/list-archiv
# dort muss es Unterordner mit dem Namen der gewünschten Kategorie geben,
# und die mbox Datei muss auch diesen Namen haben, z.B.:
# ~/list-archiv/beispiel/beispiel.mbox
# ~/list-archiv/example/example.mbox
# um die Beiträge in den entsprechenden Kategorien beispiel und example einzufügen.
</syntaxhighlight>

Durchführen des Imports:
<syntaxhighlight lang=shell>
source .profile
cd discourse
RAILS_ENV=production IMPORT=1 bundle exec rails runner \
script/import_scripts/mbox.rb script/import_scripts/mbox/settings.yml
</syntaxhighlight>

=== Export ===
* Wenn ein Forum beendet wird, möchte man evtl. eine Sicherung als statische HTML Seiten.
** Das wird hier diskutiert: https://meta.discourse.org/t/how-do-i-export-the-complete-forum-as-static-html-pages/71007/3
* Um ein Forum von Discourse zu Flarum umzuziehen, hat Timotheus ein Skript geschrieben.
** Das Migrations-Skript: https://github.com/SolidCharity/discourse_to_flarum
** siehe auch https://discuss.flarum.org/d/4930-discourse-to-flarum-migration-support/29

=== Updates ===

Discourse wird über update via mail informieren (dies kann man m.W. abschalten).

Achtung: bei größeren Updates auch immer Änderungen an der Datei site_settings.yml (https://github.com/discourse/discourse/blob/main/config/site_settings.yml) beachten!

Siehe auch die unterstützten Releases: https://releases.discourse.org/ und die Tags: https://github.com/discourse/discourse/tags

==== Am Beispiel von 3.4.7 auf 3.5.1 ====

# Im Web-Backend unter Administration->Backups-> Read-Only Mouds setzen (oder Web Server so konfigurieren, dass keine Zugriffe mehr stattfinden können)
# Backup
# Die lokalen Änderungen sichern:
# cd discourse
# mv ~/plugins.bak/discourse-ai plugins
# git diff v3.4.7 > diff-3.4.7.txt
# git fetch
# git checkout -b hostsharing-deployment-v3.5.1 v3.5.1
# evtl. Änderungen aus diff-3.4.7.txt wieder übernehmen und committen
# patch -p1 < diff-3.4.7.txt
# git commit -a -m "spezifische Änderungen für diese Instanz" --no-verify
# Schauen, ob discourse eine neue Ruby-Version nutzt (z.B. in https://github.com/discourse/discourse_docker/blob/main/image/base/Dockerfile bzw. https://github.com/discourse/discourse/blob/v2026.1.1/Gemfile)
# Dies ist der Fall, also
# rbenv install 3.3.8
# rbenv global 3.3.8
# rbenv rehash
# echo "3.3.8" > .ruby-version
# installiere Node 22: https://codeberg.org/tpokorra/hostsharing-scripts/src/branch/main/install-nodejs.sh
# source ~/.profile
# gem update --system
# bundle install
# npm install -g terser uglify-js pnpm@9
# corepack use pnpm@latest-9
# pnpm install
# export $(grep -v '^#' ~/discourse.env | xargs -d '\n')
# source ~/.profile
# wir haben keine pg extension pg_vector, daher deaktivieren wir das Plugin während migrate, aber auch für später damit /admin/settings funktioniert:
# mkdir -p ~/plugins.bak
# mv plugins/discourse-ai ~/plugins.bak
# RAILS_ENV=production bundle exec rake db:migrate
# RAILS_ENV=production bundle exec rake assets:precompile
# Services neu starten
<syntaxhighlight lang=shell>
systemctl --user restart puma
systemctl --user restart sidekiq
systemctl --user restart redis
</syntaxhighlight>
* Zuletzt: Read-Only Modus wieder deaktivieren

=== Debugging ===

Es können folgende Einstellungen in der Datei config/environments/production.rb vorgenommen werden. Danach den Puma Dienst neustarten. Fehlermeldungen und Stacktraces werden dann im Browser ausgegeben.

<syntaxhighlight lang="ini" line>
config.log_level = :debug
config.action_dispatch.show_exceptions = :all
config.action_dispatch.debug_exception_log_level = :error

# Full error reports are enabled and caching is turned off
config.consider_all_requests_local = true
config.action_controller.perform_caching = false
</syntaxhighlight>

=== Erforderliche Anpassungen ===
Weil wir bei Debian Bookworm noch mit ImageMagick 6.9 arbeiten, muss dieser [https://github.com/discourse/discourse/commit/17aa831337e352dfd875f1b4ddc4492bd0835119 Patch] rückgängig gemacht werden:

<syntaxhighlight lang="bash" line>
wget https://github.com/discourse/discourse/commit/17aa831337e352dfd875f1b4ddc4492bd0835119.patch -O ~/imagemagick.patch
patch -p1 --reverse < ~/imagemagick.patch
git commit -a -m "revert imagemagick patch" --no-verify
</syntaxhighlight>

== ToDos ==

* Ein Patch, um Discourse auch via Unix-Socket mit Redis sprechen lassen zu können dürfte relativ einfach sein (es wird ein Wrapper um das redis-gem genutzt).
* Konfiguration von discourse, um mit postgresql via Unix-Socket zu kommunizieren (DISCOURSE_DB_SOCKET environment variable)
* Performance-tuning an diversen Stellen, anhand der discourse_docker-Vorgaben (https://github.com/discourse/discourse_docker), z.B.
** thpoff (huge page settings)
** unicorn (hat eine wesentlich ausgefeiltere Konfigurations-Vorlage, wahrscheinlich bereits ordentlich optimiert)

== Links ==

* https://help.skysilk.com/support/solutions/articles/9000120927-how-to-install-discourse-without-docker-using-skysilk-vps-
* https://github.com/discourse/discourse_docker
* https://github.com/discourse/discourse
* https://codeberg.org/tpokorra/hs.ansible/src/branch/main/playbooks/discourse

== Historie ==

* 2018, 14 . September: Initiale Fassung
* 2019, Januar: Update-Informationen ergänzt
* 2022, Juni: systemd Dienste, Discourse 3.0

----
[[Kategorie:HSDoku]]
[[Kategorie:Installationsanleitungen]]
[[Kategorie:RubyOnRails]]
[[Kategorie:Webforen]]
[[Kategorie:Ansible Playbook]]

Etherpad Installieren

2026-03-05T10:17:05Z

Tim00: Aktualisierung auf 2.6.1 mit mindestens Node 20

= Etherpad Lite installieren =

Etherpad ist eine JavaScript-Anwendung mit der mehrere Bearbeiter gleichzeitig einen Text im Browser editieren können.

Mit Hilfe von Etherpad können zum Beispiel die Teilnehmer einer Telefonkonferenz gemeinsam an einem Text-Dokument arbeiten.

== Vorbereitung ==

Als Paket-Admin ''xyz00'' werden mit HSAdmin ein User angelegt und eine Domain aufgeschaltet. Eine produktive Installation von Etherpad braucht zusätzlich einen MySQL-User und eine MySQL-Datenbank.

Mit ''hsscript'' können diese Ressourcen wie folgt angelegt werden:

Als Paketadmin ''xyz00'' aufrufen: <code>hsscript -i</code>

In der HSAdmin-Shell gibt man dann ein:

<syntaxhighlight lang=shell>
xyz00@hsadmin> user.add({set:{name:'xyz00-pad', password:'mein-Geheimwort', shell:'/bin/bash'}})
xyz00@hsadmin> domain.add({set:{name:'pad.example.com', user:'xyz00-pad'}})
xyz00@hsadmin> mysqluser.add({set:{name:'xyz00_padusr', password:'anderes-Geheimwort'}})
xyz00@hsadmin> mysqldb.add({set:{name:'xyz00_paddb', owner:'xyz00_padusr'}})
xyz00@hsadmin> bye
</syntaxhighlight>

== Installation ==

Etherpad v2.6.1 benötigt ''nodejs'' in einer Version >= 20. Die Installation erfolgt gemäß der Wiki-Anleitung: [[NodeJS]]

Zusätzlich muss der Paketmanager pnpm für Version 2 vorgehalten werden

npm install pnpm@latest-10

Als Paketadmin ''xyz00'' nimmt man mit <code>sudo -u xyz00-pad -i</code> die Rechte des Domain-Administrators ''xyz00-pad'' für die neue Domain ''pad.example.com'' an.

Die Etherpad-Software kann aus dem Git-Repository bei Github ausgecheckt werden:

<syntaxhighlight lang=shell>
cd
git clone https://github.com/ether/etherpad-lite.git
cd etherpad-lite/
git tag -l
git checkout tags/2.6.1
./bin/run.sh
</syntaxhighlight>

Mit "git checkout tags/2.6.1" wird Release 2.6.1 ausgecheckt, die heute (05.03.2026) aktuelle Version.

Bei der Initialisierung der Anwendung gibt es einige Warnungen, die man ignorieren kann. Wenn die Initialisierung durchgelaufen ist, kann man
unter der URL http://xyz00.hostsharing.net:9001/ schon die die Etherpad-Anwendung ohne Datenbank und ohne die gewünschte Domain sehen.

Wir brechen das ''run.sh''-Skript mit Ctrl-c ab.

== v2: Konfiguration mit Proxy und systemd ==

# ~/.config/systemd/user/etherpad-lite.service
[Unit]
Description=Etherpad-Lite Service
[Service]
WorkingDirectory=%h/etherpad-lite
Environment="NODE_ENV=production"
Environment="BIND=127.0.0.1"
Environment="PATH=/home/pacs/xyz00/users/tools_pad/.nvm/versions/node/v20.18.3/bin:/usr/local/bin:/usr/bin:/bin"
ExecStart=%h/.nvm/versions/node/v20.18.3/bin/pnpm run prod
[Install]
WantedBy=default.target

# ~/doms/pad.example.com/.htaccess
DirectoryIndex disabled
RewriteBase /
RewriteCond %{HTTP:Connection} Upgrade [NC]
RewriteCond %{HTTP:Upgrade} websocket [NC]
RewriteRule .* ws://localhost:9001%{REQUEST_URI} [proxy]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-l
RewriteRule .* http://localhost:9001%{REQUEST_URI} [proxy]

Wichtig ist, dass auf 127.0.0.1 ge-binded wird, und nicht die von Welt erreichbare Adresse 0.0.0.0. Man beachte das im Systemd Service File die node version hardcoded wird und beim Update zwei mal entsprechend angepasst werden muss. Genauso der User und der Paketusername, der leider nicht direkt ersetzt werden kann.

Dass auch nach Neustart der Etherpad Server erreichbar ist:

systemctl --user enable etherpad-lite

== v1: Konfiguration für Apache und Passenger ==

Vor der Nutzung von [[Phusion Passenger]] bitte unbedingt die dortigen Hinweise zur Nutzung beachten.

Die statischen Dateien der Anwendung werden mit den folgenden Befehlen richtig verlinkt
(immer noch als User ''xyz00-pad''):

<syntaxhighlight lang=shell>
cd
cd ~/doms/pad.example.com
rm -rf subs/www
rm -rf subs-ssl/www
rm -rf htdocs-ssl
ln -s ~/etherpad-lite/src/static htdocs-ssl
</syntaxhighlight>

Für die Anwendung legen wir im Verzeichnis ''~/doms/pad.example.com/app-ssl/'' eine Datei app.js mit dem folgenden Inhalt an:

<syntaxhighlight lang=javascript>
require('/home/pacs/xyz00/users/pad/etherpad-lite/node_modules/ep_etherpad-lite/node/server.js');
process.chdir('/home/pacs/xyz00/users/pad/etherpad-lite');
</syntaxhighlight>

= Datenbank anpassen =

Zum Schluß wird in der Datei ''~/etherpad-lite/settings.js'' noch die MySQL-Datenbank konfiguriert. Dazu muss der Teil mit ''dbType: mysql'' aktiv (nicht auskommentiert) sein. Etwa wie folgt:

<syntaxhighlight lang=javascript>
"dbType" : "mysql",
"dbSettings" : {
"user" : "xyz00_padusr",
"host" : "localhost",
"password": "anderes-Geheimwort",
"database": "xyz00_paddb",
"charset" : "utf8mb4",
"insecureAuth": "true"
},
</syntaxhighlight>

Die Einstellungen für den ''dbType: dirty'' werden dafür entfernt.

Weiter unten in der Datei kann dann noch ein Admin-User aktiviert werden.

Etherpad sollte nun unter der URL: ''http://pad.example.com/'' erreichbar sein.

= Update =

Etherpad ist sehr pflegeleicht was das Update angeht. Es muss nur die neue Version in Git ausgecheckt werden und ./bin/run.sh erneut (einmalig) ausgeführt werden, damit die dependencies wieder neu gebaut werden. Auch von v1 -> v2 ist sonst nichts weiter zu tun.

= Links =

*[http://etherpad.org/ Etherpad Homepage (Englisch)]
*[https://github.com/ether/etherpad-lite/ Github Repository (Englisch)]
*[https://github.com/ether/etherpad-lite/wiki/Running-Etherpad-on-Phusion-Passenger Running Etherpad on Phusion Passenger (Englisch)]

----
[[Kategorie:HSDoku]]
[[Kategorie:Installationsanleitungen]]
[[Kategorie:Software]]
[[Kategorie:Passenger]]
[[Kategorie:NodeJS]]

ImapCopy

2026-02-27T19:26:07Z

Tim00: /* stunnel aufbauen */

== ImapCopy ==

ImapCopy ist ein Werkzeug, mit dem man ein komplettes IMAP-Postfach in ein IMAP-Postfach auf einem anderen Server (bei einem anderen Anbieter) kopieren kann. Wir verwenden es für die Migration von Postfächern. Eine Alternative ist [[OfflineIMAP]].

== Installation ImapCopy ==

ImapCopy ist auf den HS Hive schon installiert

== Einrichtung allgemein ==

Anmelden per ssh als ein Benutzer in einem HS-Paket.

<syntaxhighlight lang="bash">
xyz00-imapcopy@h01:~$
</syntaxhighlight>

Dort wird ein Arbeitsverzeichnis erstellt

<syntaxhighlight lang="bash">
xyz00-imapcopy@h01:~$ mkdir imapcopy
xyz00-imapcopy@h01:~$ cd imapcopy
</syntaxhighlight>

Die Konfiguration wird in einer Datei ImapCopy.cfg gespeichert

<syntaxhighlight lang="bash">
xyz00-imapcopy@h01:~/imapcopy$ vi ImapCopy.cfg
</syntaxhighlight>

=== Config Web.de -> HS Benutzer ===

Muster Inhalt der Datei ImapCopy.cfg

<syntaxhighlight lang="bash" line>
#############################################################
# imapcopy config
# all lines beginning with # are comments and will be ignored
#############################################################

##############
# Sourceserver
##############
SourceServer imap.web.de
SourcePort 143

###################
# Destinationserver
###################
DestServer xyz00.hostsharing.net
DestPort 143

#########
# Options
#########
#
# DebugSrc and DebugDest will show all traffic between IMAPCopy and Server
#
#DebugSrc
#DebugDst

#################
# Folders to skip
#################
#skipfolder INBOX.Trash
#skipfolder INBOX.Sent
#skipfolder "INBOX.Sent Objects"

#################
# Folders to copy
#################
#copyfolder INBOX
#copyfolder "INBOX.My personal files"
#copyfolder INBOX.Net-Connection.dy
#copyfolder INBOX.test

#######################################################
# Rootfolder
# Can be specified to copy the Folder-Structure under
# a separate folder instead of inbox
#######################################################
#DstRootFolder "Your old Mails"

###############################################################
# Specify Flags that are supported on the destination server
# (AllowFlags) or flags that should be filtered out (DenyFlags)
# If not specified, all Flags are copyied 1:1
# If AllowFlags is specified, all not specified Flags will be
# removed and not copied to the destination
# If DenyFlags is specified, those flags will be removed and
# the remaining ones will be copied
# Both (AllowFlags and DenyFlags) could be specified but
# would (in most cases) make no sense
##############################################################
#AllowFlags "\Seen\Answered\Flagged\Deleted\Draft Junk NonJunk $MDNSent $Forwared"
DenyFlags "\Recent"

##############################################################
# Timezone conversion
# The imap rfc is not clear on what kind of time offsets
# can be used. +XXXX -XXXX will be supported on all servers
# You can add as many entries as needed in the form
# converttimezone SRC DST
# to convert zones that your target server rejects
##############################################################
converttimezone "UTC" "+0000"
converttimezone "UT" "+0000"

#############################
# List of users and passwords
#############################
# SourceUser SourcePassword DestinationUser DestinationPassword
Copy "xyz@web.de" "Euer-Passwort" "xyz00-imap" "Benutzer-Passwort"
</syntaxhighlight>

=== Config gmail.com -> HS Benutzer ===

Da ImapCopy nicht direkt SSL unterstützt benötigt z.b. gmail und ggf einige andere die weiter unten beschrieben Lösung mit einem stunnel.

== Testen einer Verbindung ==

Zum testen ob die Daten alle OK sind auf der shell einfach:

<syntaxhighlight lang="bash">
xyz00-imapcopy@h01:~/imapcopy$ imapcopy -t
</syntaxhighlight>

eingeben.

== Daten austauschen ==

Wir empfehlen: Benutze eine <code>screen</code> Sitzung, damit die Übertragung nicht durch einen Verbindungsabbruch durcheinander kommt!

<syntaxhighlight lang="bash">
xyz00-imapcopy@h01:~/imapcopy$ screen
xyz00-imapcopy@h01:~/imapcopy$ imapcopy
</syntaxhighlight>

== Hilfe ==

<syntaxhighlight lang="bash">
xyz00-imapcopy@h01:~/imapcopy$ imapcopy -h
xyz00-imapcopy@h01:~/imapcopy$ man imapcopy
</syntaxhighlight>

== ssl via stunnel ==

Es wird eine Konfuguration Datei , hier stunnel-to-gmail.conf, benötigt.

<syntaxhighlight lang="bash">
xyz00-imapcopy@h01:~/imapcopy$ vi stunnel-to-gmail.conf
</syntaxhighlight>

Inhalt der Datei stunnel-to-gmail.conf:

<syntaxhighlight lang="ini" line>
foreground=yes

; Some performance tunings
socket = l:TCP_NODELAY=1
socket = r:TCP_NODELAY=1

; Some debugging stuff useful for troubleshooting
debug = 7

; Pfad for pid file
pid = /tmp/stunnel4-xyz00.pid

; Use it for client mode
client = yes

; Service-level configuration

[imap]
accept = 127.0.0.1:10143
connect = imap.gmail.com:993
retry = yes

[imap]
accept = 127.0.0.1:20143
connect = xyz00.hostsharing.net:993
retry = yes
</syntaxhighlight>

=== Änderung in der ImapCopy.cfg ===

<syntaxhighlight lang="ini" line>
##############
# Sourceserver
##############
SourceServer 127.0.0.1
SourcePort 10143

###################
# Destinationserver
###################
DestServer 127.0.0.1
DestPort 20143

#############################
# List of users and passwords
#############################
# SourceUser SourcePassword DestinationUser DestinationPassword
Copy "xyz@gmail.com" "passwort" "xyz00-imap" "passwort"
</syntaxhighlight>

=== stunnel aufbauen ===

Wir öffnen eine zweite Shell, starten dort screen, um kein Problem bei Verbindungsabbrüchen zu haben, und starten dann den stunnel:

<syntaxhighlight lang="bash" line>
xyz00-imapcopy@h01:~/imapcopy$ screen
xyz00-imapcopy@h01:~/imapcopy$ stunnel4 stunnel-to-gmail.conf
</syntaxhighlight>

=== Verbindung prüfen und herstellen ===

Siehe -> Testen einer Verbindung
und -> Daten austauschen

[[Kategorie:HSDoku]]
[[Kategorie:Installationsanleitungen]]
[[Kategorie:Glossar]]
[[Kategorie:Software]]
[[Kategorie:E-Mail]]

Flarum installieren

2026-02-16T07:15:12Z

Tim00: Hinweis auf PHP 7.4 entfernt

== Allgemein ==
=== Beschreibung ===
[https://flarum.org// Flarum] ist ein freies Forensystem, das sich als Foren-Software der nächsten Generation bezeichnet und Online-Diskussionen zu einem Vergnügen machen will. Es wirbt damit, einfach, schnell und frei zu sein.

Flarum läuft mit PHP und MySQL und lässt sich auf Linux betreiben. Die Installation mit Composer stellt für Benutzer von anderen shared Hosting Umgebungen ein Hindernis dar, bei Hostsharing dagegen ist Composer kein Problem und ermöglicht eine sehr einfache Installation.

Flarum ist der kombinierte Nachfolger von esoTalk und FluxBB.

Flarum steht unter der MIT Lizenz.

Seit Mai 2021 gibt es nun die stabile Version 1.0.

Die Entwicklung von Flarum geschieht in der Freizeit der Hauptentwickler, daher scheint es oft, das Projekt tritt auf der Stelle. Dennoch gibt es immer wieder Fortschritte, die man auf https://discuss.flarum.org/t/blog verfolgen kann.

== Installation ==

=== Design ===

Diese Installationsanleitung beschreibt, wie Flarum in einer eigens dafür [[Domainverwaltung#Lokale_Subdomains_durch_Aufschalten.3B_Delegieren|aufgeschalteten Subdomain]] über SSL betrieben wird. Für andere Konfigurationen, wie z.B. die Installation von Flarum in einer als Unterverzeichnis von <tt>~/doms/''domain''/subs/</tt> erstellten Subdomain, muß dieses Verfahren leicht angepaßt werden.

Der Vorteil einer Installation in einer aufgeschalteten Subdomain ist, daß die Installation leicht von anderen Domaininhalten, PHP-Konfigurationen, oder sogar von anderen Domain-Administratoren, isoliert werden kann.

=== Subdomain aufschalten ===

Im Folgenden werden folgende Domainkonfigurationsdaten als Beispiel verwendet:

{| class="wikitable"
|- class="hintergrundfarbe5"
! Typ !! Wert !! Beschreibung
|-
| Subdomain || <tt>discuss.example.org</tt> || Die Subdomain, unter der eine Flarum-Instanz laufen soll
|-
| Domain-Admin || <tt>xyz00-hans</tt> || Der User, dem die Subdomain delegiert wurde
|}

=== Quellen ===

Die Quellen befinden sich unter:
* https://github.com/flarum/core

Allerdings empfiehlt sich die Installation über Composer.

==== Installation mit Composer ====

Es sollte eine neuere Version von Composer (momentan 2.4.2) installiert werden, weil die Default Installation schon sehr alt ist (1.8.4). Siehe auch https://getcomposer.org/download/ für den aktuell gültigen sha hash...

<syntaxhighlight lang=shell line>
mkdir ~/composer
cd ~/composer
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php -r "if (hash_file('sha384', 'composer-setup.php') === '55ce33d7678c5a611085589f1f3ddf8b3c52d662cd01d4ba75c0ee0459970c2200a51f492d557530c71c15d8dba01eae') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"
php composer-setup.php
php -r "unlink('composer-setup.php');"
</syntaxhighlight>

Nun zur eigentlichen Installation:

<syntaxhighlight lang=shell line>
cd ~
mkdir flarum
cd flarum
php ~/composer/composer.phar create-project flarum/flarum .
# deutsches Sprachpaket installieren:
php ~/composer/composer.phar require flarum-lang/german
# um Platz zu sparen:
rm -Rf ~/.cache/composer
cd ~/doms/discuss.example.org
rm -Rf htdocs-ssl
ln -s ~/flarum/public htdocs-ssl
</syntaxhighlight>

=== MySQL vorbereiten ===

Flarum benötigt eine MySQL-Datenbank sowie einen Datenbanknutzer.

Die Tabellen werden später vom Installations-Werkzeug von Flarum eigenständig angelegt.

==== Datenbank und Datenbanknutzer anlegen ====

In dieser Anleitung werden folgende Namen für die Datenbank und deren Nutzer verwendet. Das Paket-Kürzel <tt>xyz00</tt> ist natürlich durch das des betreffenden Pakets zu ersetzen.

{| class="wikitable"
|- class="hintergrundfarbe5"
! Typ !! Wert !! Beschreibung
|-
| DB-Nutzer || <tt>xyz00_flarum</tt> || Der MySQL-Nutzer, dem die Datenbank gehört und der administrative Tätigkeiten durchführt und dann auch im Betrieb genutzt wird.
|-
|-
| Datenbank || <tt>xyz00_flarum</tt> || Die MySQL-Datenbank, die die Daten von Flarum enthält.
|}

Der Nutzer und die Datenbank können über die Weboberfläche auf [https://admin.hostsharing.net/ https://admin.hostsharing.net] oder über die Kommandozeile mit [[Hsadmin]] angelegt werden. Siehe dazu die Anleitungen auf der Seite [[MySQL]] und [[Datenbanken]]. Diese Schritte müssen ggf. vom Paket-Admin vorgenommen werden.

Einrichtung über die Kommandozeile:

Als Besitzer der Flarum-Datenbank <tt>xyz00_flarum</tt> angeben; als Zeichenkodierung ist das Default <tt>UTF-8</tt> richtig.

<syntaxhighlight lang=shell line>
su xyz00
hsscript -u xyz00 -e "mysqluser.add ({set:{name:'xyz00_flarum',password:'geheim'}})"
hsscript -u xyz00 -e "mysqldb.add ({set:{name:'xyz00_flarum',owner:'xyz00_flarum',encoding:'utf-8'}})"
exit
</syntaxhighlight>

=== Installation durchführen ===

Die URL zur Installation von Flarum lautet schlicht und einfach '''<tt><nowiki>https://discuss.example.org</nowiki></tt>'''.

Man gibt bei ''Forum Title'' den gewünschten Namen des Forums ein. Er kann auch später in den Einstellungen noch geändert werden, im laufenden Betrieb.

Die Datenbank muss wie folgt konfiguriert werden:
* ''MySQL Host'': <code>localhost</code>
* ''MySQL Database'': <code>xyz00_flarum</code>
* ''MySQL Username'': <code>xyz00_flarum</code>
* ''MySQL Password'': <code>geheim</code>
* ''Table Prefix'': kann leer gelassen werden

''Admin Username'' ist der Benutzername des Benutzers, der Administrationsrechte haben soll. Entsprechend ist ''Admin Email'' die E-Mail Adresse dieses Benutzers, und ''Admin Password'' sein Passwort, dass in ''Confirm Password'' wiederholt werden muss.

Nun klickt man auf den Schalter mit der Aufschrift ''Install Flarum'', und die Instanz wird konfiguriert.

Danach wird man in die Flarum Instanz weitergeleitet, und ist direkt als der erstellte Benutzer angemeldet.

== Erste Schritte ==

Man ändert die Sprache in der Titelleiste von Englisch auf Deutsch.

Man sollte dann in die Einstellungen gehen, die man im Menü oben rechts unter dem Benutzer Avatar findet.

Dort kann man die voreingestellte Sprache für das Forum einstellen, und ob man den Wechsel der Sprache erlaubt.

Außerdem lässt sich unter "E-Mail" ein SMTP Zugang für ein E-Mail Konto einrichten, über welches neue Konten eingerichtet werden können und vergessene Passwörter ersetzt werden können.

Es können auch Kategorien definiert werden, damit lassen sich die Diskussionen besser sortieren.

Man kann auch die Zugriffsrechte konfigurieren. Dafür können verschiedene Gruppen eingerichtet werden.

Im Endeffekt kann man auch über die Zugriffsrechte auch ein geschütztes Forum einrichten, wenn man die Registrierung schließt, und das Lesen von Diskussionen nur Mitgliedern erlaubt. Das einzige Problem ist, dass neue Mitglieder in diesem Fall sich nicht selber registrieren können, und notfalls über eine Erweiterung oder per Hand über die Datenbank angelegt werden müssen.

== Aktualisierung einer bestehenden Installation ==

Neue Versionen von Flarum werden auf dem Blog angekündigt: https://discuss.flarum.org/t/blog?sort=newest

In den Versionsankündigungen ist auch immer ein Abschnitt enthalten, der auf Besonderheiten beim Update hinweist. Diese Hinweise sollten befolgt werden!

Siehe auch https://docs.flarum.org/update/

Es sollte immer ein aktuelles Backup angefertigt werden.

Meistens sind diese Anweisungen ausreichend:

<syntaxhighlight lang=shell line>
cd ~/flarum
php flarum info
php ~/composer/composer.phar update --prefer-dist --no-dev -a --with-all-dependencies
php flarum migrate
php flarum cache:clear
php flarum info
rm -Rf ~/.cache/composer
</syntaxhighlight>

----
[[Kategorie:HSDoku]]
[[Kategorie:Installationsanleitungen]]
[[Kategorie:Webforen]]

Matrix Synapse installieren

2026-02-12T14:15:03Z

Tim00: /* Installation von Synapse */

Der Matrix Server ''Synapse'', der sogenannte 'Homeserver', ist aktuell die einzige vollständige serverseitige Implementierung des Matrix-Protokolls.

{{Textkasten|gelb|Work in Progress|Leider funktioniert die Server-zu-Server-Kommunikation von Synapse hinter dem Apache-Proxy mit den genannten Rewrite-Rules nicht. Bitten Sie dazu den Service, Ihren Apache VHost individuell für den Matrix Server anzupassen.}}

Die hier beschriebene Installation benötigt bei Hostsharing die Paket-Option "RAM". Benötigt werden min. 512 MB. Im Managed Webspace ist diese Option kostenpflichtig: https://www.hostsharing.net/angebote/managed-webspace/ gebucht werden muss der RAM auch bei einem Managed-Server.
Wir empfehlen für den Betrieb einen ''Managed Server''.

Diese Anleitung beschreibt, wie man den Matrix-Homeserver Synapse auf der Managed Hosting Plattform von Hostsharing installieren kann. Dabei sind die User-IDs nach dem Schema @user:beispiel.de aufgebaut, der Homeserver an sich ist unter matrix.beispiel.de erreichbar.

== Vorbereitungen ==

Mit Hilfe von HSAdmin werden angelegt:
# Ein User als Service-User mit ''/bin/bash'' als Shell, zum Beispiel Beispiel: ''xyz00-matrix''
# Eine Domain mit ''xyz00-matrix'' als Domain-Administrator, zum Beispiel ''matrix.beispiel.de''
# Einen Postgresql-User ''xyz00_matrixuser'' mit Passwort ''meinPasswort''
# Eine Postgresql-Datenbank ''xyz00_matrixdb'' mit Datenbank-Owner ''xyz00_matrixuser''

Verwendeter IP-Port für den Server-Dienst:
# Synapse: localhost:32801

== Installation von Synapse ==

Installationsanleitung basierend auf https://matrix-org.github.io/synapse/latest/setup/installation.html#installing-as-a-python-module-from-pypi

Als User ''xyz00-matrix" ein Python3 virtualenv erstellen:

<syntaxhighlight lang="shell">
mkdir -p ~/synapse
cd ~/synapse
python -m venv .venv
</syntaxhighlight>

Synapse und Postgres-Dependencies installieren:

<syntaxhighlight lang="shell">
source ~/synapse/.venv/bin/activate
release=`curl -L https://api.github.com/repos/element-hq/synapse/releases/latest -s | jq -r '.tag_name'`
rm -Rf ~/synapse.src
git clone --depth 1 https://github.com/element-hq/synapse.git -b ${release} ~/synapse.src
cd ~/synapse.src

# mit Poetry:
pip install poetry
poetry install --extras=postgres --extras=oidc

# oder mit Pipenv
pip install pipenv
pipenv install matrix-synapse[postgres,oidc] lxml authlib
</syntaxhighlight>

Initiale Konfiguration mit richtigem server-name "beispiel.de" generieren, außerdem im laufenden Betrieb keine Statistiken an Matrix.org senden:

<syntaxhighlight lang="shell">
cd ~/synapse
pipenv run python -m synapse.app.homeserver --server-name beispiel.de --config-path homeserver.yaml --generate-config --report-stats=no
</syntaxhighlight>

== Konfiguration von Synapse ==

In die initial generierte Konfiguration muss noch die Port- und Datenbank-Konfiguration eingetragen werden:

Port: Innerhalb der listener-section den Port 8008 auf 32801 (wie initial definiert) ändern, alles andere beibehalten:

<syntaxhighlight lang=yaml line>
- port: 32801
tls: false
bind_addresses: ['::1', '127.0.0.1']
type: http
x_forwarded: true
</syntaxhighlight>

Postgres-Datenbank:
<syntaxhighlight lang=yaml line>
database:
# The database engine name
name: "psycopg2"
# Arguments to pass to the engine
args:
host: "localhost"
database: "xyz00_matrixdb"
user: "xyz00_matrixuser"
password: "meinPasswort"
cp_min: 5
cp_max: 10
</syntaxhighlight>

== Starten der Dienste ==

Der ''Synapse''-Dienst wird hier als Service-Unit im SystemD des Users eingetragen.

Lege dazu die folgende Datei an: ''~/.config/systemd/user/synapse.service'' mit dem Inhalt:
<syntaxhighlight lang="ini" line>
[Unit]
Description=Synapse

[Service]
Type=simple
WorkingDirectory=%h/synapse
Environment=LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libjemalloc.so.2
ExecStart=pipenv run python -m synapse.app.homeserver --config-path=%h/synapse/homeserver.yaml

[Install]
WantedBy=default.target
</syntaxhighlight>

Durch Aufruf der folgenden Kommandos wird der Dienst aktiviert und gestartet:
<syntaxhighlight lang="shell" lines>
systemctl --user daemon-reload
systemctl --user enable synapse.service
systemctl --user start synapse.service
</syntaxhighlight>
== Einrichten des Apache VHost ==

Die ''~/doms/matrix.beispiel.de/.htaccess'' mit dem Editor der Wahl öffnen und
folgende Konfiguration einfügen:
<syntaxhighlight lang=apache line>
DirectoryIndex disabled
RewriteEngine On
RewriteBase /
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-l
RewriteRule .* http://localhost:32801%{REQUEST_URI} [NE,proxy]
RequestHeader set X-Forwarded-Proto "https"
</syntaxhighlight>
== Well-Known unter beispiel.de ==

Damit die User-Accounts das Format @user:beispiel.de haben, der Server aber unter matrix.beispiel.de erreichbar ist, müssen noch folgende zwei Dateien unter der Domain beispiel.de abgelegt werden:

https://beispiel.de/.well-known/matrix/server
<syntaxhighlight lang=json line>
{
"m.server": "matrix.beispiel.de:443"
}
</syntaxhighlight>

https://beispiel.de/.well-known/matrix/client
<syntaxhighlight lang=json line>
{
"m.homeserver": {
"base_url": "https://matrix.beispiel.de"
},
"m.identity_server": {
"base_url": "https://vector.im"
}
}
</syntaxhighlight>

Für die muss noch der CORS-Header Access-Control-Allow-Origin "*" gesetzt werden, damit die Datei aus beliebigem Riot-Web im Browser abrufbar ist. Dazu in den Ordner .well-known/matrix/ folgende .htaccess anlegen:
<syntaxhighlight lang=apache line>
<IfModule mod_headers.c>
Header set Access-Control-Allow-Origin "*"
</IfModule>
</syntaxhighlight>

Die Dokumentation dazu findet man unter https://matrix.org/docs/spec/server_server/r0.1.2#get-well-known-matrix-server und https://matrix.org/docs/spec/client_server/r0.5.0#get-well-known-matrix-client

== Update von Synapse ==

Normalerweise sollte es so gehen, mit pipenv:

<syntaxhighlight lang=shell>
cd ~/synapse
pipenv update --outdated || echo "there are packages to update"
pipenv update
systemctl --user restart synapse
</syntaxhighlight>

In seltenen Fällen gibt es Probleme bei den Abhängigkeiten, die schon wieder aktualisiert wurden, und nicht mehr kompatibel zum aktuellen Synapse sind.
Dann ist es zu empfehlen, Synapse mit der offiziellen poetry.lock Datei zu aktualisieren, um die Konflikte zu vermeiden.

mit poetry:
<syntaxhighlight lang=shell>
systemctl --user stop synapse.service
source ~/.venv/bin/activate
release=`curl -L https://api.github.com/repos/element-hq/synapse/releases/latest -s | jq -r '.tag_name'`
rm -Rf ~/synapse.src
git clone --depth 1 https://github.com/element-hq/synapse.git -b ${release} ~/synapse.src
cd ~/synapse.src
pip install poetry
poetry install --extras=postgres --extras=oidc
systemctl --user start synapse.service
</syntaxhighlight>

Wenn die Föderation für den Synapse Server aktiviert ist, kann mit dem [https://federationtester.matrix.org/ Matrix Federation Tester] die eigene Instanz auf die laufende Version geprüft werden. Als Server nicht matrix.example.org eingeben, sondern den öffentlichen Namen, wo auch die Benutzernamen drauf laufen, z.B. example.org

Ansonsten ist die laufende Version auch über die URL https://matrix.example.org/_synapse/admin/v1/server_version zu erfahren.

== Element-Web ==

Element-Web ist aus Server-Seite eine rein statische html+javascript-Kombination, daher:

* Account und Domain anlegen (separat von der Synapse-Domain)
* [https://github.com/element-hq/element-web/releases/latest aktuelles element-web release] .tgz herunterladen
* Symlink von htdocs-ssl auf entpacktes element-web-Verzeichnis
* config.sample.json in config.json kopieren und Matrix-Homeserver-Einträge anpassen
* Piwik aus config.json entfernen

== SAML mit Synapse ==

Synapse unterstützt mit Version 1.1.0 SAML. Dazu wie folgt vorgehen:

Das Paket xmlsec1 muss installiert sein:

<syntaxhighlight lang=shell>
$ xmlsec1 --version
xmlsec1 1.2.23 (openssl)
</syntaxhighlight>

Das Python-Paket pysaml2 installieren

<syntaxhighlight lang=shell>
cd ~/synapse
pipenv shell
pipenv install pysaml2
</syntaxhighlight>

In der homeserver.yaml die SAML-Direktiven einkommentieren, hier mit dem Beispiel eines SAML IdP unter https://login.beispiel.de/simplesaml/saml2/idp/metadata.php:

<syntaxhighlight lang=yaml line>
# Once SAML support is enabled, a metadata file will be exposed at
# https://<server>:<port>/_matrix/saml2/metadata.xml, which you may be able to
# use to configure your SAML IdP with. Alternatively, you can manually configure
# the IdP to use an ACS location of
# https://<server>:<port>/_matrix/saml2/authn_response.
#
saml2_config:
sp_config:
# point this to the IdP's metadata. You can use either a local file or
# (preferably) a URL.
metadata:
#local: ["saml2/idp.xml"]
remote:
- url: https://login.beispiel.de/simplesaml/saml2/idp/metadata.php
</syntaxhighlight>
Wichtig ist außerdem, dass die public_baseurl in der homeserver.yaml gesetzt ist, damit Synapse weiß, wie es erreichbar ist und dies in seine SP-Metadaten einbauen kann:
<syntaxhighlight lang=yaml line>
public_baseurl: https://matrix.beispiel.de/
</syntaxhighlight>
Die Service-Provider-Konfiguration als XML bekommt man von Synapse dann wie schon in der homeserver.yaml als Kommentar beschrieben, unter https://matrix.beispiel.de/_matrix/saml2/metadata.xml

Diese dann in den SAML-IdP-importieren und dann sollte der Single-Sign-On via SAML funktionieren.

== Federation Sender Worker für Synapse ==

Zur Parallelisierung bietet Synapse das Konzept "Worker" an, die spezifische Aufgaben übernehmen, damit der Hauptprozess diese nicht durchführen muss.

Details dazu: https://github.com/matrix-org/synapse/blob/master/docs/workers.md

Ein einfach einzurichtender Worker, der auch viel Last abfedert, ist der Federation Sender Worker, da das Verschicken des Federation-Traffics 10-50% der Serverlast ausmacht.

In der homeserver.yaml die Worker-Konfiguration aktivieren:
<syntaxhighlight lang=yaml line>
## Worker ##
worker_app: synapse.app.homeserver
daemonize: true
</syntaxhighlight>

und dazugehörige Listener (Abschnitt listener:) aktivieren:
<syntaxhighlight lang=yaml line>
# The TCP replication port
- port: 32892
bind_address: '127.0.0.1'
type: replication
# The HTTP replication port
- port: 32893
bind_address: '127.0.0.1'
type: http
resources:
- names: [replication]
</syntaxhighlight>

Funktionen, die Worker machen sollen, in der homeserver.yaml deaktivieren:
<syntaxhighlight lang=yaml line>
# disable federation sending here, use worker for it
send_federation: False
</syntaxhighlight>
Dann Verzeichnis synapse/workers anlegen, darin federation_sender.yaml:
<syntaxhighlight lang=yaml line>
worker_app: synapse.app.federation_sender

# The replication listener on the synapse to talk to.
worker_replication_host: 127.0.0.1
worker_replication_port: 32892
worker_replication_http_port: 32893

worker_daemonize: True
worker_pid_file: /home/pacs/xyz00/users/matrix/synapse/federation_sender.pid
worker_log_config: /home/pacs/xyz00/users/matrix/synapse/federation_sender.log.config
</syntaxhighlight>
.monitrc um worker erweitern:
<syntaxhighlight lang=shell line>
check process federation_sender with pidfile /home/pacs/xyz00/users/matrix/synapse/federation_sender.pid
start program "/bin/bash -c 'export VIRTUAL_ENV=$HOME/synapse/env && export PATH=$VIRTUAL_ENV/bin:$PATH && cd $HOME/synapse && synctl -w workers/federation_sender.yaml start'"
stop program "/bin/bash -c '/bin/kill $( cat $HOME/synapse/federation_sender.pid )'"
</syntaxhighlight>
Monit neu laden und synapse und federation_sender neustarten:

<syntaxhighlight lang=shell>
monit reload
monit restart all
</syntaxhighlight>

Nach Updates ebenfalls immer Hauptprozess und alle Worker neustarten

<syntaxhighlight lang=shell>
monit restart all
</syntaxhighlight>

== Sliding Sync Proxy ==
Zum Zeitpunkt dieser Anleitung werden aktiv neue Element Anwendungen (Element X) und ein neues Syncverfahren entwickelt um Matrix performanter und weniger ressourcenhungrig zu machen. Bei stärkerer Matrix Nutzung können die neuen Anwendungen besonders mobil schon eine große Entlastung sein.

Ende 2024 wurden grundlegende Funktionen direkt in Synapse implementiert. Der Proxy wird nicht länger weiterentwickelt und sollte deinstalliert werden (nicht vergessen die .well-known zurück zu ändern). Auch der 3rdparty Server [[Conduit]] bringt nativ Support für Sliding Sync.

== Links ==

* https://matrix.org/docs/projects/server/synapse
* https://github.com/element-hq/synapse
* https://github.com/element-hq/synapse/blob/master/INSTALL.md
* https://github.com/matrix-org/sliding-sync
* https://matrix.org/docs/spec/
* https://www.hostsharing.net/loesungen/matrix/
* https://codeberg.org/tpokorra/hs.ansible/src/branch/main/playbooks/synapse
* https://codeberg.org/tpokorra/hs.ansible/src/branch/main/playbooks/element

[[Kategorie:Messenger]]
[[Kategorie:Software]]
[[Kategorie:Eigene Daemons]]
[[Kategorie:Installationsanleitungen]]
[[Kategorie:Ansible Playbook]]

Matrix Synapse installieren

2026-02-12T05:49:29Z

Tim00: /* Installation von Synapse */

Der Matrix Server ''Synapse'', der sogenannte 'Homeserver', ist aktuell die einzige vollständige serverseitige Implementierung des Matrix-Protokolls.

{{Textkasten|gelb|Work in Progress|Leider funktioniert die Server-zu-Server-Kommunikation von Synapse hinter dem Apache-Proxy mit den genannten Rewrite-Rules nicht. Bitten Sie dazu den Service, Ihren Apache VHost individuell für den Matrix Server anzupassen.}}

Die hier beschriebene Installation benötigt bei Hostsharing die Paket-Option "RAM". Benötigt werden min. 512 MB. Im Managed Webspace ist diese Option kostenpflichtig: https://www.hostsharing.net/angebote/managed-webspace/ gebucht werden muss der RAM auch bei einem Managed-Server.
Wir empfehlen für den Betrieb einen ''Managed Server''.

Diese Anleitung beschreibt, wie man den Matrix-Homeserver Synapse auf der Managed Hosting Plattform von Hostsharing installieren kann. Dabei sind die User-IDs nach dem Schema @user:beispiel.de aufgebaut, der Homeserver an sich ist unter matrix.beispiel.de erreichbar.

== Vorbereitungen ==

Mit Hilfe von HSAdmin werden angelegt:
# Ein User als Service-User mit ''/bin/bash'' als Shell, zum Beispiel Beispiel: ''xyz00-matrix''
# Eine Domain mit ''xyz00-matrix'' als Domain-Administrator, zum Beispiel ''matrix.beispiel.de''
# Einen Postgresql-User ''xyz00_matrixuser'' mit Passwort ''meinPasswort''
# Eine Postgresql-Datenbank ''xyz00_matrixdb'' mit Datenbank-Owner ''xyz00_matrixuser''

Verwendeter IP-Port für den Server-Dienst:
# Synapse: localhost:32801

== Installation von Synapse ==

Installationsanleitung basierend auf https://matrix-org.github.io/synapse/latest/setup/installation.html#installing-as-a-python-module-from-pypi

Als User ''xyz00-matrix" ein Python3 virtualenv erstellen:

<syntaxhighlight lang="shell">
mkdir -p ~/synapse
cd ~/synapse
python -m venv .venv
</syntaxhighlight>

Synapse und Postgres-Dependencies installieren:

<syntaxhighlight lang="shell">
source ~/synapse/.venv/bin/activate
release=`curl -L https://api.github.com/repos/element-hq/synapse/releases/latest -s | jq -r '.tag_name'`
rm -Rf ~/synapse.src
git clone --depth 1 https://github.com/element-hq/synapse.git -b ${release} ~/synapse.src
cd ~/synapse.src

# mit Poetry:
pip install poetry
poetry install --extras=postgres --extras=oidc

# oder mit Pipenv
pip install pipenv
pipenv install matrix-synapse[postgres] matrix-synapse[oidc] lxml
</syntaxhighlight>

Initiale Konfiguration mit richtigem server-name "beispiel.de" generieren, außerdem im laufenden Betrieb keine Statistiken an Matrix.org senden:

<syntaxhighlight lang="shell">
cd ~/synapse
pipenv run python -m synapse.app.homeserver --server-name beispiel.de --config-path homeserver.yaml --generate-config --report-stats=no
</syntaxhighlight>

== Konfiguration von Synapse ==

In die initial generierte Konfiguration muss noch die Port- und Datenbank-Konfiguration eingetragen werden:

Port: Innerhalb der listener-section den Port 8008 auf 32801 (wie initial definiert) ändern, alles andere beibehalten:

<syntaxhighlight lang=yaml line>
- port: 32801
tls: false
bind_addresses: ['::1', '127.0.0.1']
type: http
x_forwarded: true
</syntaxhighlight>

Postgres-Datenbank:
<syntaxhighlight lang=yaml line>
database:
# The database engine name
name: "psycopg2"
# Arguments to pass to the engine
args:
host: "localhost"
database: "xyz00_matrixdb"
user: "xyz00_matrixuser"
password: "meinPasswort"
cp_min: 5
cp_max: 10
</syntaxhighlight>

== Starten der Dienste ==

Der ''Synapse''-Dienst wird hier als Service-Unit im SystemD des Users eingetragen.

Lege dazu die folgende Datei an: ''~/.config/systemd/user/synapse.service'' mit dem Inhalt:
<syntaxhighlight lang="ini" line>
[Unit]
Description=Synapse

[Service]
Type=simple
WorkingDirectory=%h/synapse
Environment=LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libjemalloc.so.2
ExecStart=pipenv run python -m synapse.app.homeserver --config-path=%h/synapse/homeserver.yaml

[Install]
WantedBy=default.target
</syntaxhighlight>

Durch Aufruf der folgenden Kommandos wird der Dienst aktiviert und gestartet:
<syntaxhighlight lang="shell" lines>
systemctl --user daemon-reload
systemctl --user enable synapse.service
systemctl --user start synapse.service
</syntaxhighlight>
== Einrichten des Apache VHost ==

Die ''~/doms/matrix.beispiel.de/.htaccess'' mit dem Editor der Wahl öffnen und
folgende Konfiguration einfügen:
<syntaxhighlight lang=apache line>
DirectoryIndex disabled
RewriteEngine On
RewriteBase /
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-l
RewriteRule .* http://localhost:32801%{REQUEST_URI} [NE,proxy]
RequestHeader set X-Forwarded-Proto "https"
</syntaxhighlight>
== Well-Known unter beispiel.de ==

Damit die User-Accounts das Format @user:beispiel.de haben, der Server aber unter matrix.beispiel.de erreichbar ist, müssen noch folgende zwei Dateien unter der Domain beispiel.de abgelegt werden:

https://beispiel.de/.well-known/matrix/server
<syntaxhighlight lang=json line>
{
"m.server": "matrix.beispiel.de:443"
}
</syntaxhighlight>

https://beispiel.de/.well-known/matrix/client
<syntaxhighlight lang=json line>
{
"m.homeserver": {
"base_url": "https://matrix.beispiel.de"
},
"m.identity_server": {
"base_url": "https://vector.im"
}
}
</syntaxhighlight>

Für die muss noch der CORS-Header Access-Control-Allow-Origin "*" gesetzt werden, damit die Datei aus beliebigem Riot-Web im Browser abrufbar ist. Dazu in den Ordner .well-known/matrix/ folgende .htaccess anlegen:
<syntaxhighlight lang=apache line>
<IfModule mod_headers.c>
Header set Access-Control-Allow-Origin "*"
</IfModule>
</syntaxhighlight>

Die Dokumentation dazu findet man unter https://matrix.org/docs/spec/server_server/r0.1.2#get-well-known-matrix-server und https://matrix.org/docs/spec/client_server/r0.5.0#get-well-known-matrix-client

== Update von Synapse ==

Normalerweise sollte es so gehen, mit pipenv:

<syntaxhighlight lang=shell>
cd ~/synapse
pipenv update --outdated || echo "there are packages to update"
pipenv update
systemctl --user restart synapse
</syntaxhighlight>

In seltenen Fällen gibt es Probleme bei den Abhängigkeiten, die schon wieder aktualisiert wurden, und nicht mehr kompatibel zum aktuellen Synapse sind.
Dann ist es zu empfehlen, Synapse mit der offiziellen poetry.lock Datei zu aktualisieren, um die Konflikte zu vermeiden.

mit poetry:
<syntaxhighlight lang=shell>
systemctl --user stop synapse.service
source ~/.venv/bin/activate
release=`curl -L https://api.github.com/repos/element-hq/synapse/releases/latest -s | jq -r '.tag_name'`
rm -Rf ~/synapse.src
git clone --depth 1 https://github.com/element-hq/synapse.git -b ${release} ~/synapse.src
cd ~/synapse.src
pip install poetry
poetry install --extras=postgres --extras=oidc
systemctl --user start synapse.service
</syntaxhighlight>

Wenn die Föderation für den Synapse Server aktiviert ist, kann mit dem [https://federationtester.matrix.org/ Matrix Federation Tester] die eigene Instanz auf die laufende Version geprüft werden. Als Server nicht matrix.example.org eingeben, sondern den öffentlichen Namen, wo auch die Benutzernamen drauf laufen, z.B. example.org

Ansonsten ist die laufende Version auch über die URL https://matrix.example.org/_synapse/admin/v1/server_version zu erfahren.

== Element-Web ==

Element-Web ist aus Server-Seite eine rein statische html+javascript-Kombination, daher:

* Account und Domain anlegen (separat von der Synapse-Domain)
* [https://github.com/element-hq/element-web/releases/latest aktuelles element-web release] .tgz herunterladen
* Symlink von htdocs-ssl auf entpacktes element-web-Verzeichnis
* config.sample.json in config.json kopieren und Matrix-Homeserver-Einträge anpassen
* Piwik aus config.json entfernen

== SAML mit Synapse ==

Synapse unterstützt mit Version 1.1.0 SAML. Dazu wie folgt vorgehen:

Das Paket xmlsec1 muss installiert sein:

<syntaxhighlight lang=shell>
$ xmlsec1 --version
xmlsec1 1.2.23 (openssl)
</syntaxhighlight>

Das Python-Paket pysaml2 installieren

<syntaxhighlight lang=shell>
cd ~/synapse
pipenv shell
pipenv install pysaml2
</syntaxhighlight>

In der homeserver.yaml die SAML-Direktiven einkommentieren, hier mit dem Beispiel eines SAML IdP unter https://login.beispiel.de/simplesaml/saml2/idp/metadata.php:

<syntaxhighlight lang=yaml line>
# Once SAML support is enabled, a metadata file will be exposed at
# https://<server>:<port>/_matrix/saml2/metadata.xml, which you may be able to
# use to configure your SAML IdP with. Alternatively, you can manually configure
# the IdP to use an ACS location of
# https://<server>:<port>/_matrix/saml2/authn_response.
#
saml2_config:
sp_config:
# point this to the IdP's metadata. You can use either a local file or
# (preferably) a URL.
metadata:
#local: ["saml2/idp.xml"]
remote:
- url: https://login.beispiel.de/simplesaml/saml2/idp/metadata.php
</syntaxhighlight>
Wichtig ist außerdem, dass die public_baseurl in der homeserver.yaml gesetzt ist, damit Synapse weiß, wie es erreichbar ist und dies in seine SP-Metadaten einbauen kann:
<syntaxhighlight lang=yaml line>
public_baseurl: https://matrix.beispiel.de/
</syntaxhighlight>
Die Service-Provider-Konfiguration als XML bekommt man von Synapse dann wie schon in der homeserver.yaml als Kommentar beschrieben, unter https://matrix.beispiel.de/_matrix/saml2/metadata.xml

Diese dann in den SAML-IdP-importieren und dann sollte der Single-Sign-On via SAML funktionieren.

== Federation Sender Worker für Synapse ==

Zur Parallelisierung bietet Synapse das Konzept "Worker" an, die spezifische Aufgaben übernehmen, damit der Hauptprozess diese nicht durchführen muss.

Details dazu: https://github.com/matrix-org/synapse/blob/master/docs/workers.md

Ein einfach einzurichtender Worker, der auch viel Last abfedert, ist der Federation Sender Worker, da das Verschicken des Federation-Traffics 10-50% der Serverlast ausmacht.

In der homeserver.yaml die Worker-Konfiguration aktivieren:
<syntaxhighlight lang=yaml line>
## Worker ##
worker_app: synapse.app.homeserver
daemonize: true
</syntaxhighlight>

und dazugehörige Listener (Abschnitt listener:) aktivieren:
<syntaxhighlight lang=yaml line>
# The TCP replication port
- port: 32892
bind_address: '127.0.0.1'
type: replication
# The HTTP replication port
- port: 32893
bind_address: '127.0.0.1'
type: http
resources:
- names: [replication]
</syntaxhighlight>

Funktionen, die Worker machen sollen, in der homeserver.yaml deaktivieren:
<syntaxhighlight lang=yaml line>
# disable federation sending here, use worker for it
send_federation: False
</syntaxhighlight>
Dann Verzeichnis synapse/workers anlegen, darin federation_sender.yaml:
<syntaxhighlight lang=yaml line>
worker_app: synapse.app.federation_sender

# The replication listener on the synapse to talk to.
worker_replication_host: 127.0.0.1
worker_replication_port: 32892
worker_replication_http_port: 32893

worker_daemonize: True
worker_pid_file: /home/pacs/xyz00/users/matrix/synapse/federation_sender.pid
worker_log_config: /home/pacs/xyz00/users/matrix/synapse/federation_sender.log.config
</syntaxhighlight>
.monitrc um worker erweitern:
<syntaxhighlight lang=shell line>
check process federation_sender with pidfile /home/pacs/xyz00/users/matrix/synapse/federation_sender.pid
start program "/bin/bash -c 'export VIRTUAL_ENV=$HOME/synapse/env && export PATH=$VIRTUAL_ENV/bin:$PATH && cd $HOME/synapse && synctl -w workers/federation_sender.yaml start'"
stop program "/bin/bash -c '/bin/kill $( cat $HOME/synapse/federation_sender.pid )'"
</syntaxhighlight>
Monit neu laden und synapse und federation_sender neustarten:

<syntaxhighlight lang=shell>
monit reload
monit restart all
</syntaxhighlight>

Nach Updates ebenfalls immer Hauptprozess und alle Worker neustarten

<syntaxhighlight lang=shell>
monit restart all
</syntaxhighlight>

== Sliding Sync Proxy ==
Zum Zeitpunkt dieser Anleitung werden aktiv neue Element Anwendungen (Element X) und ein neues Syncverfahren entwickelt um Matrix performanter und weniger ressourcenhungrig zu machen. Bei stärkerer Matrix Nutzung können die neuen Anwendungen besonders mobil schon eine große Entlastung sein.

Ende 2024 wurden grundlegende Funktionen direkt in Synapse implementiert. Der Proxy wird nicht länger weiterentwickelt und sollte deinstalliert werden (nicht vergessen die .well-known zurück zu ändern). Auch der 3rdparty Server [[Conduit]] bringt nativ Support für Sliding Sync.

== Links ==

* https://matrix.org/docs/projects/server/synapse
* https://github.com/element-hq/synapse
* https://github.com/element-hq/synapse/blob/master/INSTALL.md
* https://github.com/matrix-org/sliding-sync
* https://matrix.org/docs/spec/
* https://www.hostsharing.net/loesungen/matrix/
* https://codeberg.org/tpokorra/hs.ansible/src/branch/main/playbooks/synapse
* https://codeberg.org/tpokorra/hs.ansible/src/branch/main/playbooks/element

[[Kategorie:Messenger]]
[[Kategorie:Software]]
[[Kategorie:Eigene Daemons]]
[[Kategorie:Installationsanleitungen]]
[[Kategorie:Ansible Playbook]]

Matrix Synapse installieren

2026-02-12T05:45:54Z

Tim00: /* Installation von Synapse */

Der Matrix Server ''Synapse'', der sogenannte 'Homeserver', ist aktuell die einzige vollständige serverseitige Implementierung des Matrix-Protokolls.

{{Textkasten|gelb|Work in Progress|Leider funktioniert die Server-zu-Server-Kommunikation von Synapse hinter dem Apache-Proxy mit den genannten Rewrite-Rules nicht. Bitten Sie dazu den Service, Ihren Apache VHost individuell für den Matrix Server anzupassen.}}

Die hier beschriebene Installation benötigt bei Hostsharing die Paket-Option "RAM". Benötigt werden min. 512 MB. Im Managed Webspace ist diese Option kostenpflichtig: https://www.hostsharing.net/angebote/managed-webspace/ gebucht werden muss der RAM auch bei einem Managed-Server.
Wir empfehlen für den Betrieb einen ''Managed Server''.

Diese Anleitung beschreibt, wie man den Matrix-Homeserver Synapse auf der Managed Hosting Plattform von Hostsharing installieren kann. Dabei sind die User-IDs nach dem Schema @user:beispiel.de aufgebaut, der Homeserver an sich ist unter matrix.beispiel.de erreichbar.

== Vorbereitungen ==

Mit Hilfe von HSAdmin werden angelegt:
# Ein User als Service-User mit ''/bin/bash'' als Shell, zum Beispiel Beispiel: ''xyz00-matrix''
# Eine Domain mit ''xyz00-matrix'' als Domain-Administrator, zum Beispiel ''matrix.beispiel.de''
# Einen Postgresql-User ''xyz00_matrixuser'' mit Passwort ''meinPasswort''
# Eine Postgresql-Datenbank ''xyz00_matrixdb'' mit Datenbank-Owner ''xyz00_matrixuser''

Verwendeter IP-Port für den Server-Dienst:
# Synapse: localhost:32801

== Installation von Synapse ==

Installationsanleitung basierend auf https://matrix-org.github.io/synapse/latest/setup/installation.html#installing-as-a-python-module-from-pypi

Als User ''xyz00-matrix" ein Python3 virtualenv erstellen:

<syntaxhighlight lang="shell">
mkdir -p ~/synapse
cd ~/synapse
python -m venv .venv
</syntaxhighlight>

Synapse und Postgres-Dependencies installieren:

<syntaxhighlight lang="shell">
source ~/synapse/.venv/bin/activate
release=`curl -L https://api.github.com/repos/element-hq/synapse/releases/latest -s | jq -r '.tag_name'`
rm -Rf ~/synapse.src
git clone --depth 1 https://github.com/element-hq/synapse.git -b ${release} ~/synapse.src
cd ~/synapse.src

# mit Poetry:
pip install poetry
poetry install --extras=postgres --extras=oidc

# oder mit Pipenv
pip install pipenv
pipenv install matrix-synapse[postgres] matrix-synapse[oidc]
</syntaxhighlight>

Initiale Konfiguration mit richtigem server-name "beispiel.de" generieren, außerdem im laufenden Betrieb keine Statistiken an Matrix.org senden:

<syntaxhighlight lang="shell">
cd ~/synapse
pipenv run python -m synapse.app.homeserver --server-name beispiel.de --config-path homeserver.yaml --generate-config --report-stats=no
</syntaxhighlight>

== Konfiguration von Synapse ==

In die initial generierte Konfiguration muss noch die Port- und Datenbank-Konfiguration eingetragen werden:

Port: Innerhalb der listener-section den Port 8008 auf 32801 (wie initial definiert) ändern, alles andere beibehalten:

<syntaxhighlight lang=yaml line>
- port: 32801
tls: false
bind_addresses: ['::1', '127.0.0.1']
type: http
x_forwarded: true
</syntaxhighlight>

Postgres-Datenbank:
<syntaxhighlight lang=yaml line>
database:
# The database engine name
name: "psycopg2"
# Arguments to pass to the engine
args:
host: "localhost"
database: "xyz00_matrixdb"
user: "xyz00_matrixuser"
password: "meinPasswort"
cp_min: 5
cp_max: 10
</syntaxhighlight>

== Starten der Dienste ==

Der ''Synapse''-Dienst wird hier als Service-Unit im SystemD des Users eingetragen.

Lege dazu die folgende Datei an: ''~/.config/systemd/user/synapse.service'' mit dem Inhalt:
<syntaxhighlight lang="ini" line>
[Unit]
Description=Synapse

[Service]
Type=simple
WorkingDirectory=%h/synapse
Environment=LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libjemalloc.so.2
ExecStart=pipenv run python -m synapse.app.homeserver --config-path=%h/synapse/homeserver.yaml

[Install]
WantedBy=default.target
</syntaxhighlight>

Durch Aufruf der folgenden Kommandos wird der Dienst aktiviert und gestartet:
<syntaxhighlight lang="shell" lines>
systemctl --user daemon-reload
systemctl --user enable synapse.service
systemctl --user start synapse.service
</syntaxhighlight>
== Einrichten des Apache VHost ==

Die ''~/doms/matrix.beispiel.de/.htaccess'' mit dem Editor der Wahl öffnen und
folgende Konfiguration einfügen:
<syntaxhighlight lang=apache line>
DirectoryIndex disabled
RewriteEngine On
RewriteBase /
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-l
RewriteRule .* http://localhost:32801%{REQUEST_URI} [NE,proxy]
RequestHeader set X-Forwarded-Proto "https"
</syntaxhighlight>
== Well-Known unter beispiel.de ==

Damit die User-Accounts das Format @user:beispiel.de haben, der Server aber unter matrix.beispiel.de erreichbar ist, müssen noch folgende zwei Dateien unter der Domain beispiel.de abgelegt werden:

https://beispiel.de/.well-known/matrix/server
<syntaxhighlight lang=json line>
{
"m.server": "matrix.beispiel.de:443"
}
</syntaxhighlight>

https://beispiel.de/.well-known/matrix/client
<syntaxhighlight lang=json line>
{
"m.homeserver": {
"base_url": "https://matrix.beispiel.de"
},
"m.identity_server": {
"base_url": "https://vector.im"
}
}
</syntaxhighlight>

Für die muss noch der CORS-Header Access-Control-Allow-Origin "*" gesetzt werden, damit die Datei aus beliebigem Riot-Web im Browser abrufbar ist. Dazu in den Ordner .well-known/matrix/ folgende .htaccess anlegen:
<syntaxhighlight lang=apache line>
<IfModule mod_headers.c>
Header set Access-Control-Allow-Origin "*"
</IfModule>
</syntaxhighlight>

Die Dokumentation dazu findet man unter https://matrix.org/docs/spec/server_server/r0.1.2#get-well-known-matrix-server und https://matrix.org/docs/spec/client_server/r0.5.0#get-well-known-matrix-client

== Update von Synapse ==

Normalerweise sollte es so gehen, mit pipenv:

<syntaxhighlight lang=shell>
cd ~/synapse
pipenv update --outdated || echo "there are packages to update"
pipenv update
systemctl --user restart synapse
</syntaxhighlight>

In seltenen Fällen gibt es Probleme bei den Abhängigkeiten, die schon wieder aktualisiert wurden, und nicht mehr kompatibel zum aktuellen Synapse sind.
Dann ist es zu empfehlen, Synapse mit der offiziellen poetry.lock Datei zu aktualisieren, um die Konflikte zu vermeiden.

mit poetry:
<syntaxhighlight lang=shell>
systemctl --user stop synapse.service
source ~/.venv/bin/activate
release=`curl -L https://api.github.com/repos/element-hq/synapse/releases/latest -s | jq -r '.tag_name'`
rm -Rf ~/synapse.src
git clone --depth 1 https://github.com/element-hq/synapse.git -b ${release} ~/synapse.src
cd ~/synapse.src
pip install poetry
poetry install --extras=postgres --extras=oidc
systemctl --user start synapse.service
</syntaxhighlight>

Wenn die Föderation für den Synapse Server aktiviert ist, kann mit dem [https://federationtester.matrix.org/ Matrix Federation Tester] die eigene Instanz auf die laufende Version geprüft werden. Als Server nicht matrix.example.org eingeben, sondern den öffentlichen Namen, wo auch die Benutzernamen drauf laufen, z.B. example.org

Ansonsten ist die laufende Version auch über die URL https://matrix.example.org/_synapse/admin/v1/server_version zu erfahren.

== Element-Web ==

Element-Web ist aus Server-Seite eine rein statische html+javascript-Kombination, daher:

* Account und Domain anlegen (separat von der Synapse-Domain)
* [https://github.com/element-hq/element-web/releases/latest aktuelles element-web release] .tgz herunterladen
* Symlink von htdocs-ssl auf entpacktes element-web-Verzeichnis
* config.sample.json in config.json kopieren und Matrix-Homeserver-Einträge anpassen
* Piwik aus config.json entfernen

== SAML mit Synapse ==

Synapse unterstützt mit Version 1.1.0 SAML. Dazu wie folgt vorgehen:

Das Paket xmlsec1 muss installiert sein:

<syntaxhighlight lang=shell>
$ xmlsec1 --version
xmlsec1 1.2.23 (openssl)
</syntaxhighlight>

Das Python-Paket pysaml2 installieren

<syntaxhighlight lang=shell>
cd ~/synapse
pipenv shell
pipenv install pysaml2
</syntaxhighlight>

In der homeserver.yaml die SAML-Direktiven einkommentieren, hier mit dem Beispiel eines SAML IdP unter https://login.beispiel.de/simplesaml/saml2/idp/metadata.php:

<syntaxhighlight lang=yaml line>
# Once SAML support is enabled, a metadata file will be exposed at
# https://<server>:<port>/_matrix/saml2/metadata.xml, which you may be able to
# use to configure your SAML IdP with. Alternatively, you can manually configure
# the IdP to use an ACS location of
# https://<server>:<port>/_matrix/saml2/authn_response.
#
saml2_config:
sp_config:
# point this to the IdP's metadata. You can use either a local file or
# (preferably) a URL.
metadata:
#local: ["saml2/idp.xml"]
remote:
- url: https://login.beispiel.de/simplesaml/saml2/idp/metadata.php
</syntaxhighlight>
Wichtig ist außerdem, dass die public_baseurl in der homeserver.yaml gesetzt ist, damit Synapse weiß, wie es erreichbar ist und dies in seine SP-Metadaten einbauen kann:
<syntaxhighlight lang=yaml line>
public_baseurl: https://matrix.beispiel.de/
</syntaxhighlight>
Die Service-Provider-Konfiguration als XML bekommt man von Synapse dann wie schon in der homeserver.yaml als Kommentar beschrieben, unter https://matrix.beispiel.de/_matrix/saml2/metadata.xml

Diese dann in den SAML-IdP-importieren und dann sollte der Single-Sign-On via SAML funktionieren.

== Federation Sender Worker für Synapse ==

Zur Parallelisierung bietet Synapse das Konzept "Worker" an, die spezifische Aufgaben übernehmen, damit der Hauptprozess diese nicht durchführen muss.

Details dazu: https://github.com/matrix-org/synapse/blob/master/docs/workers.md

Ein einfach einzurichtender Worker, der auch viel Last abfedert, ist der Federation Sender Worker, da das Verschicken des Federation-Traffics 10-50% der Serverlast ausmacht.

In der homeserver.yaml die Worker-Konfiguration aktivieren:
<syntaxhighlight lang=yaml line>
## Worker ##
worker_app: synapse.app.homeserver
daemonize: true
</syntaxhighlight>

und dazugehörige Listener (Abschnitt listener:) aktivieren:
<syntaxhighlight lang=yaml line>
# The TCP replication port
- port: 32892
bind_address: '127.0.0.1'
type: replication
# The HTTP replication port
- port: 32893
bind_address: '127.0.0.1'
type: http
resources:
- names: [replication]
</syntaxhighlight>

Funktionen, die Worker machen sollen, in der homeserver.yaml deaktivieren:
<syntaxhighlight lang=yaml line>
# disable federation sending here, use worker for it
send_federation: False
</syntaxhighlight>
Dann Verzeichnis synapse/workers anlegen, darin federation_sender.yaml:
<syntaxhighlight lang=yaml line>
worker_app: synapse.app.federation_sender

# The replication listener on the synapse to talk to.
worker_replication_host: 127.0.0.1
worker_replication_port: 32892
worker_replication_http_port: 32893

worker_daemonize: True
worker_pid_file: /home/pacs/xyz00/users/matrix/synapse/federation_sender.pid
worker_log_config: /home/pacs/xyz00/users/matrix/synapse/federation_sender.log.config
</syntaxhighlight>
.monitrc um worker erweitern:
<syntaxhighlight lang=shell line>
check process federation_sender with pidfile /home/pacs/xyz00/users/matrix/synapse/federation_sender.pid
start program "/bin/bash -c 'export VIRTUAL_ENV=$HOME/synapse/env && export PATH=$VIRTUAL_ENV/bin:$PATH && cd $HOME/synapse && synctl -w workers/federation_sender.yaml start'"
stop program "/bin/bash -c '/bin/kill $( cat $HOME/synapse/federation_sender.pid )'"
</syntaxhighlight>
Monit neu laden und synapse und federation_sender neustarten:

<syntaxhighlight lang=shell>
monit reload
monit restart all
</syntaxhighlight>

Nach Updates ebenfalls immer Hauptprozess und alle Worker neustarten

<syntaxhighlight lang=shell>
monit restart all
</syntaxhighlight>

== Sliding Sync Proxy ==
Zum Zeitpunkt dieser Anleitung werden aktiv neue Element Anwendungen (Element X) und ein neues Syncverfahren entwickelt um Matrix performanter und weniger ressourcenhungrig zu machen. Bei stärkerer Matrix Nutzung können die neuen Anwendungen besonders mobil schon eine große Entlastung sein.

Ende 2024 wurden grundlegende Funktionen direkt in Synapse implementiert. Der Proxy wird nicht länger weiterentwickelt und sollte deinstalliert werden (nicht vergessen die .well-known zurück zu ändern). Auch der 3rdparty Server [[Conduit]] bringt nativ Support für Sliding Sync.

== Links ==

* https://matrix.org/docs/projects/server/synapse
* https://github.com/element-hq/synapse
* https://github.com/element-hq/synapse/blob/master/INSTALL.md
* https://github.com/matrix-org/sliding-sync
* https://matrix.org/docs/spec/
* https://www.hostsharing.net/loesungen/matrix/
* https://codeberg.org/tpokorra/hs.ansible/src/branch/main/playbooks/synapse
* https://codeberg.org/tpokorra/hs.ansible/src/branch/main/playbooks/element

[[Kategorie:Messenger]]
[[Kategorie:Software]]
[[Kategorie:Eigene Daemons]]
[[Kategorie:Installationsanleitungen]]
[[Kategorie:Ansible Playbook]]

Matrix Synapse installieren

2026-02-12T05:43:12Z

Tim00: /* Update von Synapse */

Der Matrix Server ''Synapse'', der sogenannte 'Homeserver', ist aktuell die einzige vollständige serverseitige Implementierung des Matrix-Protokolls.

{{Textkasten|gelb|Work in Progress|Leider funktioniert die Server-zu-Server-Kommunikation von Synapse hinter dem Apache-Proxy mit den genannten Rewrite-Rules nicht. Bitten Sie dazu den Service, Ihren Apache VHost individuell für den Matrix Server anzupassen.}}

Die hier beschriebene Installation benötigt bei Hostsharing die Paket-Option "RAM". Benötigt werden min. 512 MB. Im Managed Webspace ist diese Option kostenpflichtig: https://www.hostsharing.net/angebote/managed-webspace/ gebucht werden muss der RAM auch bei einem Managed-Server.
Wir empfehlen für den Betrieb einen ''Managed Server''.

Diese Anleitung beschreibt, wie man den Matrix-Homeserver Synapse auf der Managed Hosting Plattform von Hostsharing installieren kann. Dabei sind die User-IDs nach dem Schema @user:beispiel.de aufgebaut, der Homeserver an sich ist unter matrix.beispiel.de erreichbar.

== Vorbereitungen ==

Mit Hilfe von HSAdmin werden angelegt:
# Ein User als Service-User mit ''/bin/bash'' als Shell, zum Beispiel Beispiel: ''xyz00-matrix''
# Eine Domain mit ''xyz00-matrix'' als Domain-Administrator, zum Beispiel ''matrix.beispiel.de''
# Einen Postgresql-User ''xyz00_matrixuser'' mit Passwort ''meinPasswort''
# Eine Postgresql-Datenbank ''xyz00_matrixdb'' mit Datenbank-Owner ''xyz00_matrixuser''

Verwendeter IP-Port für den Server-Dienst:
# Synapse: localhost:32801

== Installation von Synapse ==

Installationsanleitung basierend auf https://matrix-org.github.io/synapse/latest/setup/installation.html#installing-as-a-python-module-from-pypi

Als User ''xyz00-matrix" ein Python3 virtualenv erstellen:

<syntaxhighlight lang="shell">
mkdir -p ~/synapse
cd ~/synapse
python -m venv .venv
</syntaxhighlight>

Synapse und Postgres-Dependencies installieren:

<syntaxhighlight lang="shell">
source ~/synapse/.venv/bin/activate
release=`curl -L https://api.github.com/repos/element-hq/synapse/releases/latest -s | jq -r '.tag_name'`
rm -Rf ~/synapse.src
git clone --depth 1 https://github.com/element-hq/synapse.git -b ${release} ~/synapse.src
cd ~/synapse.src
pip install poetry
poetry install --extras=postgres --extras=oidc
</syntaxhighlight>

Initiale Konfiguration mit richtigem server-name "beispiel.de" generieren, außerdem im laufenden Betrieb keine Statistiken an Matrix.org senden:

<syntaxhighlight lang="shell">
cd ~/synapse
pipenv run python -m synapse.app.homeserver --server-name beispiel.de --config-path homeserver.yaml --generate-config --report-stats=no
</syntaxhighlight>

== Konfiguration von Synapse ==

In die initial generierte Konfiguration muss noch die Port- und Datenbank-Konfiguration eingetragen werden:

Port: Innerhalb der listener-section den Port 8008 auf 32801 (wie initial definiert) ändern, alles andere beibehalten:

<syntaxhighlight lang=yaml line>
- port: 32801
tls: false
bind_addresses: ['::1', '127.0.0.1']
type: http
x_forwarded: true
</syntaxhighlight>

Postgres-Datenbank:
<syntaxhighlight lang=yaml line>
database:
# The database engine name
name: "psycopg2"
# Arguments to pass to the engine
args:
host: "localhost"
database: "xyz00_matrixdb"
user: "xyz00_matrixuser"
password: "meinPasswort"
cp_min: 5
cp_max: 10
</syntaxhighlight>

== Starten der Dienste ==

Der ''Synapse''-Dienst wird hier als Service-Unit im SystemD des Users eingetragen.

Lege dazu die folgende Datei an: ''~/.config/systemd/user/synapse.service'' mit dem Inhalt:
<syntaxhighlight lang="ini" line>
[Unit]
Description=Synapse

[Service]
Type=simple
WorkingDirectory=%h/synapse
Environment=LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libjemalloc.so.2
ExecStart=pipenv run python -m synapse.app.homeserver --config-path=%h/synapse/homeserver.yaml

[Install]
WantedBy=default.target
</syntaxhighlight>

Durch Aufruf der folgenden Kommandos wird der Dienst aktiviert und gestartet:
<syntaxhighlight lang="shell" lines>
systemctl --user daemon-reload
systemctl --user enable synapse.service
systemctl --user start synapse.service
</syntaxhighlight>
== Einrichten des Apache VHost ==

Die ''~/doms/matrix.beispiel.de/.htaccess'' mit dem Editor der Wahl öffnen und
folgende Konfiguration einfügen:
<syntaxhighlight lang=apache line>
DirectoryIndex disabled
RewriteEngine On
RewriteBase /
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-l
RewriteRule .* http://localhost:32801%{REQUEST_URI} [NE,proxy]
RequestHeader set X-Forwarded-Proto "https"
</syntaxhighlight>
== Well-Known unter beispiel.de ==

Damit die User-Accounts das Format @user:beispiel.de haben, der Server aber unter matrix.beispiel.de erreichbar ist, müssen noch folgende zwei Dateien unter der Domain beispiel.de abgelegt werden:

https://beispiel.de/.well-known/matrix/server
<syntaxhighlight lang=json line>
{
"m.server": "matrix.beispiel.de:443"
}
</syntaxhighlight>

https://beispiel.de/.well-known/matrix/client
<syntaxhighlight lang=json line>
{
"m.homeserver": {
"base_url": "https://matrix.beispiel.de"
},
"m.identity_server": {
"base_url": "https://vector.im"
}
}
</syntaxhighlight>

Für die muss noch der CORS-Header Access-Control-Allow-Origin "*" gesetzt werden, damit die Datei aus beliebigem Riot-Web im Browser abrufbar ist. Dazu in den Ordner .well-known/matrix/ folgende .htaccess anlegen:
<syntaxhighlight lang=apache line>
<IfModule mod_headers.c>
Header set Access-Control-Allow-Origin "*"
</IfModule>
</syntaxhighlight>

Die Dokumentation dazu findet man unter https://matrix.org/docs/spec/server_server/r0.1.2#get-well-known-matrix-server und https://matrix.org/docs/spec/client_server/r0.5.0#get-well-known-matrix-client

== Update von Synapse ==

Normalerweise sollte es so gehen, mit pipenv:

<syntaxhighlight lang=shell>
cd ~/synapse
pipenv update --outdated || echo "there are packages to update"
pipenv update
systemctl --user restart synapse
</syntaxhighlight>

In seltenen Fällen gibt es Probleme bei den Abhängigkeiten, die schon wieder aktualisiert wurden, und nicht mehr kompatibel zum aktuellen Synapse sind.
Dann ist es zu empfehlen, Synapse mit der offiziellen poetry.lock Datei zu aktualisieren, um die Konflikte zu vermeiden.

mit poetry:
<syntaxhighlight lang=shell>
systemctl --user stop synapse.service
source ~/.venv/bin/activate
release=`curl -L https://api.github.com/repos/element-hq/synapse/releases/latest -s | jq -r '.tag_name'`
rm -Rf ~/synapse.src
git clone --depth 1 https://github.com/element-hq/synapse.git -b ${release} ~/synapse.src
cd ~/synapse.src
pip install poetry
poetry install --extras=postgres --extras=oidc
systemctl --user start synapse.service
</syntaxhighlight>

Wenn die Föderation für den Synapse Server aktiviert ist, kann mit dem [https://federationtester.matrix.org/ Matrix Federation Tester] die eigene Instanz auf die laufende Version geprüft werden. Als Server nicht matrix.example.org eingeben, sondern den öffentlichen Namen, wo auch die Benutzernamen drauf laufen, z.B. example.org

Ansonsten ist die laufende Version auch über die URL https://matrix.example.org/_synapse/admin/v1/server_version zu erfahren.

== Element-Web ==

Element-Web ist aus Server-Seite eine rein statische html+javascript-Kombination, daher:

* Account und Domain anlegen (separat von der Synapse-Domain)
* [https://github.com/element-hq/element-web/releases/latest aktuelles element-web release] .tgz herunterladen
* Symlink von htdocs-ssl auf entpacktes element-web-Verzeichnis
* config.sample.json in config.json kopieren und Matrix-Homeserver-Einträge anpassen
* Piwik aus config.json entfernen

== SAML mit Synapse ==

Synapse unterstützt mit Version 1.1.0 SAML. Dazu wie folgt vorgehen:

Das Paket xmlsec1 muss installiert sein:

<syntaxhighlight lang=shell>
$ xmlsec1 --version
xmlsec1 1.2.23 (openssl)
</syntaxhighlight>

Das Python-Paket pysaml2 installieren

<syntaxhighlight lang=shell>
cd ~/synapse
pipenv shell
pipenv install pysaml2
</syntaxhighlight>

In der homeserver.yaml die SAML-Direktiven einkommentieren, hier mit dem Beispiel eines SAML IdP unter https://login.beispiel.de/simplesaml/saml2/idp/metadata.php:

<syntaxhighlight lang=yaml line>
# Once SAML support is enabled, a metadata file will be exposed at
# https://<server>:<port>/_matrix/saml2/metadata.xml, which you may be able to
# use to configure your SAML IdP with. Alternatively, you can manually configure
# the IdP to use an ACS location of
# https://<server>:<port>/_matrix/saml2/authn_response.
#
saml2_config:
sp_config:
# point this to the IdP's metadata. You can use either a local file or
# (preferably) a URL.
metadata:
#local: ["saml2/idp.xml"]
remote:
- url: https://login.beispiel.de/simplesaml/saml2/idp/metadata.php
</syntaxhighlight>
Wichtig ist außerdem, dass die public_baseurl in der homeserver.yaml gesetzt ist, damit Synapse weiß, wie es erreichbar ist und dies in seine SP-Metadaten einbauen kann:
<syntaxhighlight lang=yaml line>
public_baseurl: https://matrix.beispiel.de/
</syntaxhighlight>
Die Service-Provider-Konfiguration als XML bekommt man von Synapse dann wie schon in der homeserver.yaml als Kommentar beschrieben, unter https://matrix.beispiel.de/_matrix/saml2/metadata.xml

Diese dann in den SAML-IdP-importieren und dann sollte der Single-Sign-On via SAML funktionieren.

== Federation Sender Worker für Synapse ==

Zur Parallelisierung bietet Synapse das Konzept "Worker" an, die spezifische Aufgaben übernehmen, damit der Hauptprozess diese nicht durchführen muss.

Details dazu: https://github.com/matrix-org/synapse/blob/master/docs/workers.md

Ein einfach einzurichtender Worker, der auch viel Last abfedert, ist der Federation Sender Worker, da das Verschicken des Federation-Traffics 10-50% der Serverlast ausmacht.

In der homeserver.yaml die Worker-Konfiguration aktivieren:
<syntaxhighlight lang=yaml line>
## Worker ##
worker_app: synapse.app.homeserver
daemonize: true
</syntaxhighlight>

und dazugehörige Listener (Abschnitt listener:) aktivieren:
<syntaxhighlight lang=yaml line>
# The TCP replication port
- port: 32892
bind_address: '127.0.0.1'
type: replication
# The HTTP replication port
- port: 32893
bind_address: '127.0.0.1'
type: http
resources:
- names: [replication]
</syntaxhighlight>

Funktionen, die Worker machen sollen, in der homeserver.yaml deaktivieren:
<syntaxhighlight lang=yaml line>
# disable federation sending here, use worker for it
send_federation: False
</syntaxhighlight>
Dann Verzeichnis synapse/workers anlegen, darin federation_sender.yaml:
<syntaxhighlight lang=yaml line>
worker_app: synapse.app.federation_sender

# The replication listener on the synapse to talk to.
worker_replication_host: 127.0.0.1
worker_replication_port: 32892
worker_replication_http_port: 32893

worker_daemonize: True
worker_pid_file: /home/pacs/xyz00/users/matrix/synapse/federation_sender.pid
worker_log_config: /home/pacs/xyz00/users/matrix/synapse/federation_sender.log.config
</syntaxhighlight>
.monitrc um worker erweitern:
<syntaxhighlight lang=shell line>
check process federation_sender with pidfile /home/pacs/xyz00/users/matrix/synapse/federation_sender.pid
start program "/bin/bash -c 'export VIRTUAL_ENV=$HOME/synapse/env && export PATH=$VIRTUAL_ENV/bin:$PATH && cd $HOME/synapse && synctl -w workers/federation_sender.yaml start'"
stop program "/bin/bash -c '/bin/kill $( cat $HOME/synapse/federation_sender.pid )'"
</syntaxhighlight>
Monit neu laden und synapse und federation_sender neustarten:

<syntaxhighlight lang=shell>
monit reload
monit restart all
</syntaxhighlight>

Nach Updates ebenfalls immer Hauptprozess und alle Worker neustarten

<syntaxhighlight lang=shell>
monit restart all
</syntaxhighlight>

== Sliding Sync Proxy ==
Zum Zeitpunkt dieser Anleitung werden aktiv neue Element Anwendungen (Element X) und ein neues Syncverfahren entwickelt um Matrix performanter und weniger ressourcenhungrig zu machen. Bei stärkerer Matrix Nutzung können die neuen Anwendungen besonders mobil schon eine große Entlastung sein.

Ende 2024 wurden grundlegende Funktionen direkt in Synapse implementiert. Der Proxy wird nicht länger weiterentwickelt und sollte deinstalliert werden (nicht vergessen die .well-known zurück zu ändern). Auch der 3rdparty Server [[Conduit]] bringt nativ Support für Sliding Sync.

== Links ==

* https://matrix.org/docs/projects/server/synapse
* https://github.com/element-hq/synapse
* https://github.com/element-hq/synapse/blob/master/INSTALL.md
* https://github.com/matrix-org/sliding-sync
* https://matrix.org/docs/spec/
* https://www.hostsharing.net/loesungen/matrix/
* https://codeberg.org/tpokorra/hs.ansible/src/branch/main/playbooks/synapse
* https://codeberg.org/tpokorra/hs.ansible/src/branch/main/playbooks/element

[[Kategorie:Messenger]]
[[Kategorie:Software]]
[[Kategorie:Eigene Daemons]]
[[Kategorie:Installationsanleitungen]]
[[Kategorie:Ansible Playbook]]

ImapCopy

2026-02-11T16:55:06Z

Tim00: kleine Verbesserungen: Typo und screen

== ImapCopy ==

ImapCopy ist ein Werkzeug, mit dem man ein komplettes IMAP-Postfach in ein IMAP-Postfach auf einem anderen Server (bei einem anderen Anbieter) kopieren kann. Wir verwenden es für die Migration von Postfächern. Eine Alternative ist [[OfflineIMAP]].

== Installation ImapCopy ==

ImapCopy ist auf den HS Hive schon installiert

== Einrichtung allgemein ==

Anmelden per ssh als ein Benutzer in einem HS-Paket.

<syntaxhighlight lang="bash">
xyz00-imapcopy@h01:~$
</syntaxhighlight>

Dort wird ein Arbeitsverzeichnis erstellt

<syntaxhighlight lang="bash">
xyz00-imapcopy@h01:~$ mkdir imapcopy
xyz00-imapcopy@h01:~$ cd imapcopy
</syntaxhighlight>

Die Konfiguration wird in einer Datei ImapCopy.cfg gespeichert

<syntaxhighlight lang="bash">
xyz00-imapcopy@h01:~/imapcopy$ vi ImapCopy.cfg
</syntaxhighlight>

=== Config Web.de -> HS Benutzer ===

Muster Inhalt der Datei ImapCopy.cfg

<syntaxhighlight lang="bash" line>
#############################################################
# imapcopy config
# all lines beginning with # are comments and will be ignored
#############################################################

##############
# Sourceserver
##############
SourceServer imap.web.de
SourcePort 143

###################
# Destinationserver
###################
DestServer xyz00.hostsharing.net
DestPort 143

#########
# Options
#########
#
# DebugSrc and DebugDest will show all traffic between IMAPCopy and Server
#
#DebugSrc
#DebugDst

#################
# Folders to skip
#################
#skipfolder INBOX.Trash
#skipfolder INBOX.Sent
#skipfolder "INBOX.Sent Objects"

#################
# Folders to copy
#################
#copyfolder INBOX
#copyfolder "INBOX.My personal files"
#copyfolder INBOX.Net-Connection.dy
#copyfolder INBOX.test

#######################################################
# Rootfolder
# Can be specified to copy the Folder-Structure under
# a separate folder instead of inbox
#######################################################
#DstRootFolder "Your old Mails"

###############################################################
# Specify Flags that are supported on the destination server
# (AllowFlags) or flags that should be filtered out (DenyFlags)
# If not specified, all Flags are copyied 1:1
# If AllowFlags is specified, all not specified Flags will be
# removed and not copied to the destination
# If DenyFlags is specified, those flags will be removed and
# the remaining ones will be copied
# Both (AllowFlags and DenyFlags) could be specified but
# would (in most cases) make no sense
##############################################################
#AllowFlags "\Seen\Answered\Flagged\Deleted\Draft Junk NonJunk $MDNSent $Forwared"
DenyFlags "\Recent"

##############################################################
# Timezone conversion
# The imap rfc is not clear on what kind of time offsets
# can be used. +XXXX -XXXX will be supported on all servers
# You can add as many entries as needed in the form
# converttimezone SRC DST
# to convert zones that your target server rejects
##############################################################
converttimezone "UTC" "+0000"
converttimezone "UT" "+0000"

#############################
# List of users and passwords
#############################
# SourceUser SourcePassword DestinationUser DestinationPassword
Copy "xyz@web.de" "Euer-Passwort" "xyz00-imap" "Benutzer-Passwort"
</syntaxhighlight>

=== Config gmail.com -> HS Benutzer ===

Da ImapCopy nicht direkt SSL unterstützt benötigt z.b. gmail und ggf einige andere die weiter unten beschrieben Lösung mit einem stunnel.

== Testen einer Verbindung ==

Zum testen ob die Daten alle OK sind auf der shell einfach:

<syntaxhighlight lang="bash">
xyz00-imapcopy@h01:~/imapcopy$ imapcopy -t
</syntaxhighlight>

eingeben.

== Daten austauschen ==

Wir empfehlen: Benutze eine <code>screen</code> Sitzung, damit die Übertragung nicht durch einen Verbindungsabbruch durcheinander kommt!

<syntaxhighlight lang="bash">
xyz00-imapcopy@h01:~/imapcopy$ screen
xyz00-imapcopy@h01:~/imapcopy$ imapcopy
</syntaxhighlight>

== Hilfe ==

<syntaxhighlight lang="bash">
xyz00-imapcopy@h01:~/imapcopy$ imapcopy -h
xyz00-imapcopy@h01:~/imapcopy$ man imapcopy
</syntaxhighlight>

== ssl via stunnel ==

Es wird eine Konfuguration Datei , hier stunnel-to-gmail.conf, benötigt.

<syntaxhighlight lang="bash">
xyz00-imapcopy@h01:~/imapcopy$ vi stunnel-to-gmail.conf
</syntaxhighlight>

Inhalt der Datei stunnel-to-gmail.conf:

<syntaxhighlight lang="ini" line>
foreground=yes

; Some performance tunings
socket = l:TCP_NODELAY=1
socket = r:TCP_NODELAY=1

; Some debugging stuff useful for troubleshooting
debug = 7

; Pfad for pid file
pid = /tmp/stunnel4-xyz00.pid

; Use it for client mode
client = yes

; Service-level configuration

[imap]
accept = 127.0.0.1:10143
connect = imap.gmail.com:993
retry = yes

[imap]
accept = 127.0.0.1:20143
connect = xyz00.hostsharing.net:993
retry = yes
</syntaxhighlight>

=== Änderung in der ImapCopy.cfg ===

<syntaxhighlight lang="ini" line>
##############
# Sourceserver
##############
SourceServer 127.0.0.1
SourcePort 10143

###################
# Destinationserver
###################
DestServer 127.0.0.1
DestPort 20143

#############################
# List of users and passwords
#############################
# SourceUser SourcePassword DestinationUser DestinationPassword
Copy "xyz@gmail.com" "passwort" "xyz00-imap" "passwort"
</syntaxhighlight>

=== stunnel aufbauen ===

Wir öffnen eine zweite shell.

<syntaxhighlight lang="bash" line>
xyz00-imapcopy@h01:~/imapcopy$ stunnel4 stunnel-to-gmail.conf
</syntaxhighlight>

=== Verbindung prüfen und herstellen ===

Siehe -> Testen einer Verbindung
und -> Daten austauschen

[[Kategorie:HSDoku]]
[[Kategorie:Installationsanleitungen]]
[[Kategorie:Glossar]]
[[Kategorie:Software]]
[[Kategorie:E-Mail]]

Matrix Synapse installieren

2026-01-23T21:24:50Z

Tim00: /* Update von Synapse */

Der Matrix Server ''Synapse'', der sogenannte 'Homeserver', ist aktuell die einzige vollständige serverseitige Implementierung des Matrix-Protokolls.

{{Textkasten|gelb|Work in Progress|Leider funktioniert die Server-zu-Server-Kommunikation von Synapse hinter dem Apache-Proxy mit den genannten Rewrite-Rules nicht. Bitten Sie dazu den Service, Ihren Apache VHost individuell für den Matrix Server anzupassen.}}

Die hier beschriebene Installation benötigt bei Hostsharing die Paket-Option "RAM". Benötigt werden min. 512 MB. Im Managed Webspace ist diese Option kostenpflichtig: https://www.hostsharing.net/angebote/managed-webspace/ gebucht werden muss der RAM auch bei einem Managed-Server.
Wir empfehlen für den Betrieb einen ''Managed Server''.

Diese Anleitung beschreibt, wie man den Matrix-Homeserver Synapse auf der Managed Hosting Plattform von Hostsharing installieren kann. Dabei sind die User-IDs nach dem Schema @user:beispiel.de aufgebaut, der Homeserver an sich ist unter matrix.beispiel.de erreichbar.

== Vorbereitungen ==

Mit Hilfe von HSAdmin werden angelegt:
# Ein User als Service-User mit ''/bin/bash'' als Shell, zum Beispiel Beispiel: ''xyz00-matrix''
# Eine Domain mit ''xyz00-matrix'' als Domain-Administrator, zum Beispiel ''matrix.beispiel.de''
# Einen Postgresql-User ''xyz00_matrixuser'' mit Passwort ''meinPasswort''
# Eine Postgresql-Datenbank ''xyz00_matrixdb'' mit Datenbank-Owner ''xyz00_matrixuser''

Verwendeter IP-Port für den Server-Dienst:
# Synapse: localhost:32801

== Installation von Synapse ==

Installationsanleitung basierend auf https://matrix-org.github.io/synapse/latest/setup/installation.html#installing-as-a-python-module-from-pypi

Als User ''xyz00-matrix" ein Python3 virtualenv erstellen:

<syntaxhighlight lang="shell">
mkdir -p ~/synapse
cd ~/synapse
python -m venv .venv
</syntaxhighlight>

Synapse und Postgres-Dependencies installieren:

<syntaxhighlight lang="shell">
source ~/synapse/.venv/bin/activate
release=`curl -L https://api.github.com/repos/element-hq/synapse/releases/latest -s | jq -r '.tag_name'`
rm -Rf ~/synapse.src
git clone --depth 1 https://github.com/element-hq/synapse.git -b ${release} ~/synapse.src
cd ~/synapse.src
pip install poetry
poetry install --extras=postgres --extras=oidc
</syntaxhighlight>

Initiale Konfiguration mit richtigem server-name "beispiel.de" generieren, außerdem im laufenden Betrieb keine Statistiken an Matrix.org senden:

<syntaxhighlight lang="shell">
cd ~/synapse
pipenv run python -m synapse.app.homeserver --server-name beispiel.de --config-path homeserver.yaml --generate-config --report-stats=no
</syntaxhighlight>

== Konfiguration von Synapse ==

In die initial generierte Konfiguration muss noch die Port- und Datenbank-Konfiguration eingetragen werden:

Port: Innerhalb der listener-section den Port 8008 auf 32801 (wie initial definiert) ändern, alles andere beibehalten:

<syntaxhighlight lang=yaml line>
- port: 32801
tls: false
bind_addresses: ['::1', '127.0.0.1']
type: http
x_forwarded: true
</syntaxhighlight>

Postgres-Datenbank:
<syntaxhighlight lang=yaml line>
database:
# The database engine name
name: "psycopg2"
# Arguments to pass to the engine
args:
host: "localhost"
database: "xyz00_matrixdb"
user: "xyz00_matrixuser"
password: "meinPasswort"
cp_min: 5
cp_max: 10
</syntaxhighlight>

== Starten der Dienste ==

Der ''Synapse''-Dienst wird hier als Service-Unit im SystemD des Users eingetragen.

Lege dazu die folgende Datei an: ''~/.config/systemd/user/synapse.service'' mit dem Inhalt:
<syntaxhighlight lang="ini" line>
[Unit]
Description=Synapse

[Service]
Type=simple
WorkingDirectory=%h/synapse
Environment=LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libjemalloc.so.2
ExecStart=pipenv run python -m synapse.app.homeserver --config-path=%h/synapse/homeserver.yaml

[Install]
WantedBy=default.target
</syntaxhighlight>

Durch Aufruf der folgenden Kommandos wird der Dienst aktiviert und gestartet:
<syntaxhighlight lang="shell" lines>
systemctl --user daemon-reload
systemctl --user enable synapse.service
systemctl --user start synapse.service
</syntaxhighlight>
== Einrichten des Apache VHost ==

Die ''~/doms/matrix.beispiel.de/.htaccess'' mit dem Editor der Wahl öffnen und
folgende Konfiguration einfügen:
<syntaxhighlight lang=apache line>
DirectoryIndex disabled
RewriteEngine On
RewriteBase /
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-l
RewriteRule .* http://localhost:32801%{REQUEST_URI} [NE,proxy]
RequestHeader set X-Forwarded-Proto "https"
</syntaxhighlight>
== Well-Known unter beispiel.de ==

Damit die User-Accounts das Format @user:beispiel.de haben, der Server aber unter matrix.beispiel.de erreichbar ist, müssen noch folgende zwei Dateien unter der Domain beispiel.de abgelegt werden:

https://beispiel.de/.well-known/matrix/server
<syntaxhighlight lang=json line>
{
"m.server": "matrix.beispiel.de:443"
}
</syntaxhighlight>

https://beispiel.de/.well-known/matrix/client
<syntaxhighlight lang=json line>
{
"m.homeserver": {
"base_url": "https://matrix.beispiel.de"
},
"m.identity_server": {
"base_url": "https://vector.im"
}
}
</syntaxhighlight>

Für die muss noch der CORS-Header Access-Control-Allow-Origin "*" gesetzt werden, damit die Datei aus beliebigem Riot-Web im Browser abrufbar ist. Dazu in den Ordner .well-known/matrix/ folgende .htaccess anlegen:
<syntaxhighlight lang=apache line>
<IfModule mod_headers.c>
Header set Access-Control-Allow-Origin "*"
</IfModule>
</syntaxhighlight>

Die Dokumentation dazu findet man unter https://matrix.org/docs/spec/server_server/r0.1.2#get-well-known-matrix-server und https://matrix.org/docs/spec/client_server/r0.5.0#get-well-known-matrix-client

== Update von Synapse ==

mit poetry:
<syntaxhighlight lang=shell>
systemctl --user stop synapse.service
source ~/.venv/bin/activate
release=`curl -L https://api.github.com/repos/element-hq/synapse/releases/latest -s | jq -r '.tag_name'`
rm -Rf ~/synapse.src
git clone --depth 1 https://github.com/element-hq/synapse.git -b ${release} ~/synapse.src
cd ~/synapse.src
pip install poetry
poetry install --extras=postgres --extras=oidc
systemctl --user start synapse.service
</syntaxhighlight>

Es ist zu empfehlen, Synapse mit der offiziellen poetry.lock Datei zu aktualisieren, weil es sonst Versionskonflikte geben kann, wenn Abhängigkeiten schon wieder aktualisiert wurden, und nicht mehr kompatibel zum aktuellen Synapse sind.

Wenn die Föderation für den Synapse Server aktiviert ist, kann mit dem [https://federationtester.matrix.org/ Matrix Federation Tester] die eigene Instanz auf die laufende Version geprüft werden. Als Server nicht matrix.example.org eingeben, sondern den öffentlichen Namen, wo auch die Benutzernamen drauf laufen, z.B. example.org

Ansonsten ist die laufende Version auch über die URL https://matrix.example.org/_synapse/admin/v1/server_version zu erfahren.

== Element-Web ==

Element-Web ist aus Server-Seite eine rein statische html+javascript-Kombination, daher:

* Account und Domain anlegen (separat von der Synapse-Domain)
* [https://github.com/element-hq/element-web/releases/latest aktuelles element-web release] .tgz herunterladen
* Symlink von htdocs-ssl auf entpacktes element-web-Verzeichnis
* config.sample.json in config.json kopieren und Matrix-Homeserver-Einträge anpassen
* Piwik aus config.json entfernen

== SAML mit Synapse ==

Synapse unterstützt mit Version 1.1.0 SAML. Dazu wie folgt vorgehen:

Das Paket xmlsec1 muss installiert sein:

<syntaxhighlight lang=shell>
$ xmlsec1 --version
xmlsec1 1.2.23 (openssl)
</syntaxhighlight>

Das Python-Paket pysaml2 installieren

<syntaxhighlight lang=shell>
cd ~/synapse
pipenv shell
pipenv install pysaml2
</syntaxhighlight>

In der homeserver.yaml die SAML-Direktiven einkommentieren, hier mit dem Beispiel eines SAML IdP unter https://login.beispiel.de/simplesaml/saml2/idp/metadata.php:

<syntaxhighlight lang=yaml line>
# Once SAML support is enabled, a metadata file will be exposed at
# https://<server>:<port>/_matrix/saml2/metadata.xml, which you may be able to
# use to configure your SAML IdP with. Alternatively, you can manually configure
# the IdP to use an ACS location of
# https://<server>:<port>/_matrix/saml2/authn_response.
#
saml2_config:
sp_config:
# point this to the IdP's metadata. You can use either a local file or
# (preferably) a URL.
metadata:
#local: ["saml2/idp.xml"]
remote:
- url: https://login.beispiel.de/simplesaml/saml2/idp/metadata.php
</syntaxhighlight>
Wichtig ist außerdem, dass die public_baseurl in der homeserver.yaml gesetzt ist, damit Synapse weiß, wie es erreichbar ist und dies in seine SP-Metadaten einbauen kann:
<syntaxhighlight lang=yaml line>
public_baseurl: https://matrix.beispiel.de/
</syntaxhighlight>
Die Service-Provider-Konfiguration als XML bekommt man von Synapse dann wie schon in der homeserver.yaml als Kommentar beschrieben, unter https://matrix.beispiel.de/_matrix/saml2/metadata.xml

Diese dann in den SAML-IdP-importieren und dann sollte der Single-Sign-On via SAML funktionieren.

== Federation Sender Worker für Synapse ==

Zur Parallelisierung bietet Synapse das Konzept "Worker" an, die spezifische Aufgaben übernehmen, damit der Hauptprozess diese nicht durchführen muss.

Details dazu: https://github.com/matrix-org/synapse/blob/master/docs/workers.md

Ein einfach einzurichtender Worker, der auch viel Last abfedert, ist der Federation Sender Worker, da das Verschicken des Federation-Traffics 10-50% der Serverlast ausmacht.

In der homeserver.yaml die Worker-Konfiguration aktivieren:
<syntaxhighlight lang=yaml line>
## Worker ##
worker_app: synapse.app.homeserver
daemonize: true
</syntaxhighlight>

und dazugehörige Listener (Abschnitt listener:) aktivieren:
<syntaxhighlight lang=yaml line>
# The TCP replication port
- port: 32892
bind_address: '127.0.0.1'
type: replication
# The HTTP replication port
- port: 32893
bind_address: '127.0.0.1'
type: http
resources:
- names: [replication]
</syntaxhighlight>

Funktionen, die Worker machen sollen, in der homeserver.yaml deaktivieren:
<syntaxhighlight lang=yaml line>
# disable federation sending here, use worker for it
send_federation: False
</syntaxhighlight>
Dann Verzeichnis synapse/workers anlegen, darin federation_sender.yaml:
<syntaxhighlight lang=yaml line>
worker_app: synapse.app.federation_sender

# The replication listener on the synapse to talk to.
worker_replication_host: 127.0.0.1
worker_replication_port: 32892
worker_replication_http_port: 32893

worker_daemonize: True
worker_pid_file: /home/pacs/xyz00/users/matrix/synapse/federation_sender.pid
worker_log_config: /home/pacs/xyz00/users/matrix/synapse/federation_sender.log.config
</syntaxhighlight>
.monitrc um worker erweitern:
<syntaxhighlight lang=shell line>
check process federation_sender with pidfile /home/pacs/xyz00/users/matrix/synapse/federation_sender.pid
start program "/bin/bash -c 'export VIRTUAL_ENV=$HOME/synapse/env && export PATH=$VIRTUAL_ENV/bin:$PATH && cd $HOME/synapse && synctl -w workers/federation_sender.yaml start'"
stop program "/bin/bash -c '/bin/kill $( cat $HOME/synapse/federation_sender.pid )'"
</syntaxhighlight>
Monit neu laden und synapse und federation_sender neustarten:

<syntaxhighlight lang=shell>
monit reload
monit restart all
</syntaxhighlight>

Nach Updates ebenfalls immer Hauptprozess und alle Worker neustarten

<syntaxhighlight lang=shell>
monit restart all
</syntaxhighlight>

== Sliding Sync Proxy ==
Zum Zeitpunkt dieser Anleitung werden aktiv neue Element Anwendungen (Element X) und ein neues Syncverfahren entwickelt um Matrix performanter und weniger ressourcenhungrig zu machen. Bei stärkerer Matrix Nutzung können die neuen Anwendungen besonders mobil schon eine große Entlastung sein.

Ende 2024 wurden grundlegende Funktionen direkt in Synapse implementiert. Der Proxy wird nicht länger weiterentwickelt und sollte deinstalliert werden (nicht vergessen die .well-known zurück zu ändern). Auch der 3rdparty Server [[Conduit]] bringt nativ Support für Sliding Sync.

== Links ==

* https://matrix.org/docs/projects/server/synapse
* https://github.com/element-hq/synapse
* https://github.com/element-hq/synapse/blob/master/INSTALL.md
* https://github.com/matrix-org/sliding-sync
* https://matrix.org/docs/spec/
* https://www.hostsharing.net/loesungen/matrix/
* https://codeberg.org/tpokorra/hs.ansible/src/branch/main/playbooks/synapse
* https://codeberg.org/tpokorra/hs.ansible/src/branch/main/playbooks/element

[[Kategorie:Messenger]]
[[Kategorie:Software]]
[[Kategorie:Eigene Daemons]]
[[Kategorie:Installationsanleitungen]]
[[Kategorie:Ansible Playbook]]

Matrix Synapse installieren

2026-01-23T21:24:28Z

Tim00: /* Installation von Synapse */

Der Matrix Server ''Synapse'', der sogenannte 'Homeserver', ist aktuell die einzige vollständige serverseitige Implementierung des Matrix-Protokolls.

{{Textkasten|gelb|Work in Progress|Leider funktioniert die Server-zu-Server-Kommunikation von Synapse hinter dem Apache-Proxy mit den genannten Rewrite-Rules nicht. Bitten Sie dazu den Service, Ihren Apache VHost individuell für den Matrix Server anzupassen.}}

Die hier beschriebene Installation benötigt bei Hostsharing die Paket-Option "RAM". Benötigt werden min. 512 MB. Im Managed Webspace ist diese Option kostenpflichtig: https://www.hostsharing.net/angebote/managed-webspace/ gebucht werden muss der RAM auch bei einem Managed-Server.
Wir empfehlen für den Betrieb einen ''Managed Server''.

Diese Anleitung beschreibt, wie man den Matrix-Homeserver Synapse auf der Managed Hosting Plattform von Hostsharing installieren kann. Dabei sind die User-IDs nach dem Schema @user:beispiel.de aufgebaut, der Homeserver an sich ist unter matrix.beispiel.de erreichbar.

== Vorbereitungen ==

Mit Hilfe von HSAdmin werden angelegt:
# Ein User als Service-User mit ''/bin/bash'' als Shell, zum Beispiel Beispiel: ''xyz00-matrix''
# Eine Domain mit ''xyz00-matrix'' als Domain-Administrator, zum Beispiel ''matrix.beispiel.de''
# Einen Postgresql-User ''xyz00_matrixuser'' mit Passwort ''meinPasswort''
# Eine Postgresql-Datenbank ''xyz00_matrixdb'' mit Datenbank-Owner ''xyz00_matrixuser''

Verwendeter IP-Port für den Server-Dienst:
# Synapse: localhost:32801

== Installation von Synapse ==

Installationsanleitung basierend auf https://matrix-org.github.io/synapse/latest/setup/installation.html#installing-as-a-python-module-from-pypi

Als User ''xyz00-matrix" ein Python3 virtualenv erstellen:

<syntaxhighlight lang="shell">
mkdir -p ~/synapse
cd ~/synapse
python -m venv .venv
</syntaxhighlight>

Synapse und Postgres-Dependencies installieren:

<syntaxhighlight lang="shell">
source ~/synapse/.venv/bin/activate
release=`curl -L https://api.github.com/repos/element-hq/synapse/releases/latest -s | jq -r '.tag_name'`
rm -Rf ~/synapse.src
git clone --depth 1 https://github.com/element-hq/synapse.git -b ${release} ~/synapse.src
cd ~/synapse.src
pip install poetry
poetry install --extras=postgres --extras=oidc
</syntaxhighlight>

Initiale Konfiguration mit richtigem server-name "beispiel.de" generieren, außerdem im laufenden Betrieb keine Statistiken an Matrix.org senden:

<syntaxhighlight lang="shell">
cd ~/synapse
pipenv run python -m synapse.app.homeserver --server-name beispiel.de --config-path homeserver.yaml --generate-config --report-stats=no
</syntaxhighlight>

== Konfiguration von Synapse ==

In die initial generierte Konfiguration muss noch die Port- und Datenbank-Konfiguration eingetragen werden:

Port: Innerhalb der listener-section den Port 8008 auf 32801 (wie initial definiert) ändern, alles andere beibehalten:

<syntaxhighlight lang=yaml line>
- port: 32801
tls: false
bind_addresses: ['::1', '127.0.0.1']
type: http
x_forwarded: true
</syntaxhighlight>

Postgres-Datenbank:
<syntaxhighlight lang=yaml line>
database:
# The database engine name
name: "psycopg2"
# Arguments to pass to the engine
args:
host: "localhost"
database: "xyz00_matrixdb"
user: "xyz00_matrixuser"
password: "meinPasswort"
cp_min: 5
cp_max: 10
</syntaxhighlight>

== Starten der Dienste ==

Der ''Synapse''-Dienst wird hier als Service-Unit im SystemD des Users eingetragen.

Lege dazu die folgende Datei an: ''~/.config/systemd/user/synapse.service'' mit dem Inhalt:
<syntaxhighlight lang="ini" line>
[Unit]
Description=Synapse

[Service]
Type=simple
WorkingDirectory=%h/synapse
Environment=LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libjemalloc.so.2
ExecStart=pipenv run python -m synapse.app.homeserver --config-path=%h/synapse/homeserver.yaml

[Install]
WantedBy=default.target
</syntaxhighlight>

Durch Aufruf der folgenden Kommandos wird der Dienst aktiviert und gestartet:
<syntaxhighlight lang="shell" lines>
systemctl --user daemon-reload
systemctl --user enable synapse.service
systemctl --user start synapse.service
</syntaxhighlight>
== Einrichten des Apache VHost ==

Die ''~/doms/matrix.beispiel.de/.htaccess'' mit dem Editor der Wahl öffnen und
folgende Konfiguration einfügen:
<syntaxhighlight lang=apache line>
DirectoryIndex disabled
RewriteEngine On
RewriteBase /
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-l
RewriteRule .* http://localhost:32801%{REQUEST_URI} [NE,proxy]
RequestHeader set X-Forwarded-Proto "https"
</syntaxhighlight>
== Well-Known unter beispiel.de ==

Damit die User-Accounts das Format @user:beispiel.de haben, der Server aber unter matrix.beispiel.de erreichbar ist, müssen noch folgende zwei Dateien unter der Domain beispiel.de abgelegt werden:

https://beispiel.de/.well-known/matrix/server
<syntaxhighlight lang=json line>
{
"m.server": "matrix.beispiel.de:443"
}
</syntaxhighlight>

https://beispiel.de/.well-known/matrix/client
<syntaxhighlight lang=json line>
{
"m.homeserver": {
"base_url": "https://matrix.beispiel.de"
},
"m.identity_server": {
"base_url": "https://vector.im"
}
}
</syntaxhighlight>

Für die muss noch der CORS-Header Access-Control-Allow-Origin "*" gesetzt werden, damit die Datei aus beliebigem Riot-Web im Browser abrufbar ist. Dazu in den Ordner .well-known/matrix/ folgende .htaccess anlegen:
<syntaxhighlight lang=apache line>
<IfModule mod_headers.c>
Header set Access-Control-Allow-Origin "*"
</IfModule>
</syntaxhighlight>

Die Dokumentation dazu findet man unter https://matrix.org/docs/spec/server_server/r0.1.2#get-well-known-matrix-server und https://matrix.org/docs/spec/client_server/r0.5.0#get-well-known-matrix-client

== Update von Synapse ==

mit poetry:
<syntaxhighlight lang=shell>
systemctl --user stop synapse.service
source .venv/bin/activate
release=`curl -L https://api.github.com/repos/element-hq/synapse/releases/latest -s | jq -r '.tag_name'`
rm -Rf ~/synapse.src
git clone --depth 1 https://github.com/element-hq/synapse.git -b ${release} ~/synapse.src
cd ~/synapse.src
pip install poetry
poetry install --extras=postgres --extras=oidc
systemctl --user start synapse.service
</syntaxhighlight>

Es ist zu empfehlen, Synapse mit der offiziellen poetry.lock Datei zu aktualisieren, weil es sonst Versionskonflikte geben kann, wenn Abhängigkeiten schon wieder aktualisiert wurden, und nicht mehr kompatibel zum aktuellen Synapse sind.

Wenn die Föderation für den Synapse Server aktiviert ist, kann mit dem [https://federationtester.matrix.org/ Matrix Federation Tester] die eigene Instanz auf die laufende Version geprüft werden. Als Server nicht matrix.example.org eingeben, sondern den öffentlichen Namen, wo auch die Benutzernamen drauf laufen, z.B. example.org

Ansonsten ist die laufende Version auch über die URL https://matrix.example.org/_synapse/admin/v1/server_version zu erfahren.

== Element-Web ==

Element-Web ist aus Server-Seite eine rein statische html+javascript-Kombination, daher:

* Account und Domain anlegen (separat von der Synapse-Domain)
* [https://github.com/element-hq/element-web/releases/latest aktuelles element-web release] .tgz herunterladen
* Symlink von htdocs-ssl auf entpacktes element-web-Verzeichnis
* config.sample.json in config.json kopieren und Matrix-Homeserver-Einträge anpassen
* Piwik aus config.json entfernen

== SAML mit Synapse ==

Synapse unterstützt mit Version 1.1.0 SAML. Dazu wie folgt vorgehen:

Das Paket xmlsec1 muss installiert sein:

<syntaxhighlight lang=shell>
$ xmlsec1 --version
xmlsec1 1.2.23 (openssl)
</syntaxhighlight>

Das Python-Paket pysaml2 installieren

<syntaxhighlight lang=shell>
cd ~/synapse
pipenv shell
pipenv install pysaml2
</syntaxhighlight>

In der homeserver.yaml die SAML-Direktiven einkommentieren, hier mit dem Beispiel eines SAML IdP unter https://login.beispiel.de/simplesaml/saml2/idp/metadata.php:

<syntaxhighlight lang=yaml line>
# Once SAML support is enabled, a metadata file will be exposed at
# https://<server>:<port>/_matrix/saml2/metadata.xml, which you may be able to
# use to configure your SAML IdP with. Alternatively, you can manually configure
# the IdP to use an ACS location of
# https://<server>:<port>/_matrix/saml2/authn_response.
#
saml2_config:
sp_config:
# point this to the IdP's metadata. You can use either a local file or
# (preferably) a URL.
metadata:
#local: ["saml2/idp.xml"]
remote:
- url: https://login.beispiel.de/simplesaml/saml2/idp/metadata.php
</syntaxhighlight>
Wichtig ist außerdem, dass die public_baseurl in der homeserver.yaml gesetzt ist, damit Synapse weiß, wie es erreichbar ist und dies in seine SP-Metadaten einbauen kann:
<syntaxhighlight lang=yaml line>
public_baseurl: https://matrix.beispiel.de/
</syntaxhighlight>
Die Service-Provider-Konfiguration als XML bekommt man von Synapse dann wie schon in der homeserver.yaml als Kommentar beschrieben, unter https://matrix.beispiel.de/_matrix/saml2/metadata.xml

Diese dann in den SAML-IdP-importieren und dann sollte der Single-Sign-On via SAML funktionieren.

== Federation Sender Worker für Synapse ==

Zur Parallelisierung bietet Synapse das Konzept "Worker" an, die spezifische Aufgaben übernehmen, damit der Hauptprozess diese nicht durchführen muss.

Details dazu: https://github.com/matrix-org/synapse/blob/master/docs/workers.md

Ein einfach einzurichtender Worker, der auch viel Last abfedert, ist der Federation Sender Worker, da das Verschicken des Federation-Traffics 10-50% der Serverlast ausmacht.

In der homeserver.yaml die Worker-Konfiguration aktivieren:
<syntaxhighlight lang=yaml line>
## Worker ##
worker_app: synapse.app.homeserver
daemonize: true
</syntaxhighlight>

und dazugehörige Listener (Abschnitt listener:) aktivieren:
<syntaxhighlight lang=yaml line>
# The TCP replication port
- port: 32892
bind_address: '127.0.0.1'
type: replication
# The HTTP replication port
- port: 32893
bind_address: '127.0.0.1'
type: http
resources:
- names: [replication]
</syntaxhighlight>

Funktionen, die Worker machen sollen, in der homeserver.yaml deaktivieren:
<syntaxhighlight lang=yaml line>
# disable federation sending here, use worker for it
send_federation: False
</syntaxhighlight>
Dann Verzeichnis synapse/workers anlegen, darin federation_sender.yaml:
<syntaxhighlight lang=yaml line>
worker_app: synapse.app.federation_sender

# The replication listener on the synapse to talk to.
worker_replication_host: 127.0.0.1
worker_replication_port: 32892
worker_replication_http_port: 32893

worker_daemonize: True
worker_pid_file: /home/pacs/xyz00/users/matrix/synapse/federation_sender.pid
worker_log_config: /home/pacs/xyz00/users/matrix/synapse/federation_sender.log.config
</syntaxhighlight>
.monitrc um worker erweitern:
<syntaxhighlight lang=shell line>
check process federation_sender with pidfile /home/pacs/xyz00/users/matrix/synapse/federation_sender.pid
start program "/bin/bash -c 'export VIRTUAL_ENV=$HOME/synapse/env && export PATH=$VIRTUAL_ENV/bin:$PATH && cd $HOME/synapse && synctl -w workers/federation_sender.yaml start'"
stop program "/bin/bash -c '/bin/kill $( cat $HOME/synapse/federation_sender.pid )'"
</syntaxhighlight>
Monit neu laden und synapse und federation_sender neustarten:

<syntaxhighlight lang=shell>
monit reload
monit restart all
</syntaxhighlight>

Nach Updates ebenfalls immer Hauptprozess und alle Worker neustarten

<syntaxhighlight lang=shell>
monit restart all
</syntaxhighlight>

== Sliding Sync Proxy ==
Zum Zeitpunkt dieser Anleitung werden aktiv neue Element Anwendungen (Element X) und ein neues Syncverfahren entwickelt um Matrix performanter und weniger ressourcenhungrig zu machen. Bei stärkerer Matrix Nutzung können die neuen Anwendungen besonders mobil schon eine große Entlastung sein.

Ende 2024 wurden grundlegende Funktionen direkt in Synapse implementiert. Der Proxy wird nicht länger weiterentwickelt und sollte deinstalliert werden (nicht vergessen die .well-known zurück zu ändern). Auch der 3rdparty Server [[Conduit]] bringt nativ Support für Sliding Sync.

== Links ==

* https://matrix.org/docs/projects/server/synapse
* https://github.com/element-hq/synapse
* https://github.com/element-hq/synapse/blob/master/INSTALL.md
* https://github.com/matrix-org/sliding-sync
* https://matrix.org/docs/spec/
* https://www.hostsharing.net/loesungen/matrix/
* https://codeberg.org/tpokorra/hs.ansible/src/branch/main/playbooks/synapse
* https://codeberg.org/tpokorra/hs.ansible/src/branch/main/playbooks/element

[[Kategorie:Messenger]]
[[Kategorie:Software]]
[[Kategorie:Eigene Daemons]]
[[Kategorie:Installationsanleitungen]]
[[Kategorie:Ansible Playbook]]

Matrix Synapse installieren

2026-01-23T21:22:42Z

Tim00: /* Update von Synapse */

Der Matrix Server ''Synapse'', der sogenannte 'Homeserver', ist aktuell die einzige vollständige serverseitige Implementierung des Matrix-Protokolls.

{{Textkasten|gelb|Work in Progress|Leider funktioniert die Server-zu-Server-Kommunikation von Synapse hinter dem Apache-Proxy mit den genannten Rewrite-Rules nicht. Bitten Sie dazu den Service, Ihren Apache VHost individuell für den Matrix Server anzupassen.}}

Die hier beschriebene Installation benötigt bei Hostsharing die Paket-Option "RAM". Benötigt werden min. 512 MB. Im Managed Webspace ist diese Option kostenpflichtig: https://www.hostsharing.net/angebote/managed-webspace/ gebucht werden muss der RAM auch bei einem Managed-Server.
Wir empfehlen für den Betrieb einen ''Managed Server''.

Diese Anleitung beschreibt, wie man den Matrix-Homeserver Synapse auf der Managed Hosting Plattform von Hostsharing installieren kann. Dabei sind die User-IDs nach dem Schema @user:beispiel.de aufgebaut, der Homeserver an sich ist unter matrix.beispiel.de erreichbar.

== Vorbereitungen ==

Mit Hilfe von HSAdmin werden angelegt:
# Ein User als Service-User mit ''/bin/bash'' als Shell, zum Beispiel Beispiel: ''xyz00-matrix''
# Eine Domain mit ''xyz00-matrix'' als Domain-Administrator, zum Beispiel ''matrix.beispiel.de''
# Einen Postgresql-User ''xyz00_matrixuser'' mit Passwort ''meinPasswort''
# Eine Postgresql-Datenbank ''xyz00_matrixdb'' mit Datenbank-Owner ''xyz00_matrixuser''

Verwendeter IP-Port für den Server-Dienst:
# Synapse: localhost:32801

== Installation von Synapse ==

Installationsanleitung basierend auf https://matrix-org.github.io/synapse/latest/setup/installation.html#installing-as-a-python-module-from-pypi

Als User ''xyz00-matrix" ein Python3 virtualenv erstellen:

<syntaxhighlight lang="shell">
mkdir -p ~/synapse
cd ~/synapse
pipenv install
</syntaxhighlight>

Synapse und Postgres-Dependencies installieren:

<syntaxhighlight lang="shell">
cd ~/synapse
pipenv shell
pipenv install matrix-synapse[postgres]
</syntaxhighlight>

Initiale Konfiguration mit richtigem server-name "beispiel.de" generieren, außerdem im laufenden Betrieb keine Statistiken an Matrix.org senden:

<syntaxhighlight lang="shell">
cd ~/synapse
pipenv run python -m synapse.app.homeserver --server-name beispiel.de --config-path homeserver.yaml --generate-config --report-stats=no
</syntaxhighlight>

== Konfiguration von Synapse ==

In die initial generierte Konfiguration muss noch die Port- und Datenbank-Konfiguration eingetragen werden:

Port: Innerhalb der listener-section den Port 8008 auf 32801 (wie initial definiert) ändern, alles andere beibehalten:

<syntaxhighlight lang=yaml line>
- port: 32801
tls: false
bind_addresses: ['::1', '127.0.0.1']
type: http
x_forwarded: true
</syntaxhighlight>

Postgres-Datenbank:
<syntaxhighlight lang=yaml line>
database:
# The database engine name
name: "psycopg2"
# Arguments to pass to the engine
args:
host: "localhost"
database: "xyz00_matrixdb"
user: "xyz00_matrixuser"
password: "meinPasswort"
cp_min: 5
cp_max: 10
</syntaxhighlight>

== Starten der Dienste ==

Der ''Synapse''-Dienst wird hier als Service-Unit im SystemD des Users eingetragen.

Lege dazu die folgende Datei an: ''~/.config/systemd/user/synapse.service'' mit dem Inhalt:
<syntaxhighlight lang="ini" line>
[Unit]
Description=Synapse

[Service]
Type=simple
WorkingDirectory=%h/synapse
Environment=LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libjemalloc.so.2
ExecStart=pipenv run python -m synapse.app.homeserver --config-path=%h/synapse/homeserver.yaml

[Install]
WantedBy=default.target
</syntaxhighlight>

Durch Aufruf der folgenden Kommandos wird der Dienst aktiviert und gestartet:
<syntaxhighlight lang="shell" lines>
systemctl --user daemon-reload
systemctl --user enable synapse.service
systemctl --user start synapse.service
</syntaxhighlight>
== Einrichten des Apache VHost ==

Die ''~/doms/matrix.beispiel.de/.htaccess'' mit dem Editor der Wahl öffnen und
folgende Konfiguration einfügen:
<syntaxhighlight lang=apache line>
DirectoryIndex disabled
RewriteEngine On
RewriteBase /
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-l
RewriteRule .* http://localhost:32801%{REQUEST_URI} [NE,proxy]
RequestHeader set X-Forwarded-Proto "https"
</syntaxhighlight>
== Well-Known unter beispiel.de ==

Damit die User-Accounts das Format @user:beispiel.de haben, der Server aber unter matrix.beispiel.de erreichbar ist, müssen noch folgende zwei Dateien unter der Domain beispiel.de abgelegt werden:

https://beispiel.de/.well-known/matrix/server
<syntaxhighlight lang=json line>
{
"m.server": "matrix.beispiel.de:443"
}
</syntaxhighlight>

https://beispiel.de/.well-known/matrix/client
<syntaxhighlight lang=json line>
{
"m.homeserver": {
"base_url": "https://matrix.beispiel.de"
},
"m.identity_server": {
"base_url": "https://vector.im"
}
}
</syntaxhighlight>

Für die muss noch der CORS-Header Access-Control-Allow-Origin "*" gesetzt werden, damit die Datei aus beliebigem Riot-Web im Browser abrufbar ist. Dazu in den Ordner .well-known/matrix/ folgende .htaccess anlegen:
<syntaxhighlight lang=apache line>
<IfModule mod_headers.c>
Header set Access-Control-Allow-Origin "*"
</IfModule>
</syntaxhighlight>

Die Dokumentation dazu findet man unter https://matrix.org/docs/spec/server_server/r0.1.2#get-well-known-matrix-server und https://matrix.org/docs/spec/client_server/r0.5.0#get-well-known-matrix-client

== Update von Synapse ==

mit poetry:
<syntaxhighlight lang=shell>
systemctl --user stop synapse.service
source .venv/bin/activate
release=`curl -L https://api.github.com/repos/element-hq/synapse/releases/latest -s | jq -r '.tag_name'`
rm -Rf ~/synapse.src
git clone --depth 1 https://github.com/element-hq/synapse.git -b ${release} ~/synapse.src
cd ~/synapse.src
pip install poetry
poetry install --extras=postgres --extras=oidc
systemctl --user start synapse.service
</syntaxhighlight>

Es ist zu empfehlen, Synapse mit der offiziellen poetry.lock Datei zu aktualisieren, weil es sonst Versionskonflikte geben kann, wenn Abhängigkeiten schon wieder aktualisiert wurden, und nicht mehr kompatibel zum aktuellen Synapse sind.

Wenn die Föderation für den Synapse Server aktiviert ist, kann mit dem [https://federationtester.matrix.org/ Matrix Federation Tester] die eigene Instanz auf die laufende Version geprüft werden. Als Server nicht matrix.example.org eingeben, sondern den öffentlichen Namen, wo auch die Benutzernamen drauf laufen, z.B. example.org

Ansonsten ist die laufende Version auch über die URL https://matrix.example.org/_synapse/admin/v1/server_version zu erfahren.

== Element-Web ==

Element-Web ist aus Server-Seite eine rein statische html+javascript-Kombination, daher:

* Account und Domain anlegen (separat von der Synapse-Domain)
* [https://github.com/element-hq/element-web/releases/latest aktuelles element-web release] .tgz herunterladen
* Symlink von htdocs-ssl auf entpacktes element-web-Verzeichnis
* config.sample.json in config.json kopieren und Matrix-Homeserver-Einträge anpassen
* Piwik aus config.json entfernen

== SAML mit Synapse ==

Synapse unterstützt mit Version 1.1.0 SAML. Dazu wie folgt vorgehen:

Das Paket xmlsec1 muss installiert sein:

<syntaxhighlight lang=shell>
$ xmlsec1 --version
xmlsec1 1.2.23 (openssl)
</syntaxhighlight>

Das Python-Paket pysaml2 installieren

<syntaxhighlight lang=shell>
cd ~/synapse
pipenv shell
pipenv install pysaml2
</syntaxhighlight>

In der homeserver.yaml die SAML-Direktiven einkommentieren, hier mit dem Beispiel eines SAML IdP unter https://login.beispiel.de/simplesaml/saml2/idp/metadata.php:

<syntaxhighlight lang=yaml line>
# Once SAML support is enabled, a metadata file will be exposed at
# https://<server>:<port>/_matrix/saml2/metadata.xml, which you may be able to
# use to configure your SAML IdP with. Alternatively, you can manually configure
# the IdP to use an ACS location of
# https://<server>:<port>/_matrix/saml2/authn_response.
#
saml2_config:
sp_config:
# point this to the IdP's metadata. You can use either a local file or
# (preferably) a URL.
metadata:
#local: ["saml2/idp.xml"]
remote:
- url: https://login.beispiel.de/simplesaml/saml2/idp/metadata.php
</syntaxhighlight>
Wichtig ist außerdem, dass die public_baseurl in der homeserver.yaml gesetzt ist, damit Synapse weiß, wie es erreichbar ist und dies in seine SP-Metadaten einbauen kann:
<syntaxhighlight lang=yaml line>
public_baseurl: https://matrix.beispiel.de/
</syntaxhighlight>
Die Service-Provider-Konfiguration als XML bekommt man von Synapse dann wie schon in der homeserver.yaml als Kommentar beschrieben, unter https://matrix.beispiel.de/_matrix/saml2/metadata.xml

Diese dann in den SAML-IdP-importieren und dann sollte der Single-Sign-On via SAML funktionieren.

== Federation Sender Worker für Synapse ==

Zur Parallelisierung bietet Synapse das Konzept "Worker" an, die spezifische Aufgaben übernehmen, damit der Hauptprozess diese nicht durchführen muss.

Details dazu: https://github.com/matrix-org/synapse/blob/master/docs/workers.md

Ein einfach einzurichtender Worker, der auch viel Last abfedert, ist der Federation Sender Worker, da das Verschicken des Federation-Traffics 10-50% der Serverlast ausmacht.

In der homeserver.yaml die Worker-Konfiguration aktivieren:
<syntaxhighlight lang=yaml line>
## Worker ##
worker_app: synapse.app.homeserver
daemonize: true
</syntaxhighlight>

und dazugehörige Listener (Abschnitt listener:) aktivieren:
<syntaxhighlight lang=yaml line>
# The TCP replication port
- port: 32892
bind_address: '127.0.0.1'
type: replication
# The HTTP replication port
- port: 32893
bind_address: '127.0.0.1'
type: http
resources:
- names: [replication]
</syntaxhighlight>

Funktionen, die Worker machen sollen, in der homeserver.yaml deaktivieren:
<syntaxhighlight lang=yaml line>
# disable federation sending here, use worker for it
send_federation: False
</syntaxhighlight>
Dann Verzeichnis synapse/workers anlegen, darin federation_sender.yaml:
<syntaxhighlight lang=yaml line>
worker_app: synapse.app.federation_sender

# The replication listener on the synapse to talk to.
worker_replication_host: 127.0.0.1
worker_replication_port: 32892
worker_replication_http_port: 32893

worker_daemonize: True
worker_pid_file: /home/pacs/xyz00/users/matrix/synapse/federation_sender.pid
worker_log_config: /home/pacs/xyz00/users/matrix/synapse/federation_sender.log.config
</syntaxhighlight>
.monitrc um worker erweitern:
<syntaxhighlight lang=shell line>
check process federation_sender with pidfile /home/pacs/xyz00/users/matrix/synapse/federation_sender.pid
start program "/bin/bash -c 'export VIRTUAL_ENV=$HOME/synapse/env && export PATH=$VIRTUAL_ENV/bin:$PATH && cd $HOME/synapse && synctl -w workers/federation_sender.yaml start'"
stop program "/bin/bash -c '/bin/kill $( cat $HOME/synapse/federation_sender.pid )'"
</syntaxhighlight>
Monit neu laden und synapse und federation_sender neustarten:

<syntaxhighlight lang=shell>
monit reload
monit restart all
</syntaxhighlight>

Nach Updates ebenfalls immer Hauptprozess und alle Worker neustarten

<syntaxhighlight lang=shell>
monit restart all
</syntaxhighlight>

== Sliding Sync Proxy ==
Zum Zeitpunkt dieser Anleitung werden aktiv neue Element Anwendungen (Element X) und ein neues Syncverfahren entwickelt um Matrix performanter und weniger ressourcenhungrig zu machen. Bei stärkerer Matrix Nutzung können die neuen Anwendungen besonders mobil schon eine große Entlastung sein.

Ende 2024 wurden grundlegende Funktionen direkt in Synapse implementiert. Der Proxy wird nicht länger weiterentwickelt und sollte deinstalliert werden (nicht vergessen die .well-known zurück zu ändern). Auch der 3rdparty Server [[Conduit]] bringt nativ Support für Sliding Sync.

== Links ==

* https://matrix.org/docs/projects/server/synapse
* https://github.com/element-hq/synapse
* https://github.com/element-hq/synapse/blob/master/INSTALL.md
* https://github.com/matrix-org/sliding-sync
* https://matrix.org/docs/spec/
* https://www.hostsharing.net/loesungen/matrix/
* https://codeberg.org/tpokorra/hs.ansible/src/branch/main/playbooks/synapse
* https://codeberg.org/tpokorra/hs.ansible/src/branch/main/playbooks/element

[[Kategorie:Messenger]]
[[Kategorie:Software]]
[[Kategorie:Eigene Daemons]]
[[Kategorie:Installationsanleitungen]]
[[Kategorie:Ansible Playbook]]

Matrix Synapse installieren

2026-01-23T21:21:54Z

Tim00: /* Update von Synapse */

Der Matrix Server ''Synapse'', der sogenannte 'Homeserver', ist aktuell die einzige vollständige serverseitige Implementierung des Matrix-Protokolls.

{{Textkasten|gelb|Work in Progress|Leider funktioniert die Server-zu-Server-Kommunikation von Synapse hinter dem Apache-Proxy mit den genannten Rewrite-Rules nicht. Bitten Sie dazu den Service, Ihren Apache VHost individuell für den Matrix Server anzupassen.}}

Die hier beschriebene Installation benötigt bei Hostsharing die Paket-Option "RAM". Benötigt werden min. 512 MB. Im Managed Webspace ist diese Option kostenpflichtig: https://www.hostsharing.net/angebote/managed-webspace/ gebucht werden muss der RAM auch bei einem Managed-Server.
Wir empfehlen für den Betrieb einen ''Managed Server''.

Diese Anleitung beschreibt, wie man den Matrix-Homeserver Synapse auf der Managed Hosting Plattform von Hostsharing installieren kann. Dabei sind die User-IDs nach dem Schema @user:beispiel.de aufgebaut, der Homeserver an sich ist unter matrix.beispiel.de erreichbar.

== Vorbereitungen ==

Mit Hilfe von HSAdmin werden angelegt:
# Ein User als Service-User mit ''/bin/bash'' als Shell, zum Beispiel Beispiel: ''xyz00-matrix''
# Eine Domain mit ''xyz00-matrix'' als Domain-Administrator, zum Beispiel ''matrix.beispiel.de''
# Einen Postgresql-User ''xyz00_matrixuser'' mit Passwort ''meinPasswort''
# Eine Postgresql-Datenbank ''xyz00_matrixdb'' mit Datenbank-Owner ''xyz00_matrixuser''

Verwendeter IP-Port für den Server-Dienst:
# Synapse: localhost:32801

== Installation von Synapse ==

Installationsanleitung basierend auf https://matrix-org.github.io/synapse/latest/setup/installation.html#installing-as-a-python-module-from-pypi

Als User ''xyz00-matrix" ein Python3 virtualenv erstellen:

<syntaxhighlight lang="shell">
mkdir -p ~/synapse
cd ~/synapse
pipenv install
</syntaxhighlight>

Synapse und Postgres-Dependencies installieren:

<syntaxhighlight lang="shell">
cd ~/synapse
pipenv shell
pipenv install matrix-synapse[postgres]
</syntaxhighlight>

Initiale Konfiguration mit richtigem server-name "beispiel.de" generieren, außerdem im laufenden Betrieb keine Statistiken an Matrix.org senden:

<syntaxhighlight lang="shell">
cd ~/synapse
pipenv run python -m synapse.app.homeserver --server-name beispiel.de --config-path homeserver.yaml --generate-config --report-stats=no
</syntaxhighlight>

== Konfiguration von Synapse ==

In die initial generierte Konfiguration muss noch die Port- und Datenbank-Konfiguration eingetragen werden:

Port: Innerhalb der listener-section den Port 8008 auf 32801 (wie initial definiert) ändern, alles andere beibehalten:

<syntaxhighlight lang=yaml line>
- port: 32801
tls: false
bind_addresses: ['::1', '127.0.0.1']
type: http
x_forwarded: true
</syntaxhighlight>

Postgres-Datenbank:
<syntaxhighlight lang=yaml line>
database:
# The database engine name
name: "psycopg2"
# Arguments to pass to the engine
args:
host: "localhost"
database: "xyz00_matrixdb"
user: "xyz00_matrixuser"
password: "meinPasswort"
cp_min: 5
cp_max: 10
</syntaxhighlight>

== Starten der Dienste ==

Der ''Synapse''-Dienst wird hier als Service-Unit im SystemD des Users eingetragen.

Lege dazu die folgende Datei an: ''~/.config/systemd/user/synapse.service'' mit dem Inhalt:
<syntaxhighlight lang="ini" line>
[Unit]
Description=Synapse

[Service]
Type=simple
WorkingDirectory=%h/synapse
Environment=LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libjemalloc.so.2
ExecStart=pipenv run python -m synapse.app.homeserver --config-path=%h/synapse/homeserver.yaml

[Install]
WantedBy=default.target
</syntaxhighlight>

Durch Aufruf der folgenden Kommandos wird der Dienst aktiviert und gestartet:
<syntaxhighlight lang="shell" lines>
systemctl --user daemon-reload
systemctl --user enable synapse.service
systemctl --user start synapse.service
</syntaxhighlight>
== Einrichten des Apache VHost ==

Die ''~/doms/matrix.beispiel.de/.htaccess'' mit dem Editor der Wahl öffnen und
folgende Konfiguration einfügen:
<syntaxhighlight lang=apache line>
DirectoryIndex disabled
RewriteEngine On
RewriteBase /
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-l
RewriteRule .* http://localhost:32801%{REQUEST_URI} [NE,proxy]
RequestHeader set X-Forwarded-Proto "https"
</syntaxhighlight>
== Well-Known unter beispiel.de ==

Damit die User-Accounts das Format @user:beispiel.de haben, der Server aber unter matrix.beispiel.de erreichbar ist, müssen noch folgende zwei Dateien unter der Domain beispiel.de abgelegt werden:

https://beispiel.de/.well-known/matrix/server
<syntaxhighlight lang=json line>
{
"m.server": "matrix.beispiel.de:443"
}
</syntaxhighlight>

https://beispiel.de/.well-known/matrix/client
<syntaxhighlight lang=json line>
{
"m.homeserver": {
"base_url": "https://matrix.beispiel.de"
},
"m.identity_server": {
"base_url": "https://vector.im"
}
}
</syntaxhighlight>

Für die muss noch der CORS-Header Access-Control-Allow-Origin "*" gesetzt werden, damit die Datei aus beliebigem Riot-Web im Browser abrufbar ist. Dazu in den Ordner .well-known/matrix/ folgende .htaccess anlegen:
<syntaxhighlight lang=apache line>
<IfModule mod_headers.c>
Header set Access-Control-Allow-Origin "*"
</IfModule>
</syntaxhighlight>

Die Dokumentation dazu findet man unter https://matrix.org/docs/spec/server_server/r0.1.2#get-well-known-matrix-server und https://matrix.org/docs/spec/client_server/r0.5.0#get-well-known-matrix-client

== Update von Synapse ==

mit pipenv:
<syntaxhighlight lang=shell>
systemctl --user stop synapse.service
source .venv/bin/activate
release=`curl -L https://api.github.com/repos/element-hq/synapse/releases/latest -s | jq -r '.tag_name'`
rm -Rf ~/synapse.src
git clone --depth 1 https://github.com/element-hq/synapse.git -b ${release} ~/synapse.src
cd ~/synapse.src
pip install poetry
poetry install --extras=postgres --extras=oidc
systemctl --user start synapse.service
</syntaxhighlight>

Es ist zu empfehlen, Synapse mit der offiziellen poetry.lock Datei zu aktualisieren, weil es sonst Versionskonflikte geben kann, wenn Abhängigkeiten schon wieder aktualisiert wurden, und nicht mehr kompatibel zum aktuellen Synapse sind.

Wenn die Föderation für den Synapse Server aktiviert ist, kann mit dem [https://federationtester.matrix.org/ Matrix Federation Tester] die eigene Instanz auf die laufende Version geprüft werden. Als Server nicht matrix.example.org eingeben, sondern den öffentlichen Namen, wo auch die Benutzernamen drauf laufen, z.B. example.org

Ansonsten ist die laufende Version auch über die URL https://matrix.example.org/_synapse/admin/v1/server_version zu erfahren.

== Element-Web ==

Element-Web ist aus Server-Seite eine rein statische html+javascript-Kombination, daher:

* Account und Domain anlegen (separat von der Synapse-Domain)
* [https://github.com/element-hq/element-web/releases/latest aktuelles element-web release] .tgz herunterladen
* Symlink von htdocs-ssl auf entpacktes element-web-Verzeichnis
* config.sample.json in config.json kopieren und Matrix-Homeserver-Einträge anpassen
* Piwik aus config.json entfernen

== SAML mit Synapse ==

Synapse unterstützt mit Version 1.1.0 SAML. Dazu wie folgt vorgehen:

Das Paket xmlsec1 muss installiert sein:

<syntaxhighlight lang=shell>
$ xmlsec1 --version
xmlsec1 1.2.23 (openssl)
</syntaxhighlight>

Das Python-Paket pysaml2 installieren

<syntaxhighlight lang=shell>
cd ~/synapse
pipenv shell
pipenv install pysaml2
</syntaxhighlight>

In der homeserver.yaml die SAML-Direktiven einkommentieren, hier mit dem Beispiel eines SAML IdP unter https://login.beispiel.de/simplesaml/saml2/idp/metadata.php:

<syntaxhighlight lang=yaml line>
# Once SAML support is enabled, a metadata file will be exposed at
# https://<server>:<port>/_matrix/saml2/metadata.xml, which you may be able to
# use to configure your SAML IdP with. Alternatively, you can manually configure
# the IdP to use an ACS location of
# https://<server>:<port>/_matrix/saml2/authn_response.
#
saml2_config:
sp_config:
# point this to the IdP's metadata. You can use either a local file or
# (preferably) a URL.
metadata:
#local: ["saml2/idp.xml"]
remote:
- url: https://login.beispiel.de/simplesaml/saml2/idp/metadata.php
</syntaxhighlight>
Wichtig ist außerdem, dass die public_baseurl in der homeserver.yaml gesetzt ist, damit Synapse weiß, wie es erreichbar ist und dies in seine SP-Metadaten einbauen kann:
<syntaxhighlight lang=yaml line>
public_baseurl: https://matrix.beispiel.de/
</syntaxhighlight>
Die Service-Provider-Konfiguration als XML bekommt man von Synapse dann wie schon in der homeserver.yaml als Kommentar beschrieben, unter https://matrix.beispiel.de/_matrix/saml2/metadata.xml

Diese dann in den SAML-IdP-importieren und dann sollte der Single-Sign-On via SAML funktionieren.

== Federation Sender Worker für Synapse ==

Zur Parallelisierung bietet Synapse das Konzept "Worker" an, die spezifische Aufgaben übernehmen, damit der Hauptprozess diese nicht durchführen muss.

Details dazu: https://github.com/matrix-org/synapse/blob/master/docs/workers.md

Ein einfach einzurichtender Worker, der auch viel Last abfedert, ist der Federation Sender Worker, da das Verschicken des Federation-Traffics 10-50% der Serverlast ausmacht.

In der homeserver.yaml die Worker-Konfiguration aktivieren:
<syntaxhighlight lang=yaml line>
## Worker ##
worker_app: synapse.app.homeserver
daemonize: true
</syntaxhighlight>

und dazugehörige Listener (Abschnitt listener:) aktivieren:
<syntaxhighlight lang=yaml line>
# The TCP replication port
- port: 32892
bind_address: '127.0.0.1'
type: replication
# The HTTP replication port
- port: 32893
bind_address: '127.0.0.1'
type: http
resources:
- names: [replication]
</syntaxhighlight>

Funktionen, die Worker machen sollen, in der homeserver.yaml deaktivieren:
<syntaxhighlight lang=yaml line>
# disable federation sending here, use worker for it
send_federation: False
</syntaxhighlight>
Dann Verzeichnis synapse/workers anlegen, darin federation_sender.yaml:
<syntaxhighlight lang=yaml line>
worker_app: synapse.app.federation_sender

# The replication listener on the synapse to talk to.
worker_replication_host: 127.0.0.1
worker_replication_port: 32892
worker_replication_http_port: 32893

worker_daemonize: True
worker_pid_file: /home/pacs/xyz00/users/matrix/synapse/federation_sender.pid
worker_log_config: /home/pacs/xyz00/users/matrix/synapse/federation_sender.log.config
</syntaxhighlight>
.monitrc um worker erweitern:
<syntaxhighlight lang=shell line>
check process federation_sender with pidfile /home/pacs/xyz00/users/matrix/synapse/federation_sender.pid
start program "/bin/bash -c 'export VIRTUAL_ENV=$HOME/synapse/env && export PATH=$VIRTUAL_ENV/bin:$PATH && cd $HOME/synapse && synctl -w workers/federation_sender.yaml start'"
stop program "/bin/bash -c '/bin/kill $( cat $HOME/synapse/federation_sender.pid )'"
</syntaxhighlight>
Monit neu laden und synapse und federation_sender neustarten:

<syntaxhighlight lang=shell>
monit reload
monit restart all
</syntaxhighlight>

Nach Updates ebenfalls immer Hauptprozess und alle Worker neustarten

<syntaxhighlight lang=shell>
monit restart all
</syntaxhighlight>

== Sliding Sync Proxy ==
Zum Zeitpunkt dieser Anleitung werden aktiv neue Element Anwendungen (Element X) und ein neues Syncverfahren entwickelt um Matrix performanter und weniger ressourcenhungrig zu machen. Bei stärkerer Matrix Nutzung können die neuen Anwendungen besonders mobil schon eine große Entlastung sein.

Ende 2024 wurden grundlegende Funktionen direkt in Synapse implementiert. Der Proxy wird nicht länger weiterentwickelt und sollte deinstalliert werden (nicht vergessen die .well-known zurück zu ändern). Auch der 3rdparty Server [[Conduit]] bringt nativ Support für Sliding Sync.

== Links ==

* https://matrix.org/docs/projects/server/synapse
* https://github.com/element-hq/synapse
* https://github.com/element-hq/synapse/blob/master/INSTALL.md
* https://github.com/matrix-org/sliding-sync
* https://matrix.org/docs/spec/
* https://www.hostsharing.net/loesungen/matrix/
* https://codeberg.org/tpokorra/hs.ansible/src/branch/main/playbooks/synapse
* https://codeberg.org/tpokorra/hs.ansible/src/branch/main/playbooks/element

[[Kategorie:Messenger]]
[[Kategorie:Software]]
[[Kategorie:Eigene Daemons]]
[[Kategorie:Installationsanleitungen]]
[[Kategorie:Ansible Playbook]]

Matrix Synapse installieren

2026-01-23T21:21:10Z

Tim00: /* Update von Synapse */

Der Matrix Server ''Synapse'', der sogenannte 'Homeserver', ist aktuell die einzige vollständige serverseitige Implementierung des Matrix-Protokolls.

{{Textkasten|gelb|Work in Progress|Leider funktioniert die Server-zu-Server-Kommunikation von Synapse hinter dem Apache-Proxy mit den genannten Rewrite-Rules nicht. Bitten Sie dazu den Service, Ihren Apache VHost individuell für den Matrix Server anzupassen.}}

Die hier beschriebene Installation benötigt bei Hostsharing die Paket-Option "RAM". Benötigt werden min. 512 MB. Im Managed Webspace ist diese Option kostenpflichtig: https://www.hostsharing.net/angebote/managed-webspace/ gebucht werden muss der RAM auch bei einem Managed-Server.
Wir empfehlen für den Betrieb einen ''Managed Server''.

Diese Anleitung beschreibt, wie man den Matrix-Homeserver Synapse auf der Managed Hosting Plattform von Hostsharing installieren kann. Dabei sind die User-IDs nach dem Schema @user:beispiel.de aufgebaut, der Homeserver an sich ist unter matrix.beispiel.de erreichbar.

== Vorbereitungen ==

Mit Hilfe von HSAdmin werden angelegt:
# Ein User als Service-User mit ''/bin/bash'' als Shell, zum Beispiel Beispiel: ''xyz00-matrix''
# Eine Domain mit ''xyz00-matrix'' als Domain-Administrator, zum Beispiel ''matrix.beispiel.de''
# Einen Postgresql-User ''xyz00_matrixuser'' mit Passwort ''meinPasswort''
# Eine Postgresql-Datenbank ''xyz00_matrixdb'' mit Datenbank-Owner ''xyz00_matrixuser''

Verwendeter IP-Port für den Server-Dienst:
# Synapse: localhost:32801

== Installation von Synapse ==

Installationsanleitung basierend auf https://matrix-org.github.io/synapse/latest/setup/installation.html#installing-as-a-python-module-from-pypi

Als User ''xyz00-matrix" ein Python3 virtualenv erstellen:

<syntaxhighlight lang="shell">
mkdir -p ~/synapse
cd ~/synapse
pipenv install
</syntaxhighlight>

Synapse und Postgres-Dependencies installieren:

<syntaxhighlight lang="shell">
cd ~/synapse
pipenv shell
pipenv install matrix-synapse[postgres]
</syntaxhighlight>

Initiale Konfiguration mit richtigem server-name "beispiel.de" generieren, außerdem im laufenden Betrieb keine Statistiken an Matrix.org senden:

<syntaxhighlight lang="shell">
cd ~/synapse
pipenv run python -m synapse.app.homeserver --server-name beispiel.de --config-path homeserver.yaml --generate-config --report-stats=no
</syntaxhighlight>

== Konfiguration von Synapse ==

In die initial generierte Konfiguration muss noch die Port- und Datenbank-Konfiguration eingetragen werden:

Port: Innerhalb der listener-section den Port 8008 auf 32801 (wie initial definiert) ändern, alles andere beibehalten:

<syntaxhighlight lang=yaml line>
- port: 32801
tls: false
bind_addresses: ['::1', '127.0.0.1']
type: http
x_forwarded: true
</syntaxhighlight>

Postgres-Datenbank:
<syntaxhighlight lang=yaml line>
database:
# The database engine name
name: "psycopg2"
# Arguments to pass to the engine
args:
host: "localhost"
database: "xyz00_matrixdb"
user: "xyz00_matrixuser"
password: "meinPasswort"
cp_min: 5
cp_max: 10
</syntaxhighlight>

== Starten der Dienste ==

Der ''Synapse''-Dienst wird hier als Service-Unit im SystemD des Users eingetragen.

Lege dazu die folgende Datei an: ''~/.config/systemd/user/synapse.service'' mit dem Inhalt:
<syntaxhighlight lang="ini" line>
[Unit]
Description=Synapse

[Service]
Type=simple
WorkingDirectory=%h/synapse
Environment=LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libjemalloc.so.2
ExecStart=pipenv run python -m synapse.app.homeserver --config-path=%h/synapse/homeserver.yaml

[Install]
WantedBy=default.target
</syntaxhighlight>

Durch Aufruf der folgenden Kommandos wird der Dienst aktiviert und gestartet:
<syntaxhighlight lang="shell" lines>
systemctl --user daemon-reload
systemctl --user enable synapse.service
systemctl --user start synapse.service
</syntaxhighlight>
== Einrichten des Apache VHost ==

Die ''~/doms/matrix.beispiel.de/.htaccess'' mit dem Editor der Wahl öffnen und
folgende Konfiguration einfügen:
<syntaxhighlight lang=apache line>
DirectoryIndex disabled
RewriteEngine On
RewriteBase /
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-l
RewriteRule .* http://localhost:32801%{REQUEST_URI} [NE,proxy]
RequestHeader set X-Forwarded-Proto "https"
</syntaxhighlight>
== Well-Known unter beispiel.de ==

Damit die User-Accounts das Format @user:beispiel.de haben, der Server aber unter matrix.beispiel.de erreichbar ist, müssen noch folgende zwei Dateien unter der Domain beispiel.de abgelegt werden:

https://beispiel.de/.well-known/matrix/server
<syntaxhighlight lang=json line>
{
"m.server": "matrix.beispiel.de:443"
}
</syntaxhighlight>

https://beispiel.de/.well-known/matrix/client
<syntaxhighlight lang=json line>
{
"m.homeserver": {
"base_url": "https://matrix.beispiel.de"
},
"m.identity_server": {
"base_url": "https://vector.im"
}
}
</syntaxhighlight>

Für die muss noch der CORS-Header Access-Control-Allow-Origin "*" gesetzt werden, damit die Datei aus beliebigem Riot-Web im Browser abrufbar ist. Dazu in den Ordner .well-known/matrix/ folgende .htaccess anlegen:
<syntaxhighlight lang=apache line>
<IfModule mod_headers.c>
Header set Access-Control-Allow-Origin "*"
</IfModule>
</syntaxhighlight>

Die Dokumentation dazu findet man unter https://matrix.org/docs/spec/server_server/r0.1.2#get-well-known-matrix-server und https://matrix.org/docs/spec/client_server/r0.5.0#get-well-known-matrix-client

== Update von Synapse ==

mit pipenv:
<syntaxhighlight lang=shell>
systemctl --user stop synapse.service
cd ~/synapse
source .venv/bin/activate
release=`curl -L https://api.github.com/repos/element-hq/synapse/releases/latest -s | jq -r '.tag_name'`
rm -Rf synapse.src
git clone --depth 1 https://github.com/element-hq/synapse.git -b ${release} synapse.src
pip install poetry
poetry install --extras=postgres --extras=oidc
systemctl --user start synapse.service
</syntaxhighlight>

Es ist zu empfehlen, Synapse mit der offiziellen poetry.lock Datei zu aktualisieren, weil es sonst Versionskonflikte geben kann, wenn Abhängigkeiten schon wieder aktualisiert wurden, und nicht mehr kompatibel zum aktuellen Synapse sind.

Wenn die Föderation für den Synapse Server aktiviert ist, kann mit dem [https://federationtester.matrix.org/ Matrix Federation Tester] die eigene Instanz auf die laufende Version geprüft werden. Als Server nicht matrix.example.org eingeben, sondern den öffentlichen Namen, wo auch die Benutzernamen drauf laufen, z.B. example.org

Ansonsten ist die laufende Version auch über die URL https://matrix.example.org/_synapse/admin/v1/server_version zu erfahren.

== Element-Web ==

Element-Web ist aus Server-Seite eine rein statische html+javascript-Kombination, daher:

* Account und Domain anlegen (separat von der Synapse-Domain)
* [https://github.com/element-hq/element-web/releases/latest aktuelles element-web release] .tgz herunterladen
* Symlink von htdocs-ssl auf entpacktes element-web-Verzeichnis
* config.sample.json in config.json kopieren und Matrix-Homeserver-Einträge anpassen
* Piwik aus config.json entfernen

== SAML mit Synapse ==

Synapse unterstützt mit Version 1.1.0 SAML. Dazu wie folgt vorgehen:

Das Paket xmlsec1 muss installiert sein:

<syntaxhighlight lang=shell>
$ xmlsec1 --version
xmlsec1 1.2.23 (openssl)
</syntaxhighlight>

Das Python-Paket pysaml2 installieren

<syntaxhighlight lang=shell>
cd ~/synapse
pipenv shell
pipenv install pysaml2
</syntaxhighlight>

In der homeserver.yaml die SAML-Direktiven einkommentieren, hier mit dem Beispiel eines SAML IdP unter https://login.beispiel.de/simplesaml/saml2/idp/metadata.php:

<syntaxhighlight lang=yaml line>
# Once SAML support is enabled, a metadata file will be exposed at
# https://<server>:<port>/_matrix/saml2/metadata.xml, which you may be able to
# use to configure your SAML IdP with. Alternatively, you can manually configure
# the IdP to use an ACS location of
# https://<server>:<port>/_matrix/saml2/authn_response.
#
saml2_config:
sp_config:
# point this to the IdP's metadata. You can use either a local file or
# (preferably) a URL.
metadata:
#local: ["saml2/idp.xml"]
remote:
- url: https://login.beispiel.de/simplesaml/saml2/idp/metadata.php
</syntaxhighlight>
Wichtig ist außerdem, dass die public_baseurl in der homeserver.yaml gesetzt ist, damit Synapse weiß, wie es erreichbar ist und dies in seine SP-Metadaten einbauen kann:
<syntaxhighlight lang=yaml line>
public_baseurl: https://matrix.beispiel.de/
</syntaxhighlight>
Die Service-Provider-Konfiguration als XML bekommt man von Synapse dann wie schon in der homeserver.yaml als Kommentar beschrieben, unter https://matrix.beispiel.de/_matrix/saml2/metadata.xml

Diese dann in den SAML-IdP-importieren und dann sollte der Single-Sign-On via SAML funktionieren.

== Federation Sender Worker für Synapse ==

Zur Parallelisierung bietet Synapse das Konzept "Worker" an, die spezifische Aufgaben übernehmen, damit der Hauptprozess diese nicht durchführen muss.

Details dazu: https://github.com/matrix-org/synapse/blob/master/docs/workers.md

Ein einfach einzurichtender Worker, der auch viel Last abfedert, ist der Federation Sender Worker, da das Verschicken des Federation-Traffics 10-50% der Serverlast ausmacht.

In der homeserver.yaml die Worker-Konfiguration aktivieren:
<syntaxhighlight lang=yaml line>
## Worker ##
worker_app: synapse.app.homeserver
daemonize: true
</syntaxhighlight>

und dazugehörige Listener (Abschnitt listener:) aktivieren:
<syntaxhighlight lang=yaml line>
# The TCP replication port
- port: 32892
bind_address: '127.0.0.1'
type: replication
# The HTTP replication port
- port: 32893
bind_address: '127.0.0.1'
type: http
resources:
- names: [replication]
</syntaxhighlight>

Funktionen, die Worker machen sollen, in der homeserver.yaml deaktivieren:
<syntaxhighlight lang=yaml line>
# disable federation sending here, use worker for it
send_federation: False
</syntaxhighlight>
Dann Verzeichnis synapse/workers anlegen, darin federation_sender.yaml:
<syntaxhighlight lang=yaml line>
worker_app: synapse.app.federation_sender

# The replication listener on the synapse to talk to.
worker_replication_host: 127.0.0.1
worker_replication_port: 32892
worker_replication_http_port: 32893

worker_daemonize: True
worker_pid_file: /home/pacs/xyz00/users/matrix/synapse/federation_sender.pid
worker_log_config: /home/pacs/xyz00/users/matrix/synapse/federation_sender.log.config
</syntaxhighlight>
.monitrc um worker erweitern:
<syntaxhighlight lang=shell line>
check process federation_sender with pidfile /home/pacs/xyz00/users/matrix/synapse/federation_sender.pid
start program "/bin/bash -c 'export VIRTUAL_ENV=$HOME/synapse/env && export PATH=$VIRTUAL_ENV/bin:$PATH && cd $HOME/synapse && synctl -w workers/federation_sender.yaml start'"
stop program "/bin/bash -c '/bin/kill $( cat $HOME/synapse/federation_sender.pid )'"
</syntaxhighlight>
Monit neu laden und synapse und federation_sender neustarten:

<syntaxhighlight lang=shell>
monit reload
monit restart all
</syntaxhighlight>

Nach Updates ebenfalls immer Hauptprozess und alle Worker neustarten

<syntaxhighlight lang=shell>
monit restart all
</syntaxhighlight>

== Sliding Sync Proxy ==
Zum Zeitpunkt dieser Anleitung werden aktiv neue Element Anwendungen (Element X) und ein neues Syncverfahren entwickelt um Matrix performanter und weniger ressourcenhungrig zu machen. Bei stärkerer Matrix Nutzung können die neuen Anwendungen besonders mobil schon eine große Entlastung sein.

Ende 2024 wurden grundlegende Funktionen direkt in Synapse implementiert. Der Proxy wird nicht länger weiterentwickelt und sollte deinstalliert werden (nicht vergessen die .well-known zurück zu ändern). Auch der 3rdparty Server [[Conduit]] bringt nativ Support für Sliding Sync.

== Links ==

* https://matrix.org/docs/projects/server/synapse
* https://github.com/element-hq/synapse
* https://github.com/element-hq/synapse/blob/master/INSTALL.md
* https://github.com/matrix-org/sliding-sync
* https://matrix.org/docs/spec/
* https://www.hostsharing.net/loesungen/matrix/
* https://codeberg.org/tpokorra/hs.ansible/src/branch/main/playbooks/synapse
* https://codeberg.org/tpokorra/hs.ansible/src/branch/main/playbooks/element

[[Kategorie:Messenger]]
[[Kategorie:Software]]
[[Kategorie:Eigene Daemons]]
[[Kategorie:Installationsanleitungen]]
[[Kategorie:Ansible Playbook]]

Matrix Synapse installieren

2026-01-19T07:56:00Z

Tim00: /* Update von Synapse */

Der Matrix Server ''Synapse'', der sogenannte 'Homeserver', ist aktuell die einzige vollständige serverseitige Implementierung des Matrix-Protokolls.

{{Textkasten|gelb|Work in Progress|Leider funktioniert die Server-zu-Server-Kommunikation von Synapse hinter dem Apache-Proxy mit den genannten Rewrite-Rules nicht. Bitten Sie dazu den Service, Ihren Apache VHost individuell für den Matrix Server anzupassen.}}

Die hier beschriebene Installation benötigt bei Hostsharing die Paket-Option "RAM". Benötigt werden min. 512 MB. Im Managed Webspace ist diese Option kostenpflichtig: https://www.hostsharing.net/angebote/managed-webspace/ gebucht werden muss der RAM auch bei einem Managed-Server.
Wir empfehlen für den Betrieb einen ''Managed Server''.

Diese Anleitung beschreibt, wie man den Matrix-Homeserver Synapse auf der Managed Hosting Plattform von Hostsharing installieren kann. Dabei sind die User-IDs nach dem Schema @user:beispiel.de aufgebaut, der Homeserver an sich ist unter matrix.beispiel.de erreichbar.

== Vorbereitungen ==

Mit Hilfe von HSAdmin werden angelegt:
# Ein User als Service-User mit ''/bin/bash'' als Shell, zum Beispiel Beispiel: ''xyz00-matrix''
# Eine Domain mit ''xyz00-matrix'' als Domain-Administrator, zum Beispiel ''matrix.beispiel.de''
# Einen Postgresql-User ''xyz00_matrixuser'' mit Passwort ''meinPasswort''
# Eine Postgresql-Datenbank ''xyz00_matrixdb'' mit Datenbank-Owner ''xyz00_matrixuser''

Verwendeter IP-Port für den Server-Dienst:
# Synapse: localhost:32801

== Installation von Synapse ==

Installationsanleitung basierend auf https://matrix-org.github.io/synapse/latest/setup/installation.html#installing-as-a-python-module-from-pypi

Als User ''xyz00-matrix" ein Python3 virtualenv erstellen:

<syntaxhighlight lang="shell">
mkdir -p ~/synapse
cd ~/synapse
pipenv install
</syntaxhighlight>

Synapse und Postgres-Dependencies installieren:

<syntaxhighlight lang="shell">
cd ~/synapse
pipenv shell
pipenv install matrix-synapse[postgres]
</syntaxhighlight>

Initiale Konfiguration mit richtigem server-name "beispiel.de" generieren, außerdem im laufenden Betrieb keine Statistiken an Matrix.org senden:

<syntaxhighlight lang="shell">
cd ~/synapse
pipenv run python -m synapse.app.homeserver --server-name beispiel.de --config-path homeserver.yaml --generate-config --report-stats=no
</syntaxhighlight>

== Konfiguration von Synapse ==

In die initial generierte Konfiguration muss noch die Port- und Datenbank-Konfiguration eingetragen werden:

Port: Innerhalb der listener-section den Port 8008 auf 32801 (wie initial definiert) ändern, alles andere beibehalten:

<syntaxhighlight lang=yaml line>
- port: 32801
tls: false
bind_addresses: ['::1', '127.0.0.1']
type: http
x_forwarded: true
</syntaxhighlight>

Postgres-Datenbank:
<syntaxhighlight lang=yaml line>
database:
# The database engine name
name: "psycopg2"
# Arguments to pass to the engine
args:
host: "localhost"
database: "xyz00_matrixdb"
user: "xyz00_matrixuser"
password: "meinPasswort"
cp_min: 5
cp_max: 10
</syntaxhighlight>

== Starten der Dienste ==

Der ''Synapse''-Dienst wird hier als Service-Unit im SystemD des Users eingetragen.

Lege dazu die folgende Datei an: ''~/.config/systemd/user/synapse.service'' mit dem Inhalt:
<syntaxhighlight lang="ini" line>
[Unit]
Description=Synapse

[Service]
Type=simple
WorkingDirectory=%h/synapse
Environment=LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libjemalloc.so.2
ExecStart=pipenv run python -m synapse.app.homeserver --config-path=%h/synapse/homeserver.yaml

[Install]
WantedBy=default.target
</syntaxhighlight>

Durch Aufruf der folgenden Kommandos wird der Dienst aktiviert und gestartet:
<syntaxhighlight lang="shell" lines>
systemctl --user daemon-reload
systemctl --user enable synapse.service
systemctl --user start synapse.service
</syntaxhighlight>
== Einrichten des Apache VHost ==

Die ''~/doms/matrix.beispiel.de/.htaccess'' mit dem Editor der Wahl öffnen und
folgende Konfiguration einfügen:
<syntaxhighlight lang=apache line>
DirectoryIndex disabled
RewriteEngine On
RewriteBase /
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-l
RewriteRule .* http://localhost:32801%{REQUEST_URI} [NE,proxy]
RequestHeader set X-Forwarded-Proto "https"
</syntaxhighlight>
== Well-Known unter beispiel.de ==

Damit die User-Accounts das Format @user:beispiel.de haben, der Server aber unter matrix.beispiel.de erreichbar ist, müssen noch folgende zwei Dateien unter der Domain beispiel.de abgelegt werden:

https://beispiel.de/.well-known/matrix/server
<syntaxhighlight lang=json line>
{
"m.server": "matrix.beispiel.de:443"
}
</syntaxhighlight>

https://beispiel.de/.well-known/matrix/client
<syntaxhighlight lang=json line>
{
"m.homeserver": {
"base_url": "https://matrix.beispiel.de"
},
"m.identity_server": {
"base_url": "https://vector.im"
}
}
</syntaxhighlight>

Für die muss noch der CORS-Header Access-Control-Allow-Origin "*" gesetzt werden, damit die Datei aus beliebigem Riot-Web im Browser abrufbar ist. Dazu in den Ordner .well-known/matrix/ folgende .htaccess anlegen:
<syntaxhighlight lang=apache line>
<IfModule mod_headers.c>
Header set Access-Control-Allow-Origin "*"
</IfModule>
</syntaxhighlight>

Die Dokumentation dazu findet man unter https://matrix.org/docs/spec/server_server/r0.1.2#get-well-known-matrix-server und https://matrix.org/docs/spec/client_server/r0.5.0#get-well-known-matrix-client

== Update von Synapse ==

mit pipenv:
<syntaxhighlight lang=shell>
systemctl --user stop synapse.service
cd ~/synapse
source .venv/bin/activate
release=`curl -L https://api.github.com/repos/element-hq/synapse/releases/latest -s | jq -r '.tag_name'`
wget https://raw.githubusercontent.com/element-hq/synapse/refs/tags/$release/poetry.lock -O poetry.lock
wget https://raw.githubusercontent.com/element-hq/synapse/refs/tags/$release/pyproject.toml -O pyproject.toml
wget https://raw.githubusercontent.com/element-hq/synapse/refs/tags/$release/README.rst -O README.rst
pip install poetry
poetry install
systemctl --user start synapse.service
</syntaxhighlight>

Es ist zu empfehlen, Synapse mit der offiziellen poetry.lock Datei zu aktualisieren, weil es sonst Versionskonflikte geben kann, wenn Abhängigkeiten schon wieder aktualisiert wurden, und nicht mehr kompatibel zum aktuellen Synapse sind.

Wenn die Föderation für den Synapse Server aktiviert ist, kann mit dem [https://federationtester.matrix.org/ Matrix Federation Tester] die eigene Instanz auf die laufende Version geprüft werden. Als Server nicht matrix.example.org eingeben, sondern den öffentlichen Namen, wo auch die Benutzernamen drauf laufen, z.B. example.org

Ansonsten ist die laufende Version auch über die URL https://matrix.example.org/_synapse/admin/v1/server_version zu erfahren.

== Element-Web ==

Element-Web ist aus Server-Seite eine rein statische html+javascript-Kombination, daher:

* Account und Domain anlegen (separat von der Synapse-Domain)
* [https://github.com/element-hq/element-web/releases/latest aktuelles element-web release] .tgz herunterladen
* Symlink von htdocs-ssl auf entpacktes element-web-Verzeichnis
* config.sample.json in config.json kopieren und Matrix-Homeserver-Einträge anpassen
* Piwik aus config.json entfernen

== SAML mit Synapse ==

Synapse unterstützt mit Version 1.1.0 SAML. Dazu wie folgt vorgehen:

Das Paket xmlsec1 muss installiert sein:

<syntaxhighlight lang=shell>
$ xmlsec1 --version
xmlsec1 1.2.23 (openssl)
</syntaxhighlight>

Das Python-Paket pysaml2 installieren

<syntaxhighlight lang=shell>
cd ~/synapse
pipenv shell
pipenv install pysaml2
</syntaxhighlight>

In der homeserver.yaml die SAML-Direktiven einkommentieren, hier mit dem Beispiel eines SAML IdP unter https://login.beispiel.de/simplesaml/saml2/idp/metadata.php:

<syntaxhighlight lang=yaml line>
# Once SAML support is enabled, a metadata file will be exposed at
# https://<server>:<port>/_matrix/saml2/metadata.xml, which you may be able to
# use to configure your SAML IdP with. Alternatively, you can manually configure
# the IdP to use an ACS location of
# https://<server>:<port>/_matrix/saml2/authn_response.
#
saml2_config:
sp_config:
# point this to the IdP's metadata. You can use either a local file or
# (preferably) a URL.
metadata:
#local: ["saml2/idp.xml"]
remote:
- url: https://login.beispiel.de/simplesaml/saml2/idp/metadata.php
</syntaxhighlight>
Wichtig ist außerdem, dass die public_baseurl in der homeserver.yaml gesetzt ist, damit Synapse weiß, wie es erreichbar ist und dies in seine SP-Metadaten einbauen kann:
<syntaxhighlight lang=yaml line>
public_baseurl: https://matrix.beispiel.de/
</syntaxhighlight>
Die Service-Provider-Konfiguration als XML bekommt man von Synapse dann wie schon in der homeserver.yaml als Kommentar beschrieben, unter https://matrix.beispiel.de/_matrix/saml2/metadata.xml

Diese dann in den SAML-IdP-importieren und dann sollte der Single-Sign-On via SAML funktionieren.

== Federation Sender Worker für Synapse ==

Zur Parallelisierung bietet Synapse das Konzept "Worker" an, die spezifische Aufgaben übernehmen, damit der Hauptprozess diese nicht durchführen muss.

Details dazu: https://github.com/matrix-org/synapse/blob/master/docs/workers.md

Ein einfach einzurichtender Worker, der auch viel Last abfedert, ist der Federation Sender Worker, da das Verschicken des Federation-Traffics 10-50% der Serverlast ausmacht.

In der homeserver.yaml die Worker-Konfiguration aktivieren:
<syntaxhighlight lang=yaml line>
## Worker ##
worker_app: synapse.app.homeserver
daemonize: true
</syntaxhighlight>

und dazugehörige Listener (Abschnitt listener:) aktivieren:
<syntaxhighlight lang=yaml line>
# The TCP replication port
- port: 32892
bind_address: '127.0.0.1'
type: replication
# The HTTP replication port
- port: 32893
bind_address: '127.0.0.1'
type: http
resources:
- names: [replication]
</syntaxhighlight>

Funktionen, die Worker machen sollen, in der homeserver.yaml deaktivieren:
<syntaxhighlight lang=yaml line>
# disable federation sending here, use worker for it
send_federation: False
</syntaxhighlight>
Dann Verzeichnis synapse/workers anlegen, darin federation_sender.yaml:
<syntaxhighlight lang=yaml line>
worker_app: synapse.app.federation_sender

# The replication listener on the synapse to talk to.
worker_replication_host: 127.0.0.1
worker_replication_port: 32892
worker_replication_http_port: 32893

worker_daemonize: True
worker_pid_file: /home/pacs/xyz00/users/matrix/synapse/federation_sender.pid
worker_log_config: /home/pacs/xyz00/users/matrix/synapse/federation_sender.log.config
</syntaxhighlight>
.monitrc um worker erweitern:
<syntaxhighlight lang=shell line>
check process federation_sender with pidfile /home/pacs/xyz00/users/matrix/synapse/federation_sender.pid
start program "/bin/bash -c 'export VIRTUAL_ENV=$HOME/synapse/env && export PATH=$VIRTUAL_ENV/bin:$PATH && cd $HOME/synapse && synctl -w workers/federation_sender.yaml start'"
stop program "/bin/bash -c '/bin/kill $( cat $HOME/synapse/federation_sender.pid )'"
</syntaxhighlight>
Monit neu laden und synapse und federation_sender neustarten:

<syntaxhighlight lang=shell>
monit reload
monit restart all
</syntaxhighlight>

Nach Updates ebenfalls immer Hauptprozess und alle Worker neustarten

<syntaxhighlight lang=shell>
monit restart all
</syntaxhighlight>

== Sliding Sync Proxy ==
Zum Zeitpunkt dieser Anleitung werden aktiv neue Element Anwendungen (Element X) und ein neues Syncverfahren entwickelt um Matrix performanter und weniger ressourcenhungrig zu machen. Bei stärkerer Matrix Nutzung können die neuen Anwendungen besonders mobil schon eine große Entlastung sein.

Ende 2024 wurden grundlegende Funktionen direkt in Synapse implementiert. Der Proxy wird nicht länger weiterentwickelt und sollte deinstalliert werden (nicht vergessen die .well-known zurück zu ändern). Auch der 3rdparty Server [[Conduit]] bringt nativ Support für Sliding Sync.

== Links ==

* https://matrix.org/docs/projects/server/synapse
* https://github.com/element-hq/synapse
* https://github.com/element-hq/synapse/blob/master/INSTALL.md
* https://github.com/matrix-org/sliding-sync
* https://matrix.org/docs/spec/
* https://www.hostsharing.net/loesungen/matrix/
* https://codeberg.org/tpokorra/hs.ansible/src/branch/main/playbooks/synapse
* https://codeberg.org/tpokorra/hs.ansible/src/branch/main/playbooks/element

[[Kategorie:Messenger]]
[[Kategorie:Software]]
[[Kategorie:Eigene Daemons]]
[[Kategorie:Installationsanleitungen]]
[[Kategorie:Ansible Playbook]]

Matrix Synapse installieren

2026-01-19T05:41:34Z

Tim00: Update von Synapse mit Poetry

Der Matrix Server ''Synapse'', der sogenannte 'Homeserver', ist aktuell die einzige vollständige serverseitige Implementierung des Matrix-Protokolls.

{{Textkasten|gelb|Work in Progress|Leider funktioniert die Server-zu-Server-Kommunikation von Synapse hinter dem Apache-Proxy mit den genannten Rewrite-Rules nicht. Bitten Sie dazu den Service, Ihren Apache VHost individuell für den Matrix Server anzupassen.}}

Die hier beschriebene Installation benötigt bei Hostsharing die Paket-Option "RAM". Benötigt werden min. 512 MB. Im Managed Webspace ist diese Option kostenpflichtig: https://www.hostsharing.net/angebote/managed-webspace/ gebucht werden muss der RAM auch bei einem Managed-Server.
Wir empfehlen für den Betrieb einen ''Managed Server''.

Diese Anleitung beschreibt, wie man den Matrix-Homeserver Synapse auf der Managed Hosting Plattform von Hostsharing installieren kann. Dabei sind die User-IDs nach dem Schema @user:beispiel.de aufgebaut, der Homeserver an sich ist unter matrix.beispiel.de erreichbar.

== Vorbereitungen ==

Mit Hilfe von HSAdmin werden angelegt:
# Ein User als Service-User mit ''/bin/bash'' als Shell, zum Beispiel Beispiel: ''xyz00-matrix''
# Eine Domain mit ''xyz00-matrix'' als Domain-Administrator, zum Beispiel ''matrix.beispiel.de''
# Einen Postgresql-User ''xyz00_matrixuser'' mit Passwort ''meinPasswort''
# Eine Postgresql-Datenbank ''xyz00_matrixdb'' mit Datenbank-Owner ''xyz00_matrixuser''

Verwendeter IP-Port für den Server-Dienst:
# Synapse: localhost:32801

== Installation von Synapse ==

Installationsanleitung basierend auf https://matrix-org.github.io/synapse/latest/setup/installation.html#installing-as-a-python-module-from-pypi

Als User ''xyz00-matrix" ein Python3 virtualenv erstellen:

<syntaxhighlight lang="shell">
mkdir -p ~/synapse
cd ~/synapse
pipenv install
</syntaxhighlight>

Synapse und Postgres-Dependencies installieren:

<syntaxhighlight lang="shell">
cd ~/synapse
pipenv shell
pipenv install matrix-synapse[postgres]
</syntaxhighlight>

Initiale Konfiguration mit richtigem server-name "beispiel.de" generieren, außerdem im laufenden Betrieb keine Statistiken an Matrix.org senden:

<syntaxhighlight lang="shell">
cd ~/synapse
pipenv run python -m synapse.app.homeserver --server-name beispiel.de --config-path homeserver.yaml --generate-config --report-stats=no
</syntaxhighlight>

== Konfiguration von Synapse ==

In die initial generierte Konfiguration muss noch die Port- und Datenbank-Konfiguration eingetragen werden:

Port: Innerhalb der listener-section den Port 8008 auf 32801 (wie initial definiert) ändern, alles andere beibehalten:

<syntaxhighlight lang=yaml line>
- port: 32801
tls: false
bind_addresses: ['::1', '127.0.0.1']
type: http
x_forwarded: true
</syntaxhighlight>

Postgres-Datenbank:
<syntaxhighlight lang=yaml line>
database:
# The database engine name
name: "psycopg2"
# Arguments to pass to the engine
args:
host: "localhost"
database: "xyz00_matrixdb"
user: "xyz00_matrixuser"
password: "meinPasswort"
cp_min: 5
cp_max: 10
</syntaxhighlight>

== Starten der Dienste ==

Der ''Synapse''-Dienst wird hier als Service-Unit im SystemD des Users eingetragen.

Lege dazu die folgende Datei an: ''~/.config/systemd/user/synapse.service'' mit dem Inhalt:
<syntaxhighlight lang="ini" line>
[Unit]
Description=Synapse

[Service]
Type=simple
WorkingDirectory=%h/synapse
Environment=LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libjemalloc.so.2
ExecStart=pipenv run python -m synapse.app.homeserver --config-path=%h/synapse/homeserver.yaml

[Install]
WantedBy=default.target
</syntaxhighlight>

Durch Aufruf der folgenden Kommandos wird der Dienst aktiviert und gestartet:
<syntaxhighlight lang="shell" lines>
systemctl --user daemon-reload
systemctl --user enable synapse.service
systemctl --user start synapse.service
</syntaxhighlight>
== Einrichten des Apache VHost ==

Die ''~/doms/matrix.beispiel.de/.htaccess'' mit dem Editor der Wahl öffnen und
folgende Konfiguration einfügen:
<syntaxhighlight lang=apache line>
DirectoryIndex disabled
RewriteEngine On
RewriteBase /
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-l
RewriteRule .* http://localhost:32801%{REQUEST_URI} [NE,proxy]
RequestHeader set X-Forwarded-Proto "https"
</syntaxhighlight>
== Well-Known unter beispiel.de ==

Damit die User-Accounts das Format @user:beispiel.de haben, der Server aber unter matrix.beispiel.de erreichbar ist, müssen noch folgende zwei Dateien unter der Domain beispiel.de abgelegt werden:

https://beispiel.de/.well-known/matrix/server
<syntaxhighlight lang=json line>
{
"m.server": "matrix.beispiel.de:443"
}
</syntaxhighlight>

https://beispiel.de/.well-known/matrix/client
<syntaxhighlight lang=json line>
{
"m.homeserver": {
"base_url": "https://matrix.beispiel.de"
},
"m.identity_server": {
"base_url": "https://vector.im"
}
}
</syntaxhighlight>

Für die muss noch der CORS-Header Access-Control-Allow-Origin "*" gesetzt werden, damit die Datei aus beliebigem Riot-Web im Browser abrufbar ist. Dazu in den Ordner .well-known/matrix/ folgende .htaccess anlegen:
<syntaxhighlight lang=apache line>
<IfModule mod_headers.c>
Header set Access-Control-Allow-Origin "*"
</IfModule>
</syntaxhighlight>

Die Dokumentation dazu findet man unter https://matrix.org/docs/spec/server_server/r0.1.2#get-well-known-matrix-server und https://matrix.org/docs/spec/client_server/r0.5.0#get-well-known-matrix-client

== Update von Synapse ==

mit pipenv:
<syntaxhighlight lang=shell>
systemctl --user stop synapse.service
cd ~/synapse
source .venv/bin/activate
release=`curl -L https://api.github.com/repos/element-hq/synapse/releases/latest -s | jq -r '.tag_name'`
wget https://raw.githubusercontent.com/element-hq/synapse/refs/tags/$release/poetry.lock
wget https://raw.githubusercontent.com/element-hq/synapse/refs/tags/$release/pyproject.toml
wget https://raw.githubusercontent.com/element-hq/synapse/refs/tags/$release/README.rst
pip install poetry
poetry install
systemctl --user start synapse.service
</syntaxhighlight>

Es ist zu empfehlen, Synapse mit der offiziellen poetry.lock Datei zu aktualisieren, weil es sonst Versionskonflikte geben kann, wenn Abhängigkeiten schon wieder aktualisiert wurden, und nicht mehr kompatibel zum aktuellen Synapse sind.

Wenn die Föderation für den Synapse Server aktiviert ist, kann mit dem [https://federationtester.matrix.org/ Matrix Federation Tester] die eigene Instanz auf die laufende Version geprüft werden. Als Server nicht matrix.example.org eingeben, sondern den öffentlichen Namen, wo auch die Benutzernamen drauf laufen, z.B. example.org

Ansonsten ist die laufende Version auch über die URL https://matrix.example.org/_synapse/admin/v1/server_version zu erfahren.

== Element-Web ==

Element-Web ist aus Server-Seite eine rein statische html+javascript-Kombination, daher:

* Account und Domain anlegen (separat von der Synapse-Domain)
* [https://github.com/element-hq/element-web/releases/latest aktuelles element-web release] .tgz herunterladen
* Symlink von htdocs-ssl auf entpacktes element-web-Verzeichnis
* config.sample.json in config.json kopieren und Matrix-Homeserver-Einträge anpassen
* Piwik aus config.json entfernen

== SAML mit Synapse ==

Synapse unterstützt mit Version 1.1.0 SAML. Dazu wie folgt vorgehen:

Das Paket xmlsec1 muss installiert sein:

<syntaxhighlight lang=shell>
$ xmlsec1 --version
xmlsec1 1.2.23 (openssl)
</syntaxhighlight>

Das Python-Paket pysaml2 installieren

<syntaxhighlight lang=shell>
cd ~/synapse
pipenv shell
pipenv install pysaml2
</syntaxhighlight>

In der homeserver.yaml die SAML-Direktiven einkommentieren, hier mit dem Beispiel eines SAML IdP unter https://login.beispiel.de/simplesaml/saml2/idp/metadata.php:

<syntaxhighlight lang=yaml line>
# Once SAML support is enabled, a metadata file will be exposed at
# https://<server>:<port>/_matrix/saml2/metadata.xml, which you may be able to
# use to configure your SAML IdP with. Alternatively, you can manually configure
# the IdP to use an ACS location of
# https://<server>:<port>/_matrix/saml2/authn_response.
#
saml2_config:
sp_config:
# point this to the IdP's metadata. You can use either a local file or
# (preferably) a URL.
metadata:
#local: ["saml2/idp.xml"]
remote:
- url: https://login.beispiel.de/simplesaml/saml2/idp/metadata.php
</syntaxhighlight>
Wichtig ist außerdem, dass die public_baseurl in der homeserver.yaml gesetzt ist, damit Synapse weiß, wie es erreichbar ist und dies in seine SP-Metadaten einbauen kann:
<syntaxhighlight lang=yaml line>
public_baseurl: https://matrix.beispiel.de/
</syntaxhighlight>
Die Service-Provider-Konfiguration als XML bekommt man von Synapse dann wie schon in der homeserver.yaml als Kommentar beschrieben, unter https://matrix.beispiel.de/_matrix/saml2/metadata.xml

Diese dann in den SAML-IdP-importieren und dann sollte der Single-Sign-On via SAML funktionieren.

== Federation Sender Worker für Synapse ==

Zur Parallelisierung bietet Synapse das Konzept "Worker" an, die spezifische Aufgaben übernehmen, damit der Hauptprozess diese nicht durchführen muss.

Details dazu: https://github.com/matrix-org/synapse/blob/master/docs/workers.md

Ein einfach einzurichtender Worker, der auch viel Last abfedert, ist der Federation Sender Worker, da das Verschicken des Federation-Traffics 10-50% der Serverlast ausmacht.

In der homeserver.yaml die Worker-Konfiguration aktivieren:
<syntaxhighlight lang=yaml line>
## Worker ##
worker_app: synapse.app.homeserver
daemonize: true
</syntaxhighlight>

und dazugehörige Listener (Abschnitt listener:) aktivieren:
<syntaxhighlight lang=yaml line>
# The TCP replication port
- port: 32892
bind_address: '127.0.0.1'
type: replication
# The HTTP replication port
- port: 32893
bind_address: '127.0.0.1'
type: http
resources:
- names: [replication]
</syntaxhighlight>

Funktionen, die Worker machen sollen, in der homeserver.yaml deaktivieren:
<syntaxhighlight lang=yaml line>
# disable federation sending here, use worker for it
send_federation: False
</syntaxhighlight>
Dann Verzeichnis synapse/workers anlegen, darin federation_sender.yaml:
<syntaxhighlight lang=yaml line>
worker_app: synapse.app.federation_sender

# The replication listener on the synapse to talk to.
worker_replication_host: 127.0.0.1
worker_replication_port: 32892
worker_replication_http_port: 32893

worker_daemonize: True
worker_pid_file: /home/pacs/xyz00/users/matrix/synapse/federation_sender.pid
worker_log_config: /home/pacs/xyz00/users/matrix/synapse/federation_sender.log.config
</syntaxhighlight>
.monitrc um worker erweitern:
<syntaxhighlight lang=shell line>
check process federation_sender with pidfile /home/pacs/xyz00/users/matrix/synapse/federation_sender.pid
start program "/bin/bash -c 'export VIRTUAL_ENV=$HOME/synapse/env && export PATH=$VIRTUAL_ENV/bin:$PATH && cd $HOME/synapse && synctl -w workers/federation_sender.yaml start'"
stop program "/bin/bash -c '/bin/kill $( cat $HOME/synapse/federation_sender.pid )'"
</syntaxhighlight>
Monit neu laden und synapse und federation_sender neustarten:

<syntaxhighlight lang=shell>
monit reload
monit restart all
</syntaxhighlight>

Nach Updates ebenfalls immer Hauptprozess und alle Worker neustarten

<syntaxhighlight lang=shell>
monit restart all
</syntaxhighlight>

== Sliding Sync Proxy ==
Zum Zeitpunkt dieser Anleitung werden aktiv neue Element Anwendungen (Element X) und ein neues Syncverfahren entwickelt um Matrix performanter und weniger ressourcenhungrig zu machen. Bei stärkerer Matrix Nutzung können die neuen Anwendungen besonders mobil schon eine große Entlastung sein.

Ende 2024 wurden grundlegende Funktionen direkt in Synapse implementiert. Der Proxy wird nicht länger weiterentwickelt und sollte deinstalliert werden (nicht vergessen die .well-known zurück zu ändern). Auch der 3rdparty Server [[Conduit]] bringt nativ Support für Sliding Sync.

== Links ==

* https://matrix.org/docs/projects/server/synapse
* https://github.com/element-hq/synapse
* https://github.com/element-hq/synapse/blob/master/INSTALL.md
* https://github.com/matrix-org/sliding-sync
* https://matrix.org/docs/spec/
* https://www.hostsharing.net/loesungen/matrix/
* https://codeberg.org/tpokorra/hs.ansible/src/branch/main/playbooks/synapse
* https://codeberg.org/tpokorra/hs.ansible/src/branch/main/playbooks/element

[[Kategorie:Messenger]]
[[Kategorie:Software]]
[[Kategorie:Eigene Daemons]]
[[Kategorie:Installationsanleitungen]]
[[Kategorie:Ansible Playbook]]

Matrix Synapse installieren

2026-01-19T05:10:20Z

Tim00: /* Update von Synapse */

Der Matrix Server ''Synapse'', der sogenannte 'Homeserver', ist aktuell die einzige vollständige serverseitige Implementierung des Matrix-Protokolls.

{{Textkasten|gelb|Work in Progress|Leider funktioniert die Server-zu-Server-Kommunikation von Synapse hinter dem Apache-Proxy mit den genannten Rewrite-Rules nicht. Bitten Sie dazu den Service, Ihren Apache VHost individuell für den Matrix Server anzupassen.}}

Die hier beschriebene Installation benötigt bei Hostsharing die Paket-Option "RAM". Benötigt werden min. 512 MB. Im Managed Webspace ist diese Option kostenpflichtig: https://www.hostsharing.net/angebote/managed-webspace/ gebucht werden muss der RAM auch bei einem Managed-Server.
Wir empfehlen für den Betrieb einen ''Managed Server''.

Diese Anleitung beschreibt, wie man den Matrix-Homeserver Synapse auf der Managed Hosting Plattform von Hostsharing installieren kann. Dabei sind die User-IDs nach dem Schema @user:beispiel.de aufgebaut, der Homeserver an sich ist unter matrix.beispiel.de erreichbar.

== Vorbereitungen ==

Mit Hilfe von HSAdmin werden angelegt:
# Ein User als Service-User mit ''/bin/bash'' als Shell, zum Beispiel Beispiel: ''xyz00-matrix''
# Eine Domain mit ''xyz00-matrix'' als Domain-Administrator, zum Beispiel ''matrix.beispiel.de''
# Einen Postgresql-User ''xyz00_matrixuser'' mit Passwort ''meinPasswort''
# Eine Postgresql-Datenbank ''xyz00_matrixdb'' mit Datenbank-Owner ''xyz00_matrixuser''

Verwendeter IP-Port für den Server-Dienst:
# Synapse: localhost:32801

== Installation von Synapse ==

Installationsanleitung basierend auf https://matrix-org.github.io/synapse/latest/setup/installation.html#installing-as-a-python-module-from-pypi

Als User ''xyz00-matrix" ein Python3 virtualenv erstellen:

<syntaxhighlight lang="shell">
mkdir -p ~/synapse
cd ~/synapse
pipenv install
</syntaxhighlight>

Synapse und Postgres-Dependencies installieren:

<syntaxhighlight lang="shell">
cd ~/synapse
pipenv shell
pipenv install matrix-synapse[postgres]
</syntaxhighlight>

Initiale Konfiguration mit richtigem server-name "beispiel.de" generieren, außerdem im laufenden Betrieb keine Statistiken an Matrix.org senden:

<syntaxhighlight lang="shell">
cd ~/synapse
pipenv run python -m synapse.app.homeserver --server-name beispiel.de --config-path homeserver.yaml --generate-config --report-stats=no
</syntaxhighlight>

== Konfiguration von Synapse ==

In die initial generierte Konfiguration muss noch die Port- und Datenbank-Konfiguration eingetragen werden:

Port: Innerhalb der listener-section den Port 8008 auf 32801 (wie initial definiert) ändern, alles andere beibehalten:

<syntaxhighlight lang=yaml line>
- port: 32801
tls: false
bind_addresses: ['::1', '127.0.0.1']
type: http
x_forwarded: true
</syntaxhighlight>

Postgres-Datenbank:
<syntaxhighlight lang=yaml line>
database:
# The database engine name
name: "psycopg2"
# Arguments to pass to the engine
args:
host: "localhost"
database: "xyz00_matrixdb"
user: "xyz00_matrixuser"
password: "meinPasswort"
cp_min: 5
cp_max: 10
</syntaxhighlight>

== Starten der Dienste ==

Der ''Synapse''-Dienst wird hier als Service-Unit im SystemD des Users eingetragen.

Lege dazu die folgende Datei an: ''~/.config/systemd/user/synapse.service'' mit dem Inhalt:
<syntaxhighlight lang="ini" line>
[Unit]
Description=Synapse

[Service]
Type=simple
WorkingDirectory=%h/synapse
Environment=LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libjemalloc.so.2
ExecStart=pipenv run python -m synapse.app.homeserver --config-path=%h/synapse/homeserver.yaml

[Install]
WantedBy=default.target
</syntaxhighlight>

Durch Aufruf der folgenden Kommandos wird der Dienst aktiviert und gestartet:
<syntaxhighlight lang="shell" lines>
systemctl --user daemon-reload
systemctl --user enable synapse.service
systemctl --user start synapse.service
</syntaxhighlight>
== Einrichten des Apache VHost ==

Die ''~/doms/matrix.beispiel.de/.htaccess'' mit dem Editor der Wahl öffnen und
folgende Konfiguration einfügen:
<syntaxhighlight lang=apache line>
DirectoryIndex disabled
RewriteEngine On
RewriteBase /
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-l
RewriteRule .* http://localhost:32801%{REQUEST_URI} [NE,proxy]
RequestHeader set X-Forwarded-Proto "https"
</syntaxhighlight>
== Well-Known unter beispiel.de ==

Damit die User-Accounts das Format @user:beispiel.de haben, der Server aber unter matrix.beispiel.de erreichbar ist, müssen noch folgende zwei Dateien unter der Domain beispiel.de abgelegt werden:

https://beispiel.de/.well-known/matrix/server
<syntaxhighlight lang=json line>
{
"m.server": "matrix.beispiel.de:443"
}
</syntaxhighlight>

https://beispiel.de/.well-known/matrix/client
<syntaxhighlight lang=json line>
{
"m.homeserver": {
"base_url": "https://matrix.beispiel.de"
},
"m.identity_server": {
"base_url": "https://vector.im"
}
}
</syntaxhighlight>

Für die muss noch der CORS-Header Access-Control-Allow-Origin "*" gesetzt werden, damit die Datei aus beliebigem Riot-Web im Browser abrufbar ist. Dazu in den Ordner .well-known/matrix/ folgende .htaccess anlegen:
<syntaxhighlight lang=apache line>
<IfModule mod_headers.c>
Header set Access-Control-Allow-Origin "*"
</IfModule>
</syntaxhighlight>

Die Dokumentation dazu findet man unter https://matrix.org/docs/spec/server_server/r0.1.2#get-well-known-matrix-server und https://matrix.org/docs/spec/client_server/r0.5.0#get-well-known-matrix-client

== Update von Synapse ==

mit pipenv:
<syntaxhighlight lang=shell>
systemctl --user stop synapse.service
cd ~/synapse
source .venv/bin/activate || pipenv shell
pipenv update --outdated
pipenv update
systemctl --user start synapse.service
</syntaxhighlight>

oder falls Synapse mit pip verwaltet wird:

<syntaxhighlight lang=shell>
systemctl --user stop synapse.service
cd ~/synapse
source venv/bin/activate
pip freeze > requirements.txt
sed -i "s/==.*//g" requirements.txt
pip install -r requirements.txt --upgrade
systemctl --user start synapse.service
</syntaxhighlight>
Falls Monit verwendet wird statt systemctl:

<syntaxhighlight lang=shell>
monit stop synapse
#... updaten ...
monit start synapse
</syntaxhighlight>

Wenn die Föderation für den Synapse Server aktiviert ist, kann mit dem [https://federationtester.matrix.org/ Matrix Federation Tester] die eigene Instanz auf die laufende Version geprüft werden. Als Server nicht matrix.example.org eingeben, sondern den öffentlichen Namen, wo auch die Benutzernamen drauf laufen, z.B. example.org

Ansonsten ist die laufende Version auch über die URL https://matrix.example.org/_synapse/admin/v1/server_version zu erfahren.

== Element-Web ==

Element-Web ist aus Server-Seite eine rein statische html+javascript-Kombination, daher:

* Account und Domain anlegen (separat von der Synapse-Domain)
* [https://github.com/element-hq/element-web/releases/latest aktuelles element-web release] .tgz herunterladen
* Symlink von htdocs-ssl auf entpacktes element-web-Verzeichnis
* config.sample.json in config.json kopieren und Matrix-Homeserver-Einträge anpassen
* Piwik aus config.json entfernen

== SAML mit Synapse ==

Synapse unterstützt mit Version 1.1.0 SAML. Dazu wie folgt vorgehen:

Das Paket xmlsec1 muss installiert sein:

<syntaxhighlight lang=shell>
$ xmlsec1 --version
xmlsec1 1.2.23 (openssl)
</syntaxhighlight>

Das Python-Paket pysaml2 installieren

<syntaxhighlight lang=shell>
cd ~/synapse
pipenv shell
pipenv install pysaml2
</syntaxhighlight>

In der homeserver.yaml die SAML-Direktiven einkommentieren, hier mit dem Beispiel eines SAML IdP unter https://login.beispiel.de/simplesaml/saml2/idp/metadata.php:

<syntaxhighlight lang=yaml line>
# Once SAML support is enabled, a metadata file will be exposed at
# https://<server>:<port>/_matrix/saml2/metadata.xml, which you may be able to
# use to configure your SAML IdP with. Alternatively, you can manually configure
# the IdP to use an ACS location of
# https://<server>:<port>/_matrix/saml2/authn_response.
#
saml2_config:
sp_config:
# point this to the IdP's metadata. You can use either a local file or
# (preferably) a URL.
metadata:
#local: ["saml2/idp.xml"]
remote:
- url: https://login.beispiel.de/simplesaml/saml2/idp/metadata.php
</syntaxhighlight>
Wichtig ist außerdem, dass die public_baseurl in der homeserver.yaml gesetzt ist, damit Synapse weiß, wie es erreichbar ist und dies in seine SP-Metadaten einbauen kann:
<syntaxhighlight lang=yaml line>
public_baseurl: https://matrix.beispiel.de/
</syntaxhighlight>
Die Service-Provider-Konfiguration als XML bekommt man von Synapse dann wie schon in der homeserver.yaml als Kommentar beschrieben, unter https://matrix.beispiel.de/_matrix/saml2/metadata.xml

Diese dann in den SAML-IdP-importieren und dann sollte der Single-Sign-On via SAML funktionieren.

== Federation Sender Worker für Synapse ==

Zur Parallelisierung bietet Synapse das Konzept "Worker" an, die spezifische Aufgaben übernehmen, damit der Hauptprozess diese nicht durchführen muss.

Details dazu: https://github.com/matrix-org/synapse/blob/master/docs/workers.md

Ein einfach einzurichtender Worker, der auch viel Last abfedert, ist der Federation Sender Worker, da das Verschicken des Federation-Traffics 10-50% der Serverlast ausmacht.

In der homeserver.yaml die Worker-Konfiguration aktivieren:
<syntaxhighlight lang=yaml line>
## Worker ##
worker_app: synapse.app.homeserver
daemonize: true
</syntaxhighlight>

und dazugehörige Listener (Abschnitt listener:) aktivieren:
<syntaxhighlight lang=yaml line>
# The TCP replication port
- port: 32892
bind_address: '127.0.0.1'
type: replication
# The HTTP replication port
- port: 32893
bind_address: '127.0.0.1'
type: http
resources:
- names: [replication]
</syntaxhighlight>

Funktionen, die Worker machen sollen, in der homeserver.yaml deaktivieren:
<syntaxhighlight lang=yaml line>
# disable federation sending here, use worker for it
send_federation: False
</syntaxhighlight>
Dann Verzeichnis synapse/workers anlegen, darin federation_sender.yaml:
<syntaxhighlight lang=yaml line>
worker_app: synapse.app.federation_sender

# The replication listener on the synapse to talk to.
worker_replication_host: 127.0.0.1
worker_replication_port: 32892
worker_replication_http_port: 32893

worker_daemonize: True
worker_pid_file: /home/pacs/xyz00/users/matrix/synapse/federation_sender.pid
worker_log_config: /home/pacs/xyz00/users/matrix/synapse/federation_sender.log.config
</syntaxhighlight>
.monitrc um worker erweitern:
<syntaxhighlight lang=shell line>
check process federation_sender with pidfile /home/pacs/xyz00/users/matrix/synapse/federation_sender.pid
start program "/bin/bash -c 'export VIRTUAL_ENV=$HOME/synapse/env && export PATH=$VIRTUAL_ENV/bin:$PATH && cd $HOME/synapse && synctl -w workers/federation_sender.yaml start'"
stop program "/bin/bash -c '/bin/kill $( cat $HOME/synapse/federation_sender.pid )'"
</syntaxhighlight>
Monit neu laden und synapse und federation_sender neustarten:

<syntaxhighlight lang=shell>
monit reload
monit restart all
</syntaxhighlight>

Nach Updates ebenfalls immer Hauptprozess und alle Worker neustarten

<syntaxhighlight lang=shell>
monit restart all
</syntaxhighlight>

== Sliding Sync Proxy ==
Zum Zeitpunkt dieser Anleitung werden aktiv neue Element Anwendungen (Element X) und ein neues Syncverfahren entwickelt um Matrix performanter und weniger ressourcenhungrig zu machen. Bei stärkerer Matrix Nutzung können die neuen Anwendungen besonders mobil schon eine große Entlastung sein.

Ende 2024 wurden grundlegende Funktionen direkt in Synapse implementiert. Der Proxy wird nicht länger weiterentwickelt und sollte deinstalliert werden (nicht vergessen die .well-known zurück zu ändern). Auch der 3rdparty Server [[Conduit]] bringt nativ Support für Sliding Sync.

== Links ==

* https://matrix.org/docs/projects/server/synapse
* https://github.com/element-hq/synapse
* https://github.com/element-hq/synapse/blob/master/INSTALL.md
* https://github.com/matrix-org/sliding-sync
* https://matrix.org/docs/spec/
* https://www.hostsharing.net/loesungen/matrix/
* https://codeberg.org/tpokorra/hs.ansible/src/branch/main/playbooks/synapse
* https://codeberg.org/tpokorra/hs.ansible/src/branch/main/playbooks/element

[[Kategorie:Messenger]]
[[Kategorie:Software]]
[[Kategorie:Eigene Daemons]]
[[Kategorie:Installationsanleitungen]]
[[Kategorie:Ansible Playbook]]

Discourse installieren

2026-01-16T07:29:49Z

Tim00: /* Am Beispiel von 3.4.7 auf 3.5.1 */

{{Textkasten|gelb|Für Managed Server|Ein funktionierender Discourse-Server erfordert mehrere laufende Server-Dienste. Für den Betrieb ist ein Managed Server sinnvoll.}}

{{Textkasten|rot|Support von der Discourse-Community|Die Discourse-Entwickler haben sich entschieden, nur eine mehr oder weniger genormte Installationsmethode (via docker) zu unterstützen. Dies ist so auf der hostsharing-Architektur aufgrund mehrerer Bedenken und Überlegungen nicht möglich. Die Community ist durchaus hilfreich, geht aber davon aus, dass quasi alle Nutzer* eine "supported"e Installation durchgeführt haben. Wenn man in entsprechenden Kanälen nach Hilfe fragt, sollte man unbedingt erwähnen, dass man discourse selber anhand dieser hier lesbaren Anleitung installiert hat, um bereits entsprechenden Kommentaren und Nachfragen vorzugreifen.}}

== Über ==

In diesem Artikel wird die Installation von discourse, Version 2.1.0 (September 2018) beschrieben.

== Vorbereitungen ==

Mit Hilfe von HSAdmin wird angelegt:
# Ein User als Service-User mit ''/bin/bash'' als Shell, zum Beispiel Beispiel: ''xyz00-discourse''
# Eine Domain mit ''xyz00-discourse' als Domain-Administrator, zum Beispiel ''beispiel.discussion''
# Einen Postgresql-User ''xyz00_discourseuser'' mit Passwort ''meinPasswort''
# Eine Postgresql-Datenbank ''xyz00_discoursedb'' mit Datenbank-Owner ''xyz00_discourseuser''

Verwendete IP-Ports der Server-Dienste:
# Redis: localhost:32002
# Discourse-Web: localhost:13000

== Konfiguration der PostgreSQL Datenbank ==

Es müssen noch Erweiterungen für Postgresql installiert werden:

<syntaxhighlight lang=shell line>
psql --user xyz00_discourseuser -c "CREATE EXTENSION IF NOT EXISTS hstore WITH SCHEMA public;"
psql --user xyz00_discourseuser -c "CREATE EXTENSION IF NOT EXISTS pg_trgm WITH SCHEMA public;"
psql --user xyz00_discourseuser -c "CREATE EXTENSION IF NOT EXISTS unaccent WITH SCHEMA public;"
</syntaxhighlight>

== Konfiguration des Redis Server ==

{{Textkasten|gelb|Firewall/Redis Port|Leider unterstützt discourse nicht die Kommunikation mit Redis über Unix-Sockets. Dementsprechend muss der für Redis konfigurierte Port von dem hostsharing-Support in der Firewall freigegeben werden.}}

<syntaxhighlight lang=shell>
cd
mkdir redis/etc redis/lib redis/log redis/run
</syntaxhighlight>

Anlegen einer Datei ''/home/pacs/xyz00/users/discourse/redis/etc/redis.conf'' mit folgendem Inhalt:

<syntaxhighlight lang=shell line>
daemonize no
pidfile /home/pacs/xyz00/users/discourse/redis/run/redis-server.pid
port 32002
tcp-backlog 128
bind 127.0.0.1
timeout 300
loglevel notice
logfile /home/pacs/xyz00/users/discourse/redis/log/redis.log
databases 16
save 900 1
save 300 10
save 60 10000
slave-serve-stale-data yes
appendonly no
dbfilename dump.rdb
dir /home/pacs/xyz00/users/discourse/redis/lib
</syntaxhighlight>

Für Discourse 3.x gilt: "Discourse requires Redis 6.2.0 or up"

Für Debian Buster und Bullseye ist daher das Installieren eines neueren Binaries erforderlich. Bei Debian Bookwork ist bereits Redis 7.0 enthalten (siehe https://packages.debian.org/search?keywords=redis-server).

Hier steht ein entsprechendes Binary für Debian Buster zur Verfügung, das mit dem Public Key von Timotheus geprüft werden kann:

* https://download.solidcharity.com/tarballs/tpokorra/hostsharing/redis-server-6.2.12-debian-buster.tar.gz
* Prüfsignatur: https://download.solidcharity.com/tarballs/tpokorra/hostsharing/redis-server-6.2.12-debian-buster.tar.gz.sig

Prüfen der Signatur:

<syntaxhighlight lang=shell>
gpg --verify redis-server-6.2.12-debian-buster.tar.gz.sig redis-server-6.2.12-debian-buster.tar.gz
</syntaxhighlight>

Das Binary muss nach <code>$HOME/bin</code> verschoben werden, und entsprechend beim Starten des Dienstes eingetragen werden.

== Installation von Ruby ==

Als User ''xyz00-discourse'': Installation von Ruby mit ''rbenv'' mit folgenden Befehlen:

Zunächst ''rbenv'' and ''ruby-build'':

<syntaxhighlight lang=shell line>
git clone https://github.com/rbenv/rbenv.git ~/.rbenv
cd ~/.rbenv && src/configure && make -C src
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.profile
echo 'eval "$(rbenv init -)"' >> ~/.profile
</syntaxhighlight>

starte neue Shell:

<syntaxhighlight lang=shell>
exec bash
</syntaxhighlight>

Überprüfe rbenv-Installation

<syntaxhighlight lang=shell>
type rbenv
</syntaxhighlight>

Installiere ruby-build als rbenv-Plugin

<syntaxhighlight lang=shell>
git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build
</syntaxhighlight>

Nun kann die benötigte Ruby-Version installiert werden:

<syntaxhighlight lang=shell>
rbenv install 2.4
</syntaxhighlight>

== Installation von Discourse selber ==

Weiterhin Als User ''xyz00-discourse'':

<syntaxhighlight lang=shell>
cd ~
git clone https://github.com/discourse/discourse.git discourse
cd ~/discourse
</syntaxhighlight>

Die stabile Version auschecken:

<syntaxhighlight lang=shell>
git checkout stable
</syntaxhighlight>

Ruby Pakete installieren:

<syntaxhighlight lang=shell>
gem install bundler
bundle install -j$(getconf _NPROCESSORS_ONLN) --deployment --without development test
</syntaxhighlight>

== Konfiguration der Discourse Software ==

Anlegen einer Datei ''/home/pacs/xyz00/users/discourse/discourse/config/discourse.conf'' anhand der Beispiel-Datei:

<syntaxhighlight lang=shell>
cd ~/discourse
cp config/discourse_defaults.conf config/discourse.conf
</syntaxhighlight>

Anpassen folgender Inhalte:
<syntaxhighlight lang=ini line>
db_host = 127.0.0.1
db_port = 5432
#db_backup_port = 5432 #(auskommentieren)
db_name = xyz00_discoursedb
db_username = xyz00_discourseuser
db_password = "" #db password
hostname = "discourse.xyz00" # hostname
smtp_address = localhost
smtp_enable_start_tls = false
smtp_openssl_verify_mode = 'none'
developer_emails = # your email-address
redis_host = 127.0.0.1
redis_port = 32002
</syntaxhighlight>
===TODO: Secrets setzen! ===
Die Zufallswerte für die Variablen SECRET_KEY_BASE und OTP_SECRET erzeugt man durch zwei Aufrufe des Kommandos

<syntaxhighlight lang=shell>
RAILS_ENV=production bundle exec rake secret
</syntaxhighlight>

=== Sidekiq für Hintergrund-Aufgaben konfigurieren ===

''config/sidekiq.conf''

Wichtig: development auf production ändern.

Mit diesem Dienst werden z.B. die E-Mails zur Aktivierung oder zum Passwort Reset verschickt.

=== Problem mit Content Security Policy ===

Um ein Problem mit Content Security Policy zu lösen, weil manche Dateien über http nachgeladen werden, muss in der Datei <code>config/site_settings.yml</code> der Default Wert für force_https auf True gesetzt werden:
<syntaxhighlight lang=yaml line>
force_https:
default: true
</syntaxhighlight>
=== Problem beim Aufsetzen der Datenbank vermeiden ===

'''→ Notiz Mai 2024:''' dies scheint aktuell nicht aufzutreten.

Aus irgendeinem Grund wird beim Initialisieren der Datenbank versucht, den TYPE hotlinked_media_status zweimal in der Datenbank anzulegen. Der Grund ist nicht ersichtlich.

Es kann folgende Änderung an der Datei <code>db/migrate/20220428094026_create_post_hotlinked_media.rb</code> vorgenommen werden:
<syntaxhighlight lang=ruby line>
reversible do |dir|
dir.up { execute <<~SQL }
DO $$ BEGIN CREATE TYPE hotlinked_media_status AS ENUM('downloaded', 'too_large', 'download_failed', 'upload_create_failed'); EXCEPTION WHEN duplicate_object THEN null; END $$;
SQL
dir.down { execute <<~SQL }
DROP TYPE hotlinked_media_status
SQL
end
</syntaxhighlight>
=== Initialisieren der Datenbank ===

<syntaxhighlight lang=shell>
export SAFETY_ASSURED=1
# In Version 2.0.4 funktioniert db:migrate noch, ansonsten db:schema:load und seed nutzen!
# In Version 3.0.3 funktioniert db:migrate auch noch, db:schema:load ging nicht weil die Datei structure.sql fehlte
#RAILS_ENV=production bundle exec rails db:schema:load
#RAILS_ENV=production bundle exec rails db:seed
RAILS_ENV=production bundle exec rails db:migrate
</syntaxhighlight>

=== Kompilieren der Assets ===

<syntaxhighlight lang=shell>
RAILS_ENV=production bundle exec rails assets:precompile
</syntaxhighlight>

=== Konfiguration des Web-Servers (am Beispiel Puma) ===

Die Datei ''config/puma.conf'' anpassen (hier nur Änderungen angezeigt):

<syntaxhighlight lang=ini>
APP_ROOT = '/home/pacs/xyz00/users/discourse/discourse'
daemonize false
</syntaxhighlight>

== Starten der Dienste ==

Zum Start aller notwendigen Dienste sollte systemd benutzt werden.

Die folgenden Dateien müssen nach <code>.config/systemd/user/</code> kopiert werden (überlange Zeilen werden hier im Wiki umgebrochen)

redis.service:

<syntaxhighlight lang=ini line>
[Unit]
Description=Redis User Service

[Service]
WorkingDirectory=%h/var/redis
Environment="PATH=/usr/local/bin:/usr/bin:/bin"
ExecStart=%h/bin/redis-server %h/etc/redis.conf
Restart=always
PrivateTmp=true
NoNewPrivileges=true

[Install]
WantedBy=default.target
</syntaxhighlight>

sidekiq.service:

<syntaxhighlight lang=ini line>
[Unit]
Description=Discourse Sidekiq Service

[Service]
WorkingDirectory=%h/discourse
Environment="PATH=/usr/local/bin:/usr/bin:/bin"
Environment="RAILS_ENV=production"
Environment="DB_POOL=8"
Environment="MALLOC_ARENA_MAX=2"
ExecStart=%h/.rbenv/shims/bundle exec sidekiq -C %h/discourse/config/sidekiq.yml
StandardOutput=append:%h/var/log/sidekiq.out.log
StandardError=inherit
Restart=always
PrivateTmp=true
NoNewPrivileges=true

[Install]
WantedBy=default.target
After=redis.service
</syntaxhighlight>

discourse.service:

<syntaxhighlight lang=ini line>
[Unit]
Description=Discourse Web Service

[Service]
WorkingDirectory=%h/discourse
Environment="PATH=/usr/local/bin:/usr/bin:/bin"
Environment="RAILS_ENV=production"
Environment="WEB_CONCURRENCY=2"
Environment="MAX_THREADS=5"
Environment="MALLOC_ARENA_MAX=2"
ExecStart=%h/.rbenv/shims/bundle exec puma -C config/puma.rb -e production -b tcp://127.0.0.1:13000
StandardOutput=append:%h/var/log/puma.out.log
StandardError=inherit
Restart=always
PrivateTmp=true
NoNewPrivileges=true

[Install]
WantedBy=default.target
After=redis.service
</syntaxhighlight>

== Einrichten des Apache VHost ==

<syntaxhighlight lang=shell>
cd ~/doms/beispiel.discuss
rm -rf htdocs-ssl subs/www subs-ssl/www
ln -s ~/live/public htdocs-ssl
touch htdocs-ssl/.htaccess
</syntaxhighlight>

Dann die ''htdocs-ssl/.htaccess'' (durch das gelinkte Verzeichnis entspricht das dem Pfad /home/pacs/xyz00/users/discourse/discourse/public/.htaccess ) mit dem Editor der Wahl öffnen und folgende Konfiguration einfügen:

<syntaxhighlight lang=apache line>
DirectoryIndex disabled

RequestHeader set X-Forwarded-Proto "https"

RewriteEngine On
RewriteBase /
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-l
RewriteRule .* http://127.0.0.1:13000%{REQUEST_URI} [proxy,last]
</syntaxhighlight>
== Wartung ==
=== Backup ===

Discourse macht selbstätig backups und legt diese unter 'public/backups' ab. Enthalten ist ein Datenbank-Dump und die hochgeladenen Dateien.

Im Admin-Bereich lassen sich backups auch manuell antreten.

=== Admin Benutzer einladen ===

Manchmal brauchen wir einen neuen Admin Benutzer, den wir von der Kommandozeile aus einladen möchten.

<syntaxhighlight lang=shell>
cd /discourse
RAILS_ENV=production rake admin:invite[admin@example.org]
</syntaxhighlight>

=== Import aus mbox Archiven ===

Um zum Beispiel ein Mailman2 Archiv zu importieren, wo die Nachrichten als .mbox Datei vorliegen, sind folgende Schritte nötig:

Vorbereitungen an Discourse:

<syntaxhighlight lang=shell>
source .profile
cd discourse
bundle config set frozen false
IMPORT=1 bundle install
bundle config set frozen true
nano script/import_scripts/mbox/settings.yml
# dort ändern:
# data_dir: /home/pacs/xyz00/users/discourse/list-archiv
</syntaxhighlight>

Hochladen der Mailinglisten-Archive:
<syntaxhighlight lang=shell>
mkdir ~/list-archiv
# dort muss es Unterordner mit dem Namen der gewünschten Kategorie geben,
# und die mbox Datei muss auch diesen Namen haben, z.B.:
# ~/list-archiv/beispiel/beispiel.mbox
# ~/list-archiv/example/example.mbox
# um die Beiträge in den entsprechenden Kategorien beispiel und example einzufügen.
</syntaxhighlight>

Durchführen des Imports:
<syntaxhighlight lang=shell>
source .profile
cd discourse
RAILS_ENV=production IMPORT=1 bundle exec rails runner \
script/import_scripts/mbox.rb script/import_scripts/mbox/settings.yml
</syntaxhighlight>

=== Export ===
* Wenn ein Forum beendet wird, möchte man evtl. eine Sicherung als statische HTML Seiten.
** Das wird hier diskutiert: https://meta.discourse.org/t/how-do-i-export-the-complete-forum-as-static-html-pages/71007/3
* Um ein Forum von Discourse zu Flarum umzuziehen, hat Timotheus ein Skript geschrieben.
** Das Migrations-Skript: https://github.com/SolidCharity/discourse_to_flarum
** siehe auch https://discuss.flarum.org/d/4930-discourse-to-flarum-migration-support/29

=== Updates ===

Discourse wird über update via mail informieren (dies kann man m.W. abschalten).

Achtung: bei größeren Updates auch immer Änderungen an der Datei site_settings.yml (https://github.com/discourse/discourse/blob/main/config/site_settings.yml) beachten!

Siehe auch die unterstützten Releases: https://releases.discourse.org/ und die Tags: https://github.com/discourse/discourse/tags

==== Am Beispiel von 3.4.7 auf 3.5.1 ====

# Im Web-Backend unter Administration->Backups-> Read-Only Mouds setzen (oder Web Server so konfigurieren, dass keine Zugriffe mehr stattfinden können)
# Backup
# Die lokalen Änderungen sichern:
# cd discourse
# mv ~/plugins.bak/discourse-ai plugins
# git diff v3.4.7 > diff-3.4.7.txt
# git fetch
# git checkout -b hostsharing-deployment-v3.5.1 v3.5.1
# evtl. Änderungen aus diff-3.4.7.txt wieder übernehmen und committen
# patch -p1 < diff-3.4.7.txt
# git commit -a -m "spezifische Änderungen für diese Instanz" --no-verify
# Schauen, ob discourse eine neue Ruby-Version nutzt (z.B. in https://github.com/discourse/discourse_docker/blob/main/image/base/Dockerfile)
# Dies ist der Fall, also
# rbenv install 3.3.8
# rbenv global 3.3.8
# rbenv rehash
# echo "3.3.8" > .ruby-version
# installiere Node 22: https://codeberg.org/tpokorra/hostsharing-scripts/src/branch/main/install-nodejs.sh
# source ~/.profile
# gem update --system
# bundle install
# npm install -g terser uglify-js pnpm@9
# corepack use pnpm@latest-9
# pnpm install
# export $(grep -v '^#' ~/discourse.env | xargs -d '\n')
# source ~/.profile
# wir haben keine pg extension pg_vector, daher deaktivieren wir das Plugin während migrate, aber auch für später damit /admin/settings funktioniert:
# mkdir -p ~/plugins.bak
# mv plugins/discourse-ai ~/plugins.bak
# RAILS_ENV=production bundle exec rake db:migrate
# RAILS_ENV=production bundle exec rake assets:precompile
# Services neu starten
<syntaxhighlight lang=shell>
systemctl --user restart puma
systemctl --user restart sidekiq
systemctl --user restart redis
</syntaxhighlight>
* Zuletzt: Read-Only Modus wieder deaktivieren

=== Debugging ===

Es können folgende Einstellungen in der Datei config/environments/production.rb vorgenommen werden. Danach den Puma Dienst neustarten. Fehlermeldungen und Stacktraces werden dann im Browser ausgegeben.

<syntaxhighlight lang="ini" line>
config.log_level = :debug
config.action_dispatch.show_exceptions = :all
config.action_dispatch.debug_exception_log_level = :error

# Full error reports are enabled and caching is turned off
config.consider_all_requests_local = true
config.action_controller.perform_caching = false
</syntaxhighlight>

=== Erforderliche Anpassungen ===
Weil wir bei Debian Bookworm noch mit ImageMagick 6.9 arbeiten, muss dieser [https://github.com/discourse/discourse/commit/17aa831337e352dfd875f1b4ddc4492bd0835119 Patch] rückgängig gemacht werden:

<syntaxhighlight lang="bash" line>
wget https://github.com/discourse/discourse/commit/17aa831337e352dfd875f1b4ddc4492bd0835119.patch -O ~/imagemagick.patch
patch -p1 --reverse < ~/imagemagick.patch
git commit -a -m "revert imagemagick patch" --no-verify
</syntaxhighlight>

== ToDos ==

* Ein Patch, um Discourse auch via Unix-Socket mit Redis sprechen lassen zu können dürfte relativ einfach sein (es wird ein Wrapper um das redis-gem genutzt).
* Konfiguration von discourse, um mit postgresql via Unix-Socket zu kommunizieren (DISCOURSE_DB_SOCKET environment variable)
* Performance-tuning an diversen Stellen, anhand der discourse_docker-Vorgaben (https://github.com/discourse/discourse_docker), z.B.
** thpoff (huge page settings)
** unicorn (hat eine wesentlich ausgefeiltere Konfigurations-Vorlage, wahrscheinlich bereits ordentlich optimiert)

== Links ==

* https://help.skysilk.com/support/solutions/articles/9000120927-how-to-install-discourse-without-docker-using-skysilk-vps-
* https://github.com/discourse/discourse_docker
* https://github.com/discourse/discourse
* https://codeberg.org/tpokorra/hs.ansible/src/branch/main/playbooks/discourse

== Historie ==

* 2018, 14 . September: Initiale Fassung
* 2019, Januar: Update-Informationen ergänzt
* 2022, Juni: systemd Dienste, Discourse 3.0

----
[[Kategorie:HSDoku]]
[[Kategorie:Installationsanleitungen]]
[[Kategorie:RubyOnRails]]
[[Kategorie:Webforen]]
[[Kategorie:Ansible Playbook]]

Discourse installieren

2026-01-16T07:27:09Z

Tim00: /* Updates */

{{Textkasten|gelb|Für Managed Server|Ein funktionierender Discourse-Server erfordert mehrere laufende Server-Dienste. Für den Betrieb ist ein Managed Server sinnvoll.}}

{{Textkasten|rot|Support von der Discourse-Community|Die Discourse-Entwickler haben sich entschieden, nur eine mehr oder weniger genormte Installationsmethode (via docker) zu unterstützen. Dies ist so auf der hostsharing-Architektur aufgrund mehrerer Bedenken und Überlegungen nicht möglich. Die Community ist durchaus hilfreich, geht aber davon aus, dass quasi alle Nutzer* eine "supported"e Installation durchgeführt haben. Wenn man in entsprechenden Kanälen nach Hilfe fragt, sollte man unbedingt erwähnen, dass man discourse selber anhand dieser hier lesbaren Anleitung installiert hat, um bereits entsprechenden Kommentaren und Nachfragen vorzugreifen.}}

== Über ==

In diesem Artikel wird die Installation von discourse, Version 2.1.0 (September 2018) beschrieben.

== Vorbereitungen ==

Mit Hilfe von HSAdmin wird angelegt:
# Ein User als Service-User mit ''/bin/bash'' als Shell, zum Beispiel Beispiel: ''xyz00-discourse''
# Eine Domain mit ''xyz00-discourse' als Domain-Administrator, zum Beispiel ''beispiel.discussion''
# Einen Postgresql-User ''xyz00_discourseuser'' mit Passwort ''meinPasswort''
# Eine Postgresql-Datenbank ''xyz00_discoursedb'' mit Datenbank-Owner ''xyz00_discourseuser''

Verwendete IP-Ports der Server-Dienste:
# Redis: localhost:32002
# Discourse-Web: localhost:13000

== Konfiguration der PostgreSQL Datenbank ==

Es müssen noch Erweiterungen für Postgresql installiert werden:

<syntaxhighlight lang=shell line>
psql --user xyz00_discourseuser -c "CREATE EXTENSION IF NOT EXISTS hstore WITH SCHEMA public;"
psql --user xyz00_discourseuser -c "CREATE EXTENSION IF NOT EXISTS pg_trgm WITH SCHEMA public;"
psql --user xyz00_discourseuser -c "CREATE EXTENSION IF NOT EXISTS unaccent WITH SCHEMA public;"
</syntaxhighlight>

== Konfiguration des Redis Server ==

{{Textkasten|gelb|Firewall/Redis Port|Leider unterstützt discourse nicht die Kommunikation mit Redis über Unix-Sockets. Dementsprechend muss der für Redis konfigurierte Port von dem hostsharing-Support in der Firewall freigegeben werden.}}

<syntaxhighlight lang=shell>
cd
mkdir redis/etc redis/lib redis/log redis/run
</syntaxhighlight>

Anlegen einer Datei ''/home/pacs/xyz00/users/discourse/redis/etc/redis.conf'' mit folgendem Inhalt:

<syntaxhighlight lang=shell line>
daemonize no
pidfile /home/pacs/xyz00/users/discourse/redis/run/redis-server.pid
port 32002
tcp-backlog 128
bind 127.0.0.1
timeout 300
loglevel notice
logfile /home/pacs/xyz00/users/discourse/redis/log/redis.log
databases 16
save 900 1
save 300 10
save 60 10000
slave-serve-stale-data yes
appendonly no
dbfilename dump.rdb
dir /home/pacs/xyz00/users/discourse/redis/lib
</syntaxhighlight>

Für Discourse 3.x gilt: "Discourse requires Redis 6.2.0 or up"

Für Debian Buster und Bullseye ist daher das Installieren eines neueren Binaries erforderlich. Bei Debian Bookwork ist bereits Redis 7.0 enthalten (siehe https://packages.debian.org/search?keywords=redis-server).

Hier steht ein entsprechendes Binary für Debian Buster zur Verfügung, das mit dem Public Key von Timotheus geprüft werden kann:

* https://download.solidcharity.com/tarballs/tpokorra/hostsharing/redis-server-6.2.12-debian-buster.tar.gz
* Prüfsignatur: https://download.solidcharity.com/tarballs/tpokorra/hostsharing/redis-server-6.2.12-debian-buster.tar.gz.sig

Prüfen der Signatur:

<syntaxhighlight lang=shell>
gpg --verify redis-server-6.2.12-debian-buster.tar.gz.sig redis-server-6.2.12-debian-buster.tar.gz
</syntaxhighlight>

Das Binary muss nach <code>$HOME/bin</code> verschoben werden, und entsprechend beim Starten des Dienstes eingetragen werden.

== Installation von Ruby ==

Als User ''xyz00-discourse'': Installation von Ruby mit ''rbenv'' mit folgenden Befehlen:

Zunächst ''rbenv'' and ''ruby-build'':

<syntaxhighlight lang=shell line>
git clone https://github.com/rbenv/rbenv.git ~/.rbenv
cd ~/.rbenv && src/configure && make -C src
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.profile
echo 'eval "$(rbenv init -)"' >> ~/.profile
</syntaxhighlight>

starte neue Shell:

<syntaxhighlight lang=shell>
exec bash
</syntaxhighlight>

Überprüfe rbenv-Installation

<syntaxhighlight lang=shell>
type rbenv
</syntaxhighlight>

Installiere ruby-build als rbenv-Plugin

<syntaxhighlight lang=shell>
git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build
</syntaxhighlight>

Nun kann die benötigte Ruby-Version installiert werden:

<syntaxhighlight lang=shell>
rbenv install 2.4
</syntaxhighlight>

== Installation von Discourse selber ==

Weiterhin Als User ''xyz00-discourse'':

<syntaxhighlight lang=shell>
cd ~
git clone https://github.com/discourse/discourse.git discourse
cd ~/discourse
</syntaxhighlight>

Die stabile Version auschecken:

<syntaxhighlight lang=shell>
git checkout stable
</syntaxhighlight>

Ruby Pakete installieren:

<syntaxhighlight lang=shell>
gem install bundler
bundle install -j$(getconf _NPROCESSORS_ONLN) --deployment --without development test
</syntaxhighlight>

== Konfiguration der Discourse Software ==

Anlegen einer Datei ''/home/pacs/xyz00/users/discourse/discourse/config/discourse.conf'' anhand der Beispiel-Datei:

<syntaxhighlight lang=shell>
cd ~/discourse
cp config/discourse_defaults.conf config/discourse.conf
</syntaxhighlight>

Anpassen folgender Inhalte:
<syntaxhighlight lang=ini line>
db_host = 127.0.0.1
db_port = 5432
#db_backup_port = 5432 #(auskommentieren)
db_name = xyz00_discoursedb
db_username = xyz00_discourseuser
db_password = "" #db password
hostname = "discourse.xyz00" # hostname
smtp_address = localhost
smtp_enable_start_tls = false
smtp_openssl_verify_mode = 'none'
developer_emails = # your email-address
redis_host = 127.0.0.1
redis_port = 32002
</syntaxhighlight>
===TODO: Secrets setzen! ===
Die Zufallswerte für die Variablen SECRET_KEY_BASE und OTP_SECRET erzeugt man durch zwei Aufrufe des Kommandos

<syntaxhighlight lang=shell>
RAILS_ENV=production bundle exec rake secret
</syntaxhighlight>

=== Sidekiq für Hintergrund-Aufgaben konfigurieren ===

''config/sidekiq.conf''

Wichtig: development auf production ändern.

Mit diesem Dienst werden z.B. die E-Mails zur Aktivierung oder zum Passwort Reset verschickt.

=== Problem mit Content Security Policy ===

Um ein Problem mit Content Security Policy zu lösen, weil manche Dateien über http nachgeladen werden, muss in der Datei <code>config/site_settings.yml</code> der Default Wert für force_https auf True gesetzt werden:
<syntaxhighlight lang=yaml line>
force_https:
default: true
</syntaxhighlight>
=== Problem beim Aufsetzen der Datenbank vermeiden ===

'''→ Notiz Mai 2024:''' dies scheint aktuell nicht aufzutreten.

Aus irgendeinem Grund wird beim Initialisieren der Datenbank versucht, den TYPE hotlinked_media_status zweimal in der Datenbank anzulegen. Der Grund ist nicht ersichtlich.

Es kann folgende Änderung an der Datei <code>db/migrate/20220428094026_create_post_hotlinked_media.rb</code> vorgenommen werden:
<syntaxhighlight lang=ruby line>
reversible do |dir|
dir.up { execute <<~SQL }
DO $$ BEGIN CREATE TYPE hotlinked_media_status AS ENUM('downloaded', 'too_large', 'download_failed', 'upload_create_failed'); EXCEPTION WHEN duplicate_object THEN null; END $$;
SQL
dir.down { execute <<~SQL }
DROP TYPE hotlinked_media_status
SQL
end
</syntaxhighlight>
=== Initialisieren der Datenbank ===

<syntaxhighlight lang=shell>
export SAFETY_ASSURED=1
# In Version 2.0.4 funktioniert db:migrate noch, ansonsten db:schema:load und seed nutzen!
# In Version 3.0.3 funktioniert db:migrate auch noch, db:schema:load ging nicht weil die Datei structure.sql fehlte
#RAILS_ENV=production bundle exec rails db:schema:load
#RAILS_ENV=production bundle exec rails db:seed
RAILS_ENV=production bundle exec rails db:migrate
</syntaxhighlight>

=== Kompilieren der Assets ===

<syntaxhighlight lang=shell>
RAILS_ENV=production bundle exec rails assets:precompile
</syntaxhighlight>

=== Konfiguration des Web-Servers (am Beispiel Puma) ===

Die Datei ''config/puma.conf'' anpassen (hier nur Änderungen angezeigt):

<syntaxhighlight lang=ini>
APP_ROOT = '/home/pacs/xyz00/users/discourse/discourse'
daemonize false
</syntaxhighlight>

== Starten der Dienste ==

Zum Start aller notwendigen Dienste sollte systemd benutzt werden.

Die folgenden Dateien müssen nach <code>.config/systemd/user/</code> kopiert werden (überlange Zeilen werden hier im Wiki umgebrochen)

redis.service:

<syntaxhighlight lang=ini line>
[Unit]
Description=Redis User Service

[Service]
WorkingDirectory=%h/var/redis
Environment="PATH=/usr/local/bin:/usr/bin:/bin"
ExecStart=%h/bin/redis-server %h/etc/redis.conf
Restart=always
PrivateTmp=true
NoNewPrivileges=true

[Install]
WantedBy=default.target
</syntaxhighlight>

sidekiq.service:

<syntaxhighlight lang=ini line>
[Unit]
Description=Discourse Sidekiq Service

[Service]
WorkingDirectory=%h/discourse
Environment="PATH=/usr/local/bin:/usr/bin:/bin"
Environment="RAILS_ENV=production"
Environment="DB_POOL=8"
Environment="MALLOC_ARENA_MAX=2"
ExecStart=%h/.rbenv/shims/bundle exec sidekiq -C %h/discourse/config/sidekiq.yml
StandardOutput=append:%h/var/log/sidekiq.out.log
StandardError=inherit
Restart=always
PrivateTmp=true
NoNewPrivileges=true

[Install]
WantedBy=default.target
After=redis.service
</syntaxhighlight>

discourse.service:

<syntaxhighlight lang=ini line>
[Unit]
Description=Discourse Web Service

[Service]
WorkingDirectory=%h/discourse
Environment="PATH=/usr/local/bin:/usr/bin:/bin"
Environment="RAILS_ENV=production"
Environment="WEB_CONCURRENCY=2"
Environment="MAX_THREADS=5"
Environment="MALLOC_ARENA_MAX=2"
ExecStart=%h/.rbenv/shims/bundle exec puma -C config/puma.rb -e production -b tcp://127.0.0.1:13000
StandardOutput=append:%h/var/log/puma.out.log
StandardError=inherit
Restart=always
PrivateTmp=true
NoNewPrivileges=true

[Install]
WantedBy=default.target
After=redis.service
</syntaxhighlight>

== Einrichten des Apache VHost ==

<syntaxhighlight lang=shell>
cd ~/doms/beispiel.discuss
rm -rf htdocs-ssl subs/www subs-ssl/www
ln -s ~/live/public htdocs-ssl
touch htdocs-ssl/.htaccess
</syntaxhighlight>

Dann die ''htdocs-ssl/.htaccess'' (durch das gelinkte Verzeichnis entspricht das dem Pfad /home/pacs/xyz00/users/discourse/discourse/public/.htaccess ) mit dem Editor der Wahl öffnen und folgende Konfiguration einfügen:

<syntaxhighlight lang=apache line>
DirectoryIndex disabled

RequestHeader set X-Forwarded-Proto "https"

RewriteEngine On
RewriteBase /
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-l
RewriteRule .* http://127.0.0.1:13000%{REQUEST_URI} [proxy,last]
</syntaxhighlight>
== Wartung ==
=== Backup ===

Discourse macht selbstätig backups und legt diese unter 'public/backups' ab. Enthalten ist ein Datenbank-Dump und die hochgeladenen Dateien.

Im Admin-Bereich lassen sich backups auch manuell antreten.

=== Admin Benutzer einladen ===

Manchmal brauchen wir einen neuen Admin Benutzer, den wir von der Kommandozeile aus einladen möchten.

<syntaxhighlight lang=shell>
cd /discourse
RAILS_ENV=production rake admin:invite[admin@example.org]
</syntaxhighlight>

=== Import aus mbox Archiven ===

Um zum Beispiel ein Mailman2 Archiv zu importieren, wo die Nachrichten als .mbox Datei vorliegen, sind folgende Schritte nötig:

Vorbereitungen an Discourse:

<syntaxhighlight lang=shell>
source .profile
cd discourse
bundle config set frozen false
IMPORT=1 bundle install
bundle config set frozen true
nano script/import_scripts/mbox/settings.yml
# dort ändern:
# data_dir: /home/pacs/xyz00/users/discourse/list-archiv
</syntaxhighlight>

Hochladen der Mailinglisten-Archive:
<syntaxhighlight lang=shell>
mkdir ~/list-archiv
# dort muss es Unterordner mit dem Namen der gewünschten Kategorie geben,
# und die mbox Datei muss auch diesen Namen haben, z.B.:
# ~/list-archiv/beispiel/beispiel.mbox
# ~/list-archiv/example/example.mbox
# um die Beiträge in den entsprechenden Kategorien beispiel und example einzufügen.
</syntaxhighlight>

Durchführen des Imports:
<syntaxhighlight lang=shell>
source .profile
cd discourse
RAILS_ENV=production IMPORT=1 bundle exec rails runner \
script/import_scripts/mbox.rb script/import_scripts/mbox/settings.yml
</syntaxhighlight>

=== Export ===
* Wenn ein Forum beendet wird, möchte man evtl. eine Sicherung als statische HTML Seiten.
** Das wird hier diskutiert: https://meta.discourse.org/t/how-do-i-export-the-complete-forum-as-static-html-pages/71007/3
* Um ein Forum von Discourse zu Flarum umzuziehen, hat Timotheus ein Skript geschrieben.
** Das Migrations-Skript: https://github.com/SolidCharity/discourse_to_flarum
** siehe auch https://discuss.flarum.org/d/4930-discourse-to-flarum-migration-support/29

=== Updates ===

Discourse wird über update via mail informieren (dies kann man m.W. abschalten).

Achtung: bei größeren Updates auch immer Änderungen an der Datei site_settings.yml (https://github.com/discourse/discourse/blob/main/config/site_settings.yml) beachten!

Siehe auch die unterstützten Releases: https://releases.discourse.org/ und die Tags: https://github.com/discourse/discourse/tags

==== Am Beispiel von 3.4.7 auf 3.5.1 ====

# Im Web-Backend unter Administration->Backups-> Read-Only Mouds setzen (oder Web Server so konfigurieren, dass keine Zugriffe mehr stattfinden können)
# Backup
# Die lokalen Änderungen sichern:
# cd discourse
# mv ~/plugins.bak/discourse-ai plugins
# git diff v3.4.7 > diff-3.4.7.txt
# git fetch
# git checkout -b hostsharing-deployment-v3.5.1 v3.5.1
# evtl. Änderungen aus diff-3.4.7.txt wieder übernehmen und committen
# patch -p1 < diff-3.4.7.txt
# git commit -a -m "spezifische Änderungen für diese Instanz" --no-verify
# Schauen, ob discourse eine neue Ruby-Version nutzt (z.B. in https://github.com/discourse/discourse_docker/blob/main/image/base/Dockerfile)
# Dies ist der Fall, also
# rbenv install 3.3.8
# rbenv rehash
# echo "3.3.8" > .ruby-version
# installiere Node 22: https://codeberg.org/tpokorra/hostsharing-scripts/src/branch/main/install-nodejs.sh
# source ~/.profile
# gem update --system
# bundle install
# npm install -g terser uglify-js pnpm@9
# corepack use pnpm@latest-9
# pnpm install
# export $(grep -v '^#' ~/discourse.env | xargs -d '\n')
# source ~/.profile
# wir haben keine pg extension pg_vector, daher deaktivieren wir das Plugin während migrate, aber auch für später damit /admin/settings funktioniert:
# mkdir -p ~/plugins.bak
# mv plugins/discourse-ai ~/plugins.bak
# RAILS_ENV=production bundle exec rake db:migrate
# RAILS_ENV=production bundle exec rake assets:precompile
# Services neu starten
<syntaxhighlight lang=shell>
systemctl --user restart puma
systemctl --user restart sidekiq
systemctl --user restart redis
</syntaxhighlight>
* Zuletzt: Read-Only Modus wieder deaktivieren

=== Debugging ===

Es können folgende Einstellungen in der Datei config/environments/production.rb vorgenommen werden. Danach den Puma Dienst neustarten. Fehlermeldungen und Stacktraces werden dann im Browser ausgegeben.

<syntaxhighlight lang="ini" line>
config.log_level = :debug
config.action_dispatch.show_exceptions = :all
config.action_dispatch.debug_exception_log_level = :error

# Full error reports are enabled and caching is turned off
config.consider_all_requests_local = true
config.action_controller.perform_caching = false
</syntaxhighlight>

=== Erforderliche Anpassungen ===
Weil wir bei Debian Bookworm noch mit ImageMagick 6.9 arbeiten, muss dieser [https://github.com/discourse/discourse/commit/17aa831337e352dfd875f1b4ddc4492bd0835119 Patch] rückgängig gemacht werden:

<syntaxhighlight lang="bash" line>
wget https://github.com/discourse/discourse/commit/17aa831337e352dfd875f1b4ddc4492bd0835119.patch -O ~/imagemagick.patch
patch -p1 --reverse < ~/imagemagick.patch
git commit -a -m "revert imagemagick patch" --no-verify
</syntaxhighlight>

== ToDos ==

* Ein Patch, um Discourse auch via Unix-Socket mit Redis sprechen lassen zu können dürfte relativ einfach sein (es wird ein Wrapper um das redis-gem genutzt).
* Konfiguration von discourse, um mit postgresql via Unix-Socket zu kommunizieren (DISCOURSE_DB_SOCKET environment variable)
* Performance-tuning an diversen Stellen, anhand der discourse_docker-Vorgaben (https://github.com/discourse/discourse_docker), z.B.
** thpoff (huge page settings)
** unicorn (hat eine wesentlich ausgefeiltere Konfigurations-Vorlage, wahrscheinlich bereits ordentlich optimiert)

== Links ==

* https://help.skysilk.com/support/solutions/articles/9000120927-how-to-install-discourse-without-docker-using-skysilk-vps-
* https://github.com/discourse/discourse_docker
* https://github.com/discourse/discourse
* https://codeberg.org/tpokorra/hs.ansible/src/branch/main/playbooks/discourse

== Historie ==

* 2018, 14 . September: Initiale Fassung
* 2019, Januar: Update-Informationen ergänzt
* 2022, Juni: systemd Dienste, Discourse 3.0

----
[[Kategorie:HSDoku]]
[[Kategorie:Installationsanleitungen]]
[[Kategorie:RubyOnRails]]
[[Kategorie:Webforen]]
[[Kategorie:Ansible Playbook]]

Keycloak installieren

2026-01-12T12:06:42Z

Tim00: /* Gruppen Synchronisation in der Praxis */

== Allgemein ==

Keycloak [http://www.keycloak.org/] ist eine Open Source Lösung, die ein Single Sign On für verschiedene Anwendungen ermöglicht. Dabei ermöglicht es sowohl die Identitätsverwaltung als auch Zugriffsmanagement.

Es kann die Benutzer entweder aus einem existierenden Verzeichnisdienst (LDAP, Active Directory) auslesen, oder die Gruppen und Benutzer auch selber verwalten.

== Technische Details ==
Keycloak ist in Java geschrieben. Bisher lief es in einem Wildfly Server, aber seit Version 17 (Februar 2022) benutzt es Quarkus, welches ein leichtgewichtiges Java Framework ist.

Es gibt ein Ansible Skript, das die Installationsschritte für Keycloak automatisiert durchführt.

Die Quellen für das Ansible Skript können hier eingesehen werden: [https://codeberg.org/tpokorra/hs.ansible/src/branch/main/playbooks/keycloak]

== Installation ==
Was das Ansible Skript macht, lässt sich mit diesen Worten beschreiben:

* Es wird ein Linux Benutzer eingerichtet.
* Es wird eine Postgresql Datenbank eingerichtet.
* Es wird eine Domain aufgeschaltet.
* Es wird Keycloak als Zip Datei heruntergeladen, z.B. [https://github.com/keycloak/keycloak/releases/download/17.0.0/keycloak-17.0.0.zip], und ins Verzeichnis $HOME/keycloak-17.0.0 entpackt.
* Dann werden ein paar Konfigurationen an der Datei <code>keycloak/conf/keycloak.conf</code> vorgenommen, um die Postgresql Datenbank einzurichten, und um den Proxymodus auf edge zu setzen und den Hostname zu setzen.
* Nun wird die Keycloak Instanz initialisiert, mit dem Befehl: <code>keycloak/bin/kc.sh --cache=local --profile=prod build</code>. Hierbei verhindert die Einstellung für den Cache, dass Keycloak versucht über das Netzwerk Verbindungen zu anderen Instanzen herzustellen.
* Es muss der Server einmal gestartet werden, während der Admin Benutzer mit Passwort in einer Umgebungsvariable gesetzt ist, damit der Benutzer eingerichtet wird.
* Es wird Monit konfiguriert, um den Keycloak Service zu starten, der auf einem internen Port lauscht.
* Es wird der Apache in der htaccess Datei konfiguriert, damit die aufgeschaltete Domain über Proxy auf den Keycloak Dienst verweist. Dabei ist wichtig, dass der Java Prozess mitbekommt, dass die Seite über https läuft. Dazu wird in der htaccess Datei der Wert X-Forwarded-Proto auf https gesetzt.

=== Keycloak mit Systemd ===

Sofern <code>linger</code> für den User schon verfügbar ist, kann auch Systemd verwendet werden. Zudem sollte im Vorfeld <code>export XDG_RUNTIME_DIR=/run/user/$UID</code> ausgeführt werden um Zugriff auf die Befehle zu erhalten.

Beispiel einer Systemd Konfiguration in <code>.config/systemd/user/keycloak.service</code>
<syntaxhighlight lang=ini line>
[Unit]
Description=Keycloak

[Service]
Type=simple
Restart=on-abort
WorkingDirectory=/home/pacs/xyz00/users/login/keycloak
Environment=PROXY_ADDRESS_FORWARDING=true

# Für den ersten Start, um den Adminuser zu setzen
#Environment=KEYCLOAK_ADMIN=changeme
#Environment=KEYCLOAK_ADMIN_PASSWORD=changeme

# Die Option cache=local kann auch an anderer Stelle gesetzt werden.
# Hauptsache sie taucht auf, da es sonst zu Performance-Problemen wie
# Timeouts kommen kann.
ExecStart=/home/pacs/xyz00/users/login/keycloak/latest/bin/kc.sh start --cache=local

[Install]
# Achtung: multiuser.target würde hier zu Problemen führen
WantedBy=default.target
</syntaxhighlight>
== Beispiel einer Einrichtung ==
Diese Anleitung steht auch als [https://youtu.be/bmOp8epgxsM Video auf Youtube] zur Verfügung.

* Auf https://keycloak.example.org/admin anmelden.

=== Admin User einrichten ===
* Der auf der Kommandozeile angelegte Benutzer ist nur vorübergehend gültig.
* Bitte einen permanenten Admin User anlegen, mit den entsprechenden Rollen (role_admin und role_default-roles) ausstatten
* Login mit permanentem Admin durchführen
* Dann den temporären Benutzer löschen.

=== Realm einrichten ===
* Es soll nicht mit der master Realm gearbeitet werden, sondern sollte eine weitere Realm eingerichtet werden, z.B. "MeineFirma"
* Diese neue Realm wird dann ausgewählt

=== Benutzer einrichten ===
* Innerhalb der neuen Realm wird dann ein neuer Benutzer angelegt.
* Beim neuen Benutzer kann ausgewählt werden, dass die E-Mail bereits bestätigt ist.
* Nach dem Speichern des Benutzers kann man dann auch bei Credentials das Passwort setzen. Wenn es nur temporär ist, muss der Benutzer es bei der ersten Anmeldung ändern.
* Nun kann man sich als Administrator abmelden und sich als der Benutzer anmelden, auf https://keycloak.example.org/realms/MeineFirma/account/#/
** Achtung: in anderen Anleitungen heißen die URLs /auth/realms usw, aber auth scheint nicht mehr Teil der Standardeinrichtung zu sein.
* Als Benutzer kann man sein Passwort ändern.
* Wieder abmelden, und wieder als Administrator anmelden.

=== Client einrichten ===
* Achtung: erst aus der Master Realm in die vorher angelegte Realm wechseln, z.B. "MeineFirma"
* Nun sollte ein Client hinzugefügt werden, also eine beliebige Anwendung, die mit Keycloak zusammenarbeiten soll
** Als Client-Protokoll wählt man "OpenID Connect"
** Die Client-ID kann so aussehen: my-nextcloud
** Anwählen: 'Client Authentication', um den OID Typ auf 'Confidential Access Type' zu setzen.
** Anwählen: 'Standard Flow', 'Implicit Flow' und 'Direct Access Grants'
* Eine Root Url eingeben, z.B. https://nextcloud.example.org
* Eine Valid Redirect URI eingeben, z.B. https://nextcloud.example.org/*
* Gültige Web Origins eingeben, z.B. https://nextcloud.example.org
* Speichern
* Unter Roles eine neue Rolle mit Namen admin anlegen.
* Wieder unter den Client Nextcloud gehen, und bei "Client Scopes" klicke auf "my-nextcloud-dedicated", und wähle dort "Add predefined Mapper". Wähle "client roles", und klicke auf "Add". Dann diesen neuen Mapper "client roles" Bearbeiten, und Client ID auf "my-nextcloud" setzen, und "Token Claim Name" mit "roles" setzen, und "Add to userinfo" auf "ON" stellen. Dann Speichern.
* Dann zu nochmal zu Client Scopes (im Client) gehen, und auf "my-nextcloud-dedicated" klicken, und dort im Reiter "Scope" die Option "Full Scope Allowed" abschalten.

* Dann unter Configure / Realm Settings, in General, bei Endpoints auf "OpenID Endpoint Configuration" klicken, dann wird eine Seite geöffnet, auf dieser URL: https://keycloak.example.org/realms/MeineFirma/.well-known/openid-configuration; diese Seite offen halten, wir brauchen daraus die Daten für die Nextcloud Einrichtung

=== Nextcloud einrichten (Einfach) ===
* Als Administrator anmelden, und bei den Apps die App [https://apps.nextcloud.com/apps/sociallogin "Social Login"] installieren.
* Dann bei Einstellungen, unter Verwaltung, Social Login, die gewünschten Einstellungen vornehmen.
* Es sollte ein Kreuz sein bei: Anlegen eines Kontos verhindern, wenn die E-Mail-Adresse bereits von einem anderen Konto verwendet wird.
* Es sollte ein Kreuz sein bei: Verhindern, dass sich Benutzer ohne gemappte Gruppe anmelden können.
* Speichern
* Dann bei "Benutzerdefinierte OpenID Connect Anbindung" auf das Plus klicken
* Nun die Daten aus der "OpenID Endpoint Configuration" (siehe oben) übernehmen: Authorize URL, Token URL, User info URL, Logout URL
* Client ID: nc (Name des Clients in Keycloak)
* Client Secret: hier kommt das Secret hinein, das in Keycloak im Client unter Credentials "Client Secret" zu finden ist. Das kann über die Zwischenablage kopiert werden.
* Scope: openid
* Speichern

=== Nextcloud einrichten (Fortgeschritten) ===
Die folgende App wird mit Rücksicht auf Keycloak entwickelt und hat daher eine bessere Kompatibilität als das Beispiel oben. Allerdings gibt es hierfür keine Optionen in der Cloud, stattdessen wird die <code>config.php</code> direkt bearbeitet.

==== Plugin-Installation ====

# Als Administrator die App [https://github.com/pulsejet/nextcloud-oidc-login "Nextcloud OIDC Login"] installieren
# Die Nextcloud Konfigurationsdatei unter <code>pfad/zur/nextcloud/config/config.php</code> öffnen und basierend auf dem Readme der App (Link aus Schritt #1) befüllen. Das könnte so aussehen:
<syntaxhighlight lang=php line>
'oidc_login_client_id' => 'nextcloud',
'oidc_login_client_secret' => 'bSIPDNUyTQpxmfOpXdwyoBP8nZDQZVuL', // Client Reiter "Credentials" in Keycloak
'oidc_login_provider_url' => 'https://login.mydomain.de/realms/myrealm',
'oidc_login_end_session_redirect' => true,
'oidc_login_logout_url' => 'https://cloud.mydomain.de/index.php/apps/oidc_login/oidc',
'oidc_login_auto_redirect' => true, // hiermit wird das Login-Formular übergangen um Leute weniger zu verwirren
'oidc_login_redir_fallback' => false,
'oidc_login_disable_registration' => false, // Nextcloud soll neue Keycloak Accounts akzeptieren
'oidc_create_groups' => true,
'oidc_login_attributes' => array(
'id' => 'preferred_username',
'mail' => 'email',
'groups' => 'ownCloudGroups',
'is_admin' => 'ownCloudAdmin',
),
</syntaxhighlight>

==== In Keycloak nochmal alles kontrollieren ====
# Client ID stimmt überein
# unter <code>Capability config</code> ist <code>Client authentication</code> aktiv (damit wir ua. unser Secret bekommen)
# <code>Valid redirect URIs</code> erlaubt </code>https://cloud.mydomain.de/*</code> – oder eine konkretere Adresse. Das Plus übernimmt die Einstellung aus <code>Valid redirect URIs</code>
# <code>Valid post logout redirect URIs</code> erlaubt <code>+</code> oder </code>https://cloud.mydomain.de/*</code> – oder eine konkretere Adresse
# <code>Fine Grain OpenID Connect Configuration</code> steht unter <code>ID Token Signature Algorithm</code> auf <code>RS256</code> (Achtung, hier verrutscht man schnell weil die Einträge sich ähneln)

==== Gruppen Synchronisation über Rollen ermöglichen ====
Hierfür legen wir einen Mapper in <code>nextcloud</code> Client an. Anschließend müssen die tatsächlichen Gruppen mit Roles verknüpft werden. Hintergrund ist, dass Roles eigentlich für Berechtigungsmanagement gedacht sind, und Gruppen eigentlich nur User gruppieren sollen.
# wir wechseln im Client <code>nextcloud</code> auf den Reiter <code>Client scopes</code>
# wir wählen <code>nextcloud-dedicated</code>
# Add mapper -> by configuration
## Type: <code>User Client Role</code>
## Name: <code>ownCloudGroups</code>
## Client ID
### Option #1: <code>none</code> – es werden alle <code>Realm roles</code> abgerufen. Das umfasst allerdings auch die Defaults wie <code>uma_authorization</code>, <code>offline_access</code>, <code>default-user-roles</code> und ist nicht immer gewünscht.
### Option #2: <code>nextcloud</code> hier können im Anschluss roles im Client angelegt und mit <code>Groups</code> oder <code>Realm roles</code> verknüpft werden.
## Multivalued: <code>On</code>
## Token Claim Name: <code>NextcloudGroups</code>
## Claim JSON Type: <code>String</code>
## die folgenden drei Optionen: <code>On</code>

==== Gruppen Synchronisation in der Praxis ====

Option #2: Client ID <code>nextcloud</code>
# wir wechseln im Client <code>nextcloud</code> auf den Reiter <code>Roles</code>
# Create role
## Wunschname
# wir wechseln in <code>Groups</code> (Sidebar)
# Create group
## Wunschname: Wichtig: es muss der Name der Gruppe in Nextcloud genommen werden, der in der URL der Gruppe erkennbar ist; nicht der DisplayName
# In der Gruppe wechseln wir auf den Reiter <code>Role mapping</code>
## Assign role
## Im Dropdown wechseln wir auf den Filter <code>by clients</code>
## Wir wählen die gewünschte Rolle
## Unten Links, button <code>Assign</code>

Ab hier können wir die Gruppe normal zuweisen.

=== Benutzer einrichten ===
* Einen Benutzer im Keycloak einrichten, in der Realm "MeineFirma".
* Den Benutzer bearbeiten, und unter "Role Mappings", "Assign Role", "Filter by Clients", wähle "my-nextcloud admin" und klicke auf "Assign".

== Fehler beheben ==

Problem: Gerade beim Experimentieren kommt schon mal die Meldung: "expected expression, got end of script"
* Lösung: Webseite aus der Firefox Chronik komplett löschen, oder in einem privaten Fenster öffnen, dann geht es wieder.

Generell kann es zu verwirrenden Fehlermeldungen kommen, wenn man sich versucht in einer verknüpften Anwendung einzuloggen aber beispielsweise noch als Admin im Master-Realm eingeloggt ist.

=== Logging ===
Um Fehler besser verstehen zu können, kann das Logging angeschaltet werden, siehe auch [https://www.keycloak.org/server/logging].

Dazu müssen im Start Skript <code>bin/start-keycloak.sh</code> folgende Parameter hinzugefügt werden:
<syntaxhighlight lang=shell>
--log-level=ERROR --log=file
</syntaxhighlight>
Also sieht es z.B. so aus:
<syntaxhighlight lang=shell>
./bin/kc.sh start --http-port [...] --proxy edge --log-level=ERROR --log=file &
</syntaxhighlight>
Nach dem Neustart von Keycloak gibt es dann die Datei <code>keycloak/data/log/keycloak.log</code>.

== Links ==
*[http://www.keycloak.org/ Webseite von Keycloak]
*[https://codeberg.org/tpokorra/hs.ansible/src/branch/main/playbooks/keycloak Ansible Playbook für Hostsharing]
*[https://robferguson.org/blog/2019/12/24/getting-started-with-keycloak/ Getting started with Keycloak]
*[https://janikvonrotz.ch/2020/10/20/openid-connect-with-nextcloud-and-keycloak/ OpenID Connect with Nextcloud and Keycloak] von Janik Vonrotz, Oktober 2020
* [https://www.muehlencord.de/wordpress/2019/12/14/nextcloud-sso-using-keycloak/ Nextcloud SSO using Keycloak] von Jörns Blog, Dezember 2019
* [https://youtu.be/bmOp8epgxsM Erklärvideo auf Youtube] zum Einrichten von Keycloak und Nextcloud
* [https://apps.nextcloud.com/apps/sociallogin Nextcloud App Social Login]

----
[[Kategorie:HSDoku]]
[[Kategorie:Installationsanleitungen]]
[[Kategorie:Ansible Playbook]]
[[Kategorie:Software]]
[[Kategorie:SSO]]
[[Kategorie:Java]]

Keycloak installieren

2026-01-12T12:06:00Z

Tim00: /* Gruppen Synchronisation über Rollen ermöglichen */

== Allgemein ==

Keycloak [http://www.keycloak.org/] ist eine Open Source Lösung, die ein Single Sign On für verschiedene Anwendungen ermöglicht. Dabei ermöglicht es sowohl die Identitätsverwaltung als auch Zugriffsmanagement.

Es kann die Benutzer entweder aus einem existierenden Verzeichnisdienst (LDAP, Active Directory) auslesen, oder die Gruppen und Benutzer auch selber verwalten.

== Technische Details ==
Keycloak ist in Java geschrieben. Bisher lief es in einem Wildfly Server, aber seit Version 17 (Februar 2022) benutzt es Quarkus, welches ein leichtgewichtiges Java Framework ist.

Es gibt ein Ansible Skript, das die Installationsschritte für Keycloak automatisiert durchführt.

Die Quellen für das Ansible Skript können hier eingesehen werden: [https://codeberg.org/tpokorra/hs.ansible/src/branch/main/playbooks/keycloak]

== Installation ==
Was das Ansible Skript macht, lässt sich mit diesen Worten beschreiben:

* Es wird ein Linux Benutzer eingerichtet.
* Es wird eine Postgresql Datenbank eingerichtet.
* Es wird eine Domain aufgeschaltet.
* Es wird Keycloak als Zip Datei heruntergeladen, z.B. [https://github.com/keycloak/keycloak/releases/download/17.0.0/keycloak-17.0.0.zip], und ins Verzeichnis $HOME/keycloak-17.0.0 entpackt.
* Dann werden ein paar Konfigurationen an der Datei <code>keycloak/conf/keycloak.conf</code> vorgenommen, um die Postgresql Datenbank einzurichten, und um den Proxymodus auf edge zu setzen und den Hostname zu setzen.
* Nun wird die Keycloak Instanz initialisiert, mit dem Befehl: <code>keycloak/bin/kc.sh --cache=local --profile=prod build</code>. Hierbei verhindert die Einstellung für den Cache, dass Keycloak versucht über das Netzwerk Verbindungen zu anderen Instanzen herzustellen.
* Es muss der Server einmal gestartet werden, während der Admin Benutzer mit Passwort in einer Umgebungsvariable gesetzt ist, damit der Benutzer eingerichtet wird.
* Es wird Monit konfiguriert, um den Keycloak Service zu starten, der auf einem internen Port lauscht.
* Es wird der Apache in der htaccess Datei konfiguriert, damit die aufgeschaltete Domain über Proxy auf den Keycloak Dienst verweist. Dabei ist wichtig, dass der Java Prozess mitbekommt, dass die Seite über https läuft. Dazu wird in der htaccess Datei der Wert X-Forwarded-Proto auf https gesetzt.

=== Keycloak mit Systemd ===

Sofern <code>linger</code> für den User schon verfügbar ist, kann auch Systemd verwendet werden. Zudem sollte im Vorfeld <code>export XDG_RUNTIME_DIR=/run/user/$UID</code> ausgeführt werden um Zugriff auf die Befehle zu erhalten.

Beispiel einer Systemd Konfiguration in <code>.config/systemd/user/keycloak.service</code>
<syntaxhighlight lang=ini line>
[Unit]
Description=Keycloak

[Service]
Type=simple
Restart=on-abort
WorkingDirectory=/home/pacs/xyz00/users/login/keycloak
Environment=PROXY_ADDRESS_FORWARDING=true

# Für den ersten Start, um den Adminuser zu setzen
#Environment=KEYCLOAK_ADMIN=changeme
#Environment=KEYCLOAK_ADMIN_PASSWORD=changeme

# Die Option cache=local kann auch an anderer Stelle gesetzt werden.
# Hauptsache sie taucht auf, da es sonst zu Performance-Problemen wie
# Timeouts kommen kann.
ExecStart=/home/pacs/xyz00/users/login/keycloak/latest/bin/kc.sh start --cache=local

[Install]
# Achtung: multiuser.target würde hier zu Problemen führen
WantedBy=default.target
</syntaxhighlight>
== Beispiel einer Einrichtung ==
Diese Anleitung steht auch als [https://youtu.be/bmOp8epgxsM Video auf Youtube] zur Verfügung.

* Auf https://keycloak.example.org/admin anmelden.

=== Admin User einrichten ===
* Der auf der Kommandozeile angelegte Benutzer ist nur vorübergehend gültig.
* Bitte einen permanenten Admin User anlegen, mit den entsprechenden Rollen (role_admin und role_default-roles) ausstatten
* Login mit permanentem Admin durchführen
* Dann den temporären Benutzer löschen.

=== Realm einrichten ===
* Es soll nicht mit der master Realm gearbeitet werden, sondern sollte eine weitere Realm eingerichtet werden, z.B. "MeineFirma"
* Diese neue Realm wird dann ausgewählt

=== Benutzer einrichten ===
* Innerhalb der neuen Realm wird dann ein neuer Benutzer angelegt.
* Beim neuen Benutzer kann ausgewählt werden, dass die E-Mail bereits bestätigt ist.
* Nach dem Speichern des Benutzers kann man dann auch bei Credentials das Passwort setzen. Wenn es nur temporär ist, muss der Benutzer es bei der ersten Anmeldung ändern.
* Nun kann man sich als Administrator abmelden und sich als der Benutzer anmelden, auf https://keycloak.example.org/realms/MeineFirma/account/#/
** Achtung: in anderen Anleitungen heißen die URLs /auth/realms usw, aber auth scheint nicht mehr Teil der Standardeinrichtung zu sein.
* Als Benutzer kann man sein Passwort ändern.
* Wieder abmelden, und wieder als Administrator anmelden.

=== Client einrichten ===
* Achtung: erst aus der Master Realm in die vorher angelegte Realm wechseln, z.B. "MeineFirma"
* Nun sollte ein Client hinzugefügt werden, also eine beliebige Anwendung, die mit Keycloak zusammenarbeiten soll
** Als Client-Protokoll wählt man "OpenID Connect"
** Die Client-ID kann so aussehen: my-nextcloud
** Anwählen: 'Client Authentication', um den OID Typ auf 'Confidential Access Type' zu setzen.
** Anwählen: 'Standard Flow', 'Implicit Flow' und 'Direct Access Grants'
* Eine Root Url eingeben, z.B. https://nextcloud.example.org
* Eine Valid Redirect URI eingeben, z.B. https://nextcloud.example.org/*
* Gültige Web Origins eingeben, z.B. https://nextcloud.example.org
* Speichern
* Unter Roles eine neue Rolle mit Namen admin anlegen.
* Wieder unter den Client Nextcloud gehen, und bei "Client Scopes" klicke auf "my-nextcloud-dedicated", und wähle dort "Add predefined Mapper". Wähle "client roles", und klicke auf "Add". Dann diesen neuen Mapper "client roles" Bearbeiten, und Client ID auf "my-nextcloud" setzen, und "Token Claim Name" mit "roles" setzen, und "Add to userinfo" auf "ON" stellen. Dann Speichern.
* Dann zu nochmal zu Client Scopes (im Client) gehen, und auf "my-nextcloud-dedicated" klicken, und dort im Reiter "Scope" die Option "Full Scope Allowed" abschalten.

* Dann unter Configure / Realm Settings, in General, bei Endpoints auf "OpenID Endpoint Configuration" klicken, dann wird eine Seite geöffnet, auf dieser URL: https://keycloak.example.org/realms/MeineFirma/.well-known/openid-configuration; diese Seite offen halten, wir brauchen daraus die Daten für die Nextcloud Einrichtung

=== Nextcloud einrichten (Einfach) ===
* Als Administrator anmelden, und bei den Apps die App [https://apps.nextcloud.com/apps/sociallogin "Social Login"] installieren.
* Dann bei Einstellungen, unter Verwaltung, Social Login, die gewünschten Einstellungen vornehmen.
* Es sollte ein Kreuz sein bei: Anlegen eines Kontos verhindern, wenn die E-Mail-Adresse bereits von einem anderen Konto verwendet wird.
* Es sollte ein Kreuz sein bei: Verhindern, dass sich Benutzer ohne gemappte Gruppe anmelden können.
* Speichern
* Dann bei "Benutzerdefinierte OpenID Connect Anbindung" auf das Plus klicken
* Nun die Daten aus der "OpenID Endpoint Configuration" (siehe oben) übernehmen: Authorize URL, Token URL, User info URL, Logout URL
* Client ID: nc (Name des Clients in Keycloak)
* Client Secret: hier kommt das Secret hinein, das in Keycloak im Client unter Credentials "Client Secret" zu finden ist. Das kann über die Zwischenablage kopiert werden.
* Scope: openid
* Speichern

=== Nextcloud einrichten (Fortgeschritten) ===
Die folgende App wird mit Rücksicht auf Keycloak entwickelt und hat daher eine bessere Kompatibilität als das Beispiel oben. Allerdings gibt es hierfür keine Optionen in der Cloud, stattdessen wird die <code>config.php</code> direkt bearbeitet.

==== Plugin-Installation ====

# Als Administrator die App [https://github.com/pulsejet/nextcloud-oidc-login "Nextcloud OIDC Login"] installieren
# Die Nextcloud Konfigurationsdatei unter <code>pfad/zur/nextcloud/config/config.php</code> öffnen und basierend auf dem Readme der App (Link aus Schritt #1) befüllen. Das könnte so aussehen:
<syntaxhighlight lang=php line>
'oidc_login_client_id' => 'nextcloud',
'oidc_login_client_secret' => 'bSIPDNUyTQpxmfOpXdwyoBP8nZDQZVuL', // Client Reiter "Credentials" in Keycloak
'oidc_login_provider_url' => 'https://login.mydomain.de/realms/myrealm',
'oidc_login_end_session_redirect' => true,
'oidc_login_logout_url' => 'https://cloud.mydomain.de/index.php/apps/oidc_login/oidc',
'oidc_login_auto_redirect' => true, // hiermit wird das Login-Formular übergangen um Leute weniger zu verwirren
'oidc_login_redir_fallback' => false,
'oidc_login_disable_registration' => false, // Nextcloud soll neue Keycloak Accounts akzeptieren
'oidc_create_groups' => true,
'oidc_login_attributes' => array(
'id' => 'preferred_username',
'mail' => 'email',
'groups' => 'ownCloudGroups',
'is_admin' => 'ownCloudAdmin',
),
</syntaxhighlight>

==== In Keycloak nochmal alles kontrollieren ====
# Client ID stimmt überein
# unter <code>Capability config</code> ist <code>Client authentication</code> aktiv (damit wir ua. unser Secret bekommen)
# <code>Valid redirect URIs</code> erlaubt </code>https://cloud.mydomain.de/*</code> – oder eine konkretere Adresse. Das Plus übernimmt die Einstellung aus <code>Valid redirect URIs</code>
# <code>Valid post logout redirect URIs</code> erlaubt <code>+</code> oder </code>https://cloud.mydomain.de/*</code> – oder eine konkretere Adresse
# <code>Fine Grain OpenID Connect Configuration</code> steht unter <code>ID Token Signature Algorithm</code> auf <code>RS256</code> (Achtung, hier verrutscht man schnell weil die Einträge sich ähneln)

==== Gruppen Synchronisation über Rollen ermöglichen ====
Hierfür legen wir einen Mapper in <code>nextcloud</code> Client an. Anschließend müssen die tatsächlichen Gruppen mit Roles verknüpft werden. Hintergrund ist, dass Roles eigentlich für Berechtigungsmanagement gedacht sind, und Gruppen eigentlich nur User gruppieren sollen.
# wir wechseln im Client <code>nextcloud</code> auf den Reiter <code>Client scopes</code>
# wir wählen <code>nextcloud-dedicated</code>
# Add mapper -> by configuration
## Type: <code>User Client Role</code>
## Name: <code>ownCloudGroups</code>
## Client ID
### Option #1: <code>none</code> – es werden alle <code>Realm roles</code> abgerufen. Das umfasst allerdings auch die Defaults wie <code>uma_authorization</code>, <code>offline_access</code>, <code>default-user-roles</code> und ist nicht immer gewünscht.
### Option #2: <code>nextcloud</code> hier können im Anschluss roles im Client angelegt und mit <code>Groups</code> oder <code>Realm roles</code> verknüpft werden.
## Multivalued: <code>On</code>
## Token Claim Name: <code>NextcloudGroups</code>
## Claim JSON Type: <code>String</code>
## die folgenden drei Optionen: <code>On</code>

==== Gruppen Synchronisation in der Praxis ====

Option #2: Client ID <code>nextcloud</code>
# wir wechseln im Client <code>nextcloud</code> auf den Reiter <code>Roles</code>
# Create role
## Wunschname
# wir wechseln in <code>Groups</code> (Sidebar)
# Create group
## Wunschname: Wichtig: es muss der Name der Gruppe in Nextcloud genommen werden, der in der URL der Gruppe erkennbar ist; nicht der DisplayName
# In der Gruppe wechseln wir auf den Reiter <code>Role mapping</code>
## Assign role
## Im Dropdown welchseln wir auf den Filter <code>by clients</code>
## Wir wählen die gewünschte Rolle
## Unten Links, button <code>Assign</code>

Ab hier können wir die Gruppe normal zuweisen.

=== Benutzer einrichten ===
* Einen Benutzer im Keycloak einrichten, in der Realm "MeineFirma".
* Den Benutzer bearbeiten, und unter "Role Mappings", "Assign Role", "Filter by Clients", wähle "my-nextcloud admin" und klicke auf "Assign".

== Fehler beheben ==

Problem: Gerade beim Experimentieren kommt schon mal die Meldung: "expected expression, got end of script"
* Lösung: Webseite aus der Firefox Chronik komplett löschen, oder in einem privaten Fenster öffnen, dann geht es wieder.

Generell kann es zu verwirrenden Fehlermeldungen kommen, wenn man sich versucht in einer verknüpften Anwendung einzuloggen aber beispielsweise noch als Admin im Master-Realm eingeloggt ist.

=== Logging ===
Um Fehler besser verstehen zu können, kann das Logging angeschaltet werden, siehe auch [https://www.keycloak.org/server/logging].

Dazu müssen im Start Skript <code>bin/start-keycloak.sh</code> folgende Parameter hinzugefügt werden:
<syntaxhighlight lang=shell>
--log-level=ERROR --log=file
</syntaxhighlight>
Also sieht es z.B. so aus:
<syntaxhighlight lang=shell>
./bin/kc.sh start --http-port [...] --proxy edge --log-level=ERROR --log=file &
</syntaxhighlight>
Nach dem Neustart von Keycloak gibt es dann die Datei <code>keycloak/data/log/keycloak.log</code>.

== Links ==
*[http://www.keycloak.org/ Webseite von Keycloak]
*[https://codeberg.org/tpokorra/hs.ansible/src/branch/main/playbooks/keycloak Ansible Playbook für Hostsharing]
*[https://robferguson.org/blog/2019/12/24/getting-started-with-keycloak/ Getting started with Keycloak]
*[https://janikvonrotz.ch/2020/10/20/openid-connect-with-nextcloud-and-keycloak/ OpenID Connect with Nextcloud and Keycloak] von Janik Vonrotz, Oktober 2020
* [https://www.muehlencord.de/wordpress/2019/12/14/nextcloud-sso-using-keycloak/ Nextcloud SSO using Keycloak] von Jörns Blog, Dezember 2019
* [https://youtu.be/bmOp8epgxsM Erklärvideo auf Youtube] zum Einrichten von Keycloak und Nextcloud
* [https://apps.nextcloud.com/apps/sociallogin Nextcloud App Social Login]

----
[[Kategorie:HSDoku]]
[[Kategorie:Installationsanleitungen]]
[[Kategorie:Ansible Playbook]]
[[Kategorie:Software]]
[[Kategorie:SSO]]
[[Kategorie:Java]]

Keycloak installieren

2026-01-12T12:05:10Z

Tim00: /* Gruppen Synchronisation in der Praxis */

== Allgemein ==

Keycloak [http://www.keycloak.org/] ist eine Open Source Lösung, die ein Single Sign On für verschiedene Anwendungen ermöglicht. Dabei ermöglicht es sowohl die Identitätsverwaltung als auch Zugriffsmanagement.

Es kann die Benutzer entweder aus einem existierenden Verzeichnisdienst (LDAP, Active Directory) auslesen, oder die Gruppen und Benutzer auch selber verwalten.

== Technische Details ==
Keycloak ist in Java geschrieben. Bisher lief es in einem Wildfly Server, aber seit Version 17 (Februar 2022) benutzt es Quarkus, welches ein leichtgewichtiges Java Framework ist.

Es gibt ein Ansible Skript, das die Installationsschritte für Keycloak automatisiert durchführt.

Die Quellen für das Ansible Skript können hier eingesehen werden: [https://codeberg.org/tpokorra/hs.ansible/src/branch/main/playbooks/keycloak]

== Installation ==
Was das Ansible Skript macht, lässt sich mit diesen Worten beschreiben:

* Es wird ein Linux Benutzer eingerichtet.
* Es wird eine Postgresql Datenbank eingerichtet.
* Es wird eine Domain aufgeschaltet.
* Es wird Keycloak als Zip Datei heruntergeladen, z.B. [https://github.com/keycloak/keycloak/releases/download/17.0.0/keycloak-17.0.0.zip], und ins Verzeichnis $HOME/keycloak-17.0.0 entpackt.
* Dann werden ein paar Konfigurationen an der Datei <code>keycloak/conf/keycloak.conf</code> vorgenommen, um die Postgresql Datenbank einzurichten, und um den Proxymodus auf edge zu setzen und den Hostname zu setzen.
* Nun wird die Keycloak Instanz initialisiert, mit dem Befehl: <code>keycloak/bin/kc.sh --cache=local --profile=prod build</code>. Hierbei verhindert die Einstellung für den Cache, dass Keycloak versucht über das Netzwerk Verbindungen zu anderen Instanzen herzustellen.
* Es muss der Server einmal gestartet werden, während der Admin Benutzer mit Passwort in einer Umgebungsvariable gesetzt ist, damit der Benutzer eingerichtet wird.
* Es wird Monit konfiguriert, um den Keycloak Service zu starten, der auf einem internen Port lauscht.
* Es wird der Apache in der htaccess Datei konfiguriert, damit die aufgeschaltete Domain über Proxy auf den Keycloak Dienst verweist. Dabei ist wichtig, dass der Java Prozess mitbekommt, dass die Seite über https läuft. Dazu wird in der htaccess Datei der Wert X-Forwarded-Proto auf https gesetzt.

=== Keycloak mit Systemd ===

Sofern <code>linger</code> für den User schon verfügbar ist, kann auch Systemd verwendet werden. Zudem sollte im Vorfeld <code>export XDG_RUNTIME_DIR=/run/user/$UID</code> ausgeführt werden um Zugriff auf die Befehle zu erhalten.

Beispiel einer Systemd Konfiguration in <code>.config/systemd/user/keycloak.service</code>
<syntaxhighlight lang=ini line>
[Unit]
Description=Keycloak

[Service]
Type=simple
Restart=on-abort
WorkingDirectory=/home/pacs/xyz00/users/login/keycloak
Environment=PROXY_ADDRESS_FORWARDING=true

# Für den ersten Start, um den Adminuser zu setzen
#Environment=KEYCLOAK_ADMIN=changeme
#Environment=KEYCLOAK_ADMIN_PASSWORD=changeme

# Die Option cache=local kann auch an anderer Stelle gesetzt werden.
# Hauptsache sie taucht auf, da es sonst zu Performance-Problemen wie
# Timeouts kommen kann.
ExecStart=/home/pacs/xyz00/users/login/keycloak/latest/bin/kc.sh start --cache=local

[Install]
# Achtung: multiuser.target würde hier zu Problemen führen
WantedBy=default.target
</syntaxhighlight>
== Beispiel einer Einrichtung ==
Diese Anleitung steht auch als [https://youtu.be/bmOp8epgxsM Video auf Youtube] zur Verfügung.

* Auf https://keycloak.example.org/admin anmelden.

=== Admin User einrichten ===
* Der auf der Kommandozeile angelegte Benutzer ist nur vorübergehend gültig.
* Bitte einen permanenten Admin User anlegen, mit den entsprechenden Rollen (role_admin und role_default-roles) ausstatten
* Login mit permanentem Admin durchführen
* Dann den temporären Benutzer löschen.

=== Realm einrichten ===
* Es soll nicht mit der master Realm gearbeitet werden, sondern sollte eine weitere Realm eingerichtet werden, z.B. "MeineFirma"
* Diese neue Realm wird dann ausgewählt

=== Benutzer einrichten ===
* Innerhalb der neuen Realm wird dann ein neuer Benutzer angelegt.
* Beim neuen Benutzer kann ausgewählt werden, dass die E-Mail bereits bestätigt ist.
* Nach dem Speichern des Benutzers kann man dann auch bei Credentials das Passwort setzen. Wenn es nur temporär ist, muss der Benutzer es bei der ersten Anmeldung ändern.
* Nun kann man sich als Administrator abmelden und sich als der Benutzer anmelden, auf https://keycloak.example.org/realms/MeineFirma/account/#/
** Achtung: in anderen Anleitungen heißen die URLs /auth/realms usw, aber auth scheint nicht mehr Teil der Standardeinrichtung zu sein.
* Als Benutzer kann man sein Passwort ändern.
* Wieder abmelden, und wieder als Administrator anmelden.

=== Client einrichten ===
* Achtung: erst aus der Master Realm in die vorher angelegte Realm wechseln, z.B. "MeineFirma"
* Nun sollte ein Client hinzugefügt werden, also eine beliebige Anwendung, die mit Keycloak zusammenarbeiten soll
** Als Client-Protokoll wählt man "OpenID Connect"
** Die Client-ID kann so aussehen: my-nextcloud
** Anwählen: 'Client Authentication', um den OID Typ auf 'Confidential Access Type' zu setzen.
** Anwählen: 'Standard Flow', 'Implicit Flow' und 'Direct Access Grants'
* Eine Root Url eingeben, z.B. https://nextcloud.example.org
* Eine Valid Redirect URI eingeben, z.B. https://nextcloud.example.org/*
* Gültige Web Origins eingeben, z.B. https://nextcloud.example.org
* Speichern
* Unter Roles eine neue Rolle mit Namen admin anlegen.
* Wieder unter den Client Nextcloud gehen, und bei "Client Scopes" klicke auf "my-nextcloud-dedicated", und wähle dort "Add predefined Mapper". Wähle "client roles", und klicke auf "Add". Dann diesen neuen Mapper "client roles" Bearbeiten, und Client ID auf "my-nextcloud" setzen, und "Token Claim Name" mit "roles" setzen, und "Add to userinfo" auf "ON" stellen. Dann Speichern.
* Dann zu nochmal zu Client Scopes (im Client) gehen, und auf "my-nextcloud-dedicated" klicken, und dort im Reiter "Scope" die Option "Full Scope Allowed" abschalten.

* Dann unter Configure / Realm Settings, in General, bei Endpoints auf "OpenID Endpoint Configuration" klicken, dann wird eine Seite geöffnet, auf dieser URL: https://keycloak.example.org/realms/MeineFirma/.well-known/openid-configuration; diese Seite offen halten, wir brauchen daraus die Daten für die Nextcloud Einrichtung

=== Nextcloud einrichten (Einfach) ===
* Als Administrator anmelden, und bei den Apps die App [https://apps.nextcloud.com/apps/sociallogin "Social Login"] installieren.
* Dann bei Einstellungen, unter Verwaltung, Social Login, die gewünschten Einstellungen vornehmen.
* Es sollte ein Kreuz sein bei: Anlegen eines Kontos verhindern, wenn die E-Mail-Adresse bereits von einem anderen Konto verwendet wird.
* Es sollte ein Kreuz sein bei: Verhindern, dass sich Benutzer ohne gemappte Gruppe anmelden können.
* Speichern
* Dann bei "Benutzerdefinierte OpenID Connect Anbindung" auf das Plus klicken
* Nun die Daten aus der "OpenID Endpoint Configuration" (siehe oben) übernehmen: Authorize URL, Token URL, User info URL, Logout URL
* Client ID: nc (Name des Clients in Keycloak)
* Client Secret: hier kommt das Secret hinein, das in Keycloak im Client unter Credentials "Client Secret" zu finden ist. Das kann über die Zwischenablage kopiert werden.
* Scope: openid
* Speichern

=== Nextcloud einrichten (Fortgeschritten) ===
Die folgende App wird mit Rücksicht auf Keycloak entwickelt und hat daher eine bessere Kompatibilität als das Beispiel oben. Allerdings gibt es hierfür keine Optionen in der Cloud, stattdessen wird die <code>config.php</code> direkt bearbeitet.

==== Plugin-Installation ====

# Als Administrator die App [https://github.com/pulsejet/nextcloud-oidc-login "Nextcloud OIDC Login"] installieren
# Die Nextcloud Konfigurationsdatei unter <code>pfad/zur/nextcloud/config/config.php</code> öffnen und basierend auf dem Readme der App (Link aus Schritt #1) befüllen. Das könnte so aussehen:
<syntaxhighlight lang=php line>
'oidc_login_client_id' => 'nextcloud',
'oidc_login_client_secret' => 'bSIPDNUyTQpxmfOpXdwyoBP8nZDQZVuL', // Client Reiter "Credentials" in Keycloak
'oidc_login_provider_url' => 'https://login.mydomain.de/realms/myrealm',
'oidc_login_end_session_redirect' => true,
'oidc_login_logout_url' => 'https://cloud.mydomain.de/index.php/apps/oidc_login/oidc',
'oidc_login_auto_redirect' => true, // hiermit wird das Login-Formular übergangen um Leute weniger zu verwirren
'oidc_login_redir_fallback' => false,
'oidc_login_disable_registration' => false, // Nextcloud soll neue Keycloak Accounts akzeptieren
'oidc_create_groups' => true,
'oidc_login_attributes' => array(
'id' => 'preferred_username',
'mail' => 'email',
'groups' => 'ownCloudGroups',
'is_admin' => 'ownCloudAdmin',
),
</syntaxhighlight>

==== In Keycloak nochmal alles kontrollieren ====
# Client ID stimmt überein
# unter <code>Capability config</code> ist <code>Client authentication</code> aktiv (damit wir ua. unser Secret bekommen)
# <code>Valid redirect URIs</code> erlaubt </code>https://cloud.mydomain.de/*</code> – oder eine konkretere Adresse. Das Plus übernimmt die Einstellung aus <code>Valid redirect URIs</code>
# <code>Valid post logout redirect URIs</code> erlaubt <code>+</code> oder </code>https://cloud.mydomain.de/*</code> – oder eine konkretere Adresse
# <code>Fine Grain OpenID Connect Configuration</code> steht unter <code>ID Token Signature Algorithm</code> auf <code>RS256</code> (Achtung, hier verrutscht man schnell weil die Einträge sich ähneln)

==== Gruppen Synchronisation über Rollen ermöglichen ====
Hierfür legen wir einen Mapper in <code>nextcloud</code> Client an. Anschließend müssen die tatsächlichen Gruppen mit Roles verknüpft werden. Hintergrund ist, dass Roles eigentlich für Berechtigungsmanagement gedacht sind, und Gruppen eigentlich nur User gruppieren sollen.
# wir wechseln im Client <code>nextcloud</code> auf den Reiter <code>Client scopes</code>
# wir wählen <code>nextcloud-dedicated</code>
# Add mapper -> by configuration
## Type: <code>User Client Role</code>
## Name: <code>ownCloudGroups</code>
## Client ID
### Option #1: <code>none</code> – es werden alle <code>Realm roles</code> abgerufen. Das umfasst allerdings auch die Defaults wie <code>uma_authorization</code>, <code>offline_access</code>, <code>default-user-roles</code> und ist nicht immer gewünscht.
### Option #2: <code>nextcloud</code> hier können im Anschluss roles im Client angelegt und mit <code>Groups</code> oder <code>Realm roles</code> verknüpft werden.
## Multivalued: <code>On</code>
## Token Claim Name: <code>ownCloudGroups</code>
## Claim JSON Type: <code>String</code>
## die folgenden drei Optionen: <code>On</code>

==== Gruppen Synchronisation in der Praxis ====

Option #2: Client ID <code>nextcloud</code>
# wir wechseln im Client <code>nextcloud</code> auf den Reiter <code>Roles</code>
# Create role
## Wunschname
# wir wechseln in <code>Groups</code> (Sidebar)
# Create group
## Wunschname: Wichtig: es muss der Name der Gruppe in Nextcloud genommen werden, der in der URL der Gruppe erkennbar ist; nicht der DisplayName
# In der Gruppe wechseln wir auf den Reiter <code>Role mapping</code>
## Assign role
## Im Dropdown welchseln wir auf den Filter <code>by clients</code>
## Wir wählen die gewünschte Rolle
## Unten Links, button <code>Assign</code>

Ab hier können wir die Gruppe normal zuweisen.

=== Benutzer einrichten ===
* Einen Benutzer im Keycloak einrichten, in der Realm "MeineFirma".
* Den Benutzer bearbeiten, und unter "Role Mappings", "Assign Role", "Filter by Clients", wähle "my-nextcloud admin" und klicke auf "Assign".

== Fehler beheben ==

Problem: Gerade beim Experimentieren kommt schon mal die Meldung: "expected expression, got end of script"
* Lösung: Webseite aus der Firefox Chronik komplett löschen, oder in einem privaten Fenster öffnen, dann geht es wieder.

Generell kann es zu verwirrenden Fehlermeldungen kommen, wenn man sich versucht in einer verknüpften Anwendung einzuloggen aber beispielsweise noch als Admin im Master-Realm eingeloggt ist.

=== Logging ===
Um Fehler besser verstehen zu können, kann das Logging angeschaltet werden, siehe auch [https://www.keycloak.org/server/logging].

Dazu müssen im Start Skript <code>bin/start-keycloak.sh</code> folgende Parameter hinzugefügt werden:
<syntaxhighlight lang=shell>
--log-level=ERROR --log=file
</syntaxhighlight>
Also sieht es z.B. so aus:
<syntaxhighlight lang=shell>
./bin/kc.sh start --http-port [...] --proxy edge --log-level=ERROR --log=file &
</syntaxhighlight>
Nach dem Neustart von Keycloak gibt es dann die Datei <code>keycloak/data/log/keycloak.log</code>.

== Links ==
*[http://www.keycloak.org/ Webseite von Keycloak]
*[https://codeberg.org/tpokorra/hs.ansible/src/branch/main/playbooks/keycloak Ansible Playbook für Hostsharing]
*[https://robferguson.org/blog/2019/12/24/getting-started-with-keycloak/ Getting started with Keycloak]
*[https://janikvonrotz.ch/2020/10/20/openid-connect-with-nextcloud-and-keycloak/ OpenID Connect with Nextcloud and Keycloak] von Janik Vonrotz, Oktober 2020
* [https://www.muehlencord.de/wordpress/2019/12/14/nextcloud-sso-using-keycloak/ Nextcloud SSO using Keycloak] von Jörns Blog, Dezember 2019
* [https://youtu.be/bmOp8epgxsM Erklärvideo auf Youtube] zum Einrichten von Keycloak und Nextcloud
* [https://apps.nextcloud.com/apps/sociallogin Nextcloud App Social Login]

----
[[Kategorie:HSDoku]]
[[Kategorie:Installationsanleitungen]]
[[Kategorie:Ansible Playbook]]
[[Kategorie:Software]]
[[Kategorie:SSO]]
[[Kategorie:Java]]

Keycloak installieren

2026-01-12T12:04:37Z

Tim00: /* Gruppen Synchronisation in der Praxis */ Problem mit Gruppenname

== Allgemein ==

Keycloak [http://www.keycloak.org/] ist eine Open Source Lösung, die ein Single Sign On für verschiedene Anwendungen ermöglicht. Dabei ermöglicht es sowohl die Identitätsverwaltung als auch Zugriffsmanagement.

Es kann die Benutzer entweder aus einem existierenden Verzeichnisdienst (LDAP, Active Directory) auslesen, oder die Gruppen und Benutzer auch selber verwalten.

== Technische Details ==
Keycloak ist in Java geschrieben. Bisher lief es in einem Wildfly Server, aber seit Version 17 (Februar 2022) benutzt es Quarkus, welches ein leichtgewichtiges Java Framework ist.

Es gibt ein Ansible Skript, das die Installationsschritte für Keycloak automatisiert durchführt.

Die Quellen für das Ansible Skript können hier eingesehen werden: [https://codeberg.org/tpokorra/hs.ansible/src/branch/main/playbooks/keycloak]

== Installation ==
Was das Ansible Skript macht, lässt sich mit diesen Worten beschreiben:

* Es wird ein Linux Benutzer eingerichtet.
* Es wird eine Postgresql Datenbank eingerichtet.
* Es wird eine Domain aufgeschaltet.
* Es wird Keycloak als Zip Datei heruntergeladen, z.B. [https://github.com/keycloak/keycloak/releases/download/17.0.0/keycloak-17.0.0.zip], und ins Verzeichnis $HOME/keycloak-17.0.0 entpackt.
* Dann werden ein paar Konfigurationen an der Datei <code>keycloak/conf/keycloak.conf</code> vorgenommen, um die Postgresql Datenbank einzurichten, und um den Proxymodus auf edge zu setzen und den Hostname zu setzen.
* Nun wird die Keycloak Instanz initialisiert, mit dem Befehl: <code>keycloak/bin/kc.sh --cache=local --profile=prod build</code>. Hierbei verhindert die Einstellung für den Cache, dass Keycloak versucht über das Netzwerk Verbindungen zu anderen Instanzen herzustellen.
* Es muss der Server einmal gestartet werden, während der Admin Benutzer mit Passwort in einer Umgebungsvariable gesetzt ist, damit der Benutzer eingerichtet wird.
* Es wird Monit konfiguriert, um den Keycloak Service zu starten, der auf einem internen Port lauscht.
* Es wird der Apache in der htaccess Datei konfiguriert, damit die aufgeschaltete Domain über Proxy auf den Keycloak Dienst verweist. Dabei ist wichtig, dass der Java Prozess mitbekommt, dass die Seite über https läuft. Dazu wird in der htaccess Datei der Wert X-Forwarded-Proto auf https gesetzt.

=== Keycloak mit Systemd ===

Sofern <code>linger</code> für den User schon verfügbar ist, kann auch Systemd verwendet werden. Zudem sollte im Vorfeld <code>export XDG_RUNTIME_DIR=/run/user/$UID</code> ausgeführt werden um Zugriff auf die Befehle zu erhalten.

Beispiel einer Systemd Konfiguration in <code>.config/systemd/user/keycloak.service</code>
<syntaxhighlight lang=ini line>
[Unit]
Description=Keycloak

[Service]
Type=simple
Restart=on-abort
WorkingDirectory=/home/pacs/xyz00/users/login/keycloak
Environment=PROXY_ADDRESS_FORWARDING=true

# Für den ersten Start, um den Adminuser zu setzen
#Environment=KEYCLOAK_ADMIN=changeme
#Environment=KEYCLOAK_ADMIN_PASSWORD=changeme

# Die Option cache=local kann auch an anderer Stelle gesetzt werden.
# Hauptsache sie taucht auf, da es sonst zu Performance-Problemen wie
# Timeouts kommen kann.
ExecStart=/home/pacs/xyz00/users/login/keycloak/latest/bin/kc.sh start --cache=local

[Install]
# Achtung: multiuser.target würde hier zu Problemen führen
WantedBy=default.target
</syntaxhighlight>
== Beispiel einer Einrichtung ==
Diese Anleitung steht auch als [https://youtu.be/bmOp8epgxsM Video auf Youtube] zur Verfügung.

* Auf https://keycloak.example.org/admin anmelden.

=== Admin User einrichten ===
* Der auf der Kommandozeile angelegte Benutzer ist nur vorübergehend gültig.
* Bitte einen permanenten Admin User anlegen, mit den entsprechenden Rollen (role_admin und role_default-roles) ausstatten
* Login mit permanentem Admin durchführen
* Dann den temporären Benutzer löschen.

=== Realm einrichten ===
* Es soll nicht mit der master Realm gearbeitet werden, sondern sollte eine weitere Realm eingerichtet werden, z.B. "MeineFirma"
* Diese neue Realm wird dann ausgewählt

=== Benutzer einrichten ===
* Innerhalb der neuen Realm wird dann ein neuer Benutzer angelegt.
* Beim neuen Benutzer kann ausgewählt werden, dass die E-Mail bereits bestätigt ist.
* Nach dem Speichern des Benutzers kann man dann auch bei Credentials das Passwort setzen. Wenn es nur temporär ist, muss der Benutzer es bei der ersten Anmeldung ändern.
* Nun kann man sich als Administrator abmelden und sich als der Benutzer anmelden, auf https://keycloak.example.org/realms/MeineFirma/account/#/
** Achtung: in anderen Anleitungen heißen die URLs /auth/realms usw, aber auth scheint nicht mehr Teil der Standardeinrichtung zu sein.
* Als Benutzer kann man sein Passwort ändern.
* Wieder abmelden, und wieder als Administrator anmelden.

=== Client einrichten ===
* Achtung: erst aus der Master Realm in die vorher angelegte Realm wechseln, z.B. "MeineFirma"
* Nun sollte ein Client hinzugefügt werden, also eine beliebige Anwendung, die mit Keycloak zusammenarbeiten soll
** Als Client-Protokoll wählt man "OpenID Connect"
** Die Client-ID kann so aussehen: my-nextcloud
** Anwählen: 'Client Authentication', um den OID Typ auf 'Confidential Access Type' zu setzen.
** Anwählen: 'Standard Flow', 'Implicit Flow' und 'Direct Access Grants'
* Eine Root Url eingeben, z.B. https://nextcloud.example.org
* Eine Valid Redirect URI eingeben, z.B. https://nextcloud.example.org/*
* Gültige Web Origins eingeben, z.B. https://nextcloud.example.org
* Speichern
* Unter Roles eine neue Rolle mit Namen admin anlegen.
* Wieder unter den Client Nextcloud gehen, und bei "Client Scopes" klicke auf "my-nextcloud-dedicated", und wähle dort "Add predefined Mapper". Wähle "client roles", und klicke auf "Add". Dann diesen neuen Mapper "client roles" Bearbeiten, und Client ID auf "my-nextcloud" setzen, und "Token Claim Name" mit "roles" setzen, und "Add to userinfo" auf "ON" stellen. Dann Speichern.
* Dann zu nochmal zu Client Scopes (im Client) gehen, und auf "my-nextcloud-dedicated" klicken, und dort im Reiter "Scope" die Option "Full Scope Allowed" abschalten.

* Dann unter Configure / Realm Settings, in General, bei Endpoints auf "OpenID Endpoint Configuration" klicken, dann wird eine Seite geöffnet, auf dieser URL: https://keycloak.example.org/realms/MeineFirma/.well-known/openid-configuration; diese Seite offen halten, wir brauchen daraus die Daten für die Nextcloud Einrichtung

=== Nextcloud einrichten (Einfach) ===
* Als Administrator anmelden, und bei den Apps die App [https://apps.nextcloud.com/apps/sociallogin "Social Login"] installieren.
* Dann bei Einstellungen, unter Verwaltung, Social Login, die gewünschten Einstellungen vornehmen.
* Es sollte ein Kreuz sein bei: Anlegen eines Kontos verhindern, wenn die E-Mail-Adresse bereits von einem anderen Konto verwendet wird.
* Es sollte ein Kreuz sein bei: Verhindern, dass sich Benutzer ohne gemappte Gruppe anmelden können.
* Speichern
* Dann bei "Benutzerdefinierte OpenID Connect Anbindung" auf das Plus klicken
* Nun die Daten aus der "OpenID Endpoint Configuration" (siehe oben) übernehmen: Authorize URL, Token URL, User info URL, Logout URL
* Client ID: nc (Name des Clients in Keycloak)
* Client Secret: hier kommt das Secret hinein, das in Keycloak im Client unter Credentials "Client Secret" zu finden ist. Das kann über die Zwischenablage kopiert werden.
* Scope: openid
* Speichern

=== Nextcloud einrichten (Fortgeschritten) ===
Die folgende App wird mit Rücksicht auf Keycloak entwickelt und hat daher eine bessere Kompatibilität als das Beispiel oben. Allerdings gibt es hierfür keine Optionen in der Cloud, stattdessen wird die <code>config.php</code> direkt bearbeitet.

==== Plugin-Installation ====

# Als Administrator die App [https://github.com/pulsejet/nextcloud-oidc-login "Nextcloud OIDC Login"] installieren
# Die Nextcloud Konfigurationsdatei unter <code>pfad/zur/nextcloud/config/config.php</code> öffnen und basierend auf dem Readme der App (Link aus Schritt #1) befüllen. Das könnte so aussehen:
<syntaxhighlight lang=php line>
'oidc_login_client_id' => 'nextcloud',
'oidc_login_client_secret' => 'bSIPDNUyTQpxmfOpXdwyoBP8nZDQZVuL', // Client Reiter "Credentials" in Keycloak
'oidc_login_provider_url' => 'https://login.mydomain.de/realms/myrealm',
'oidc_login_end_session_redirect' => true,
'oidc_login_logout_url' => 'https://cloud.mydomain.de/index.php/apps/oidc_login/oidc',
'oidc_login_auto_redirect' => true, // hiermit wird das Login-Formular übergangen um Leute weniger zu verwirren
'oidc_login_redir_fallback' => false,
'oidc_login_disable_registration' => false, // Nextcloud soll neue Keycloak Accounts akzeptieren
'oidc_create_groups' => true,
'oidc_login_attributes' => array(
'id' => 'preferred_username',
'mail' => 'email',
'groups' => 'ownCloudGroups',
'is_admin' => 'ownCloudAdmin',
),
</syntaxhighlight>

==== In Keycloak nochmal alles kontrollieren ====
# Client ID stimmt überein
# unter <code>Capability config</code> ist <code>Client authentication</code> aktiv (damit wir ua. unser Secret bekommen)
# <code>Valid redirect URIs</code> erlaubt </code>https://cloud.mydomain.de/*</code> – oder eine konkretere Adresse. Das Plus übernimmt die Einstellung aus <code>Valid redirect URIs</code>
# <code>Valid post logout redirect URIs</code> erlaubt <code>+</code> oder </code>https://cloud.mydomain.de/*</code> – oder eine konkretere Adresse
# <code>Fine Grain OpenID Connect Configuration</code> steht unter <code>ID Token Signature Algorithm</code> auf <code>RS256</code> (Achtung, hier verrutscht man schnell weil die Einträge sich ähneln)

==== Gruppen Synchronisation über Rollen ermöglichen ====
Hierfür legen wir einen Mapper in <code>nextcloud</code> Client an. Anschließend müssen die tatsächlichen Gruppen mit Roles verknüpft werden. Hintergrund ist, dass Roles eigentlich für Berechtigungsmanagement gedacht sind, und Gruppen eigentlich nur User gruppieren sollen.
# wir wechseln im Client <code>nextcloud</code> auf den Reiter <code>Client scopes</code>
# wir wählen <code>nextcloud-dedicated</code>
# Add mapper -> by configuration
## Type: <code>User Client Role</code>
## Name: <code>ownCloudGroups</code>
## Client ID
### Option #1: <code>none</code> – es werden alle <code>Realm roles</code> abgerufen. Das umfasst allerdings auch die Defaults wie <code>uma_authorization</code>, <code>offline_access</code>, <code>default-user-roles</code> und ist nicht immer gewünscht.
### Option #2: <code>nextcloud</code> hier können im Anschluss roles im Client angelegt und mit <code>Groups</code> oder <code>Realm roles</code> verknüpft werden.
## Multivalued: <code>On</code>
## Token Claim Name: <code>ownCloudGroups</code>
## Claim JSON Type: <code>String</code>
## die folgenden drei Optionen: <code>On</code>

==== Gruppen Synchronisation in der Praxis ====

Option #2: Client ID <code>nextcloud</code>
# wir wechseln im Client <code>nextcloud</code> auf den Reiter <code>Roles</code>
# Create role
## Wunschname
# wir wechseln in <code>Groups</code> (Sidebar)
# Create group
## Wunschname
Wichtig: es muss der Name der Gruppe in Nextcloud genommen werden, der in der URL der Gruppe erkennbar ist; nicht der DisplayName
# In der Gruppe wechseln wir auf den Reiter <code>Role mapping</code>
## Assign role
## Im Dropdown welchseln wir auf den Filter <code>by clients</code>
## Wir wählen die gewünschte Rolle
## Unten Links, button <code>Assign</code>

Ab hier können wir die Gruppe normal zuweisen.

=== Benutzer einrichten ===
* Einen Benutzer im Keycloak einrichten, in der Realm "MeineFirma".
* Den Benutzer bearbeiten, und unter "Role Mappings", "Assign Role", "Filter by Clients", wähle "my-nextcloud admin" und klicke auf "Assign".

== Fehler beheben ==

Problem: Gerade beim Experimentieren kommt schon mal die Meldung: "expected expression, got end of script"
* Lösung: Webseite aus der Firefox Chronik komplett löschen, oder in einem privaten Fenster öffnen, dann geht es wieder.

Generell kann es zu verwirrenden Fehlermeldungen kommen, wenn man sich versucht in einer verknüpften Anwendung einzuloggen aber beispielsweise noch als Admin im Master-Realm eingeloggt ist.

=== Logging ===
Um Fehler besser verstehen zu können, kann das Logging angeschaltet werden, siehe auch [https://www.keycloak.org/server/logging].

Dazu müssen im Start Skript <code>bin/start-keycloak.sh</code> folgende Parameter hinzugefügt werden:
<syntaxhighlight lang=shell>
--log-level=ERROR --log=file
</syntaxhighlight>
Also sieht es z.B. so aus:
<syntaxhighlight lang=shell>
./bin/kc.sh start --http-port [...] --proxy edge --log-level=ERROR --log=file &
</syntaxhighlight>
Nach dem Neustart von Keycloak gibt es dann die Datei <code>keycloak/data/log/keycloak.log</code>.

== Links ==
*[http://www.keycloak.org/ Webseite von Keycloak]
*[https://codeberg.org/tpokorra/hs.ansible/src/branch/main/playbooks/keycloak Ansible Playbook für Hostsharing]
*[https://robferguson.org/blog/2019/12/24/getting-started-with-keycloak/ Getting started with Keycloak]
*[https://janikvonrotz.ch/2020/10/20/openid-connect-with-nextcloud-and-keycloak/ OpenID Connect with Nextcloud and Keycloak] von Janik Vonrotz, Oktober 2020
* [https://www.muehlencord.de/wordpress/2019/12/14/nextcloud-sso-using-keycloak/ Nextcloud SSO using Keycloak] von Jörns Blog, Dezember 2019
* [https://youtu.be/bmOp8epgxsM Erklärvideo auf Youtube] zum Einrichten von Keycloak und Nextcloud
* [https://apps.nextcloud.com/apps/sociallogin Nextcloud App Social Login]

----
[[Kategorie:HSDoku]]
[[Kategorie:Installationsanleitungen]]
[[Kategorie:Ansible Playbook]]
[[Kategorie:Software]]
[[Kategorie:SSO]]
[[Kategorie:Java]]

Diskussion:OpenLDAP

2026-01-08T07:21:56Z

Tim00:

== Konfiguration der Overlays ==

add olcOverlay={0}refint,olcDatabase={1}mdb,cn=config
objectClass: olcConfig
objectClass: olcOverlayConfig
objectClass: olcRefintConfig
objectClass: top
olcOverlay: {0}refint
olcRefintAttribute: memberof member manager owner uniqueMember

add olcOverlay={1}memberof,olcDatabase={1}mdb,cn=config
objectClass: olcMemberOf
objectClass: olcOverlayConfig
objectClass: olcConfig
objectClass: top
olcOverlay: {1}memberof
olcMemberOfDangling: error
olcMemberOfRefInt: TRUE
olcMemberOfGroupOC: groupOfUniqueNames
olcMemberOfMemberAD: Member
olcMemberOfMemberOfAD: memberOf

--[[Benutzer:Tim00|Tim00]] ([[Benutzer Diskussion:Tim00|Diskussion]]) 08:21, 8. Jan. 2026 (CET) wurde nun auf der Seite angepasst

OpenLDAP

2026-01-08T07:20:54Z

Tim00: /* memberof Overlay */

== OpenLDAP installieren ==

Voraussetzung: Das Debian-Paket "slapd" ist auf dem Managed Server vorinstalliert.

<syntaxhighlight lang="bash" line>
#!/bin/sh

BASE_DIR="${HOME}/slapd2"
BASE_DN="dc=example,dc=com"

INITIAL_PASSWORD="myInitialPassword"

BIND_IP_ADDR="127.0.0.1"
BIND_IP_PORT="12345"

############################################################################

# Fail, if base directory already exists

if test -e ${BASE_DIR}; then
echo "Initialization failed." >&2
echo "Base directory already exists." >&2
exit 1
fi

# Create directory

mkdir -p -m 700 ${BASE_DIR}
mkdir ${BASE_DIR}/etc
mkdir ${BASE_DIR}/run
mkdir ${BASE_DIR}/var

# create initial configuration:
# cd ~/slapd2/etc && tar -cz . | base64
# see also /etc/ldap/slapd.d on a clean bookworm install, with apt-install slapd
# need to insert BASE_DIR, BASE_DN, and INITIAL_PASSWORD

# Unpack initital configuration

cd ${BASE_DIR}/etc
cat <<EOF |base64 -d |tar -xz
H4sIAAAAAAAAA+xdW3PbOJbOM38FppIqO1WJmnfJ6doHtexktevbWHZvet4oEpY4oUgNSSX2dPV/
3wOAuPACiraV7FZ1qyttSYTE7+AcnDug0U+vvvvDhMfY816Zjmf69hj+2mPPdun71eOV5Vn22DX9
sWu9Mi3L9+xXyPv+0F692hVlkCP06uHx3yf++2yL0yQKtu1x9PqPAPRjH6OfwvQ/wiy9j1ffTRIY
/80B/Lcsy4ZxluNZzl/8/xEPlf/wrAjXeBMcWBKG8990HN8H/nugCf7i/494dPMfnv1u/hFmOR4l
UXz/wnsQBvumjv+OD6u9zn/btMfWK2QehMI9jz85/1+j6d3t1ftPZ5dnN9Pbs1P0cX5+ht6j0yt0
eXWLzk7nt3/7G7orMCLTsslAGh5Hxms0u5k5Nhrfh2a0NH0jSj8gKTRGtvwnDstZEhTFB5Ql4YKK
1YyKmRHCWDEwCadlmcfLXYlvH7e4oJeOkT3yRu7IRpfTizN09CXNviU4WuF5ep/lm6CMs/QInZ4t
Zujo5uPMtj3/A4JBBmLDUKyOO/v73fR8fvsbCoMCz1cp3PciKMM1Wvx2eTv9jKyRM/JHFtzPGlmu
D08tb2TZ1siAS5b3O0irP/kDve0EawmwLgN7jI4KuOlRscvTYIOP0NsmUJiVEh3fGyjYxMnjW0SG
HRdvEUBG39YxACvXGOG0jMtHFBeEsG8pWj4eocXdNR2twWILLF41cQXO4yC53G2WOG9NGLuIUrhq
IJyj7F65cd+03f2yuL1R3l7slgVASVdFNcBAe2YW3nJ/913dpDqCEF9MaghzGma7tMwfL5vz6nrW
yQdUfsveGyjBZQnEzBdX7x3L91H1GfgbYWUG9/Ee/rMIIfPLT+dn73+dnt+dacC6AuxYgE0AbJKF
QQIz2UJbSUEWggSQAYLpwGu2cFCOizjCBcjxXqZ74vYTKYAlEcAyKPFVfp1nX+M0xG0YBmJiQMYh
kL1tNfJleHyB50TBk2PMMJEn0yiCLyyak2IgioaMQAEbwmRS4HiSUBqoKZb7We79btnapT4WlFmm
IC0DqrJ8FaTxv6m66eS2gUALKoNqc7vESQYYUZntnduJRGBJBLsGhCC5S+OyDsRAQvDqQ9EOxj4X
z4nEw1U16I4Et1QNfReBNcjCGKQtQqCp43Jd0zd77mVJs2C5Qr0Febj+tIuj9i3ZNbTaxQaK8Dv4
t81xSG++fISbrgMQ9WihfsN+AbE9HTppByyufJe7Ik5BiGdw01WWP7Yg0gGgekHOQzHmBWqXwDfQ
CyTckhbEqjTv0TYDBZGIJdsggV1FAcxxNaAD/3lclBoayKUOOgy0z3xYOhKk7bDGNRJmWYeUVPiJ
cTDQiydfhUydh9bku6Z27qUdsSYK8Kv7+zjEv2QPLezXcBXBZQPBAERHHAK/gXqEpwe/NETWCce/
fixisIKnOIm/4vyR0cI0U8sOXVeDER+N2HDExg8mDRbUXuY8dV1Io2abXNHhBG/XWYo13tUtvW4g
GIH4EEFD48M1QhrXarQYaBA1nglOq5YYacdsSyHmoYeQB0oC8RKHaEnP1t1aGjDbVm5d4odbnG9i
sEfziNiD+7gBxEAcCoxFfDBSRw/ApVUa0pDZjjCs90FYxOCi49smq+HSA7OtBqrN1Uf+EXT8MXh4
i8QnhQj0o6RKg8yNxsFXQiNuAx+ANp12/kwIR+QqtTKKAILTD95/uKCSVRO/2hXdQgIdoZ1lxye6
QEeBtJM2t5NxCg57Wvkj8eL0slMQiQ9VGwku/ukljV5qS2sgZcC4JysJQpmvpUzaTpvbzhyvwL7h
HEc6DpERBmJjhDHlY4lHVDO/AzC6wBsdQmkabW4awakvYzaj8zQC9VtmbQ0QEenhw4AJYtwzzc1A
LQYhYo9OtqW9tIW9zPE9zmEquQm5wOU6izokSYwEv7CyNptq7ABj4aKFjAsNpIsMbWkS7RMJsQCd
RadS61TR5cpHSXkQ093xJb0yDMtVmVZHRa/FLk2ew01esdtusxw86Ol2mxAZgNvPMliTD6VCA5hz
5oDz0SiQw8HTqsYLYljYITV5gxID6dfjRAdemjiHm7gN7rRu7G0SZwZolWcQNG7ZwotiIvIQPhRr
HF32JF2kTXO4Tcu+pR23ou+i4yrNkoE5JYS/feLtpKlyHK5msgRfheFuG6Rl+67VBQi54M5k6NNu
6Eib43C9titwPsM54RcJXDrsjmeewA3JOBTKge/IO+jnJaiSeqgjh5w9BGHZKcwG6hABnQQ40s44
XNeF0/2YZxBAHQyxS1EPRSzth8P1WbADlZRDdHyDv2ZsAZGAqUOfMfRiPNgV/gGUwCcaZPSqOFi/
BOeJDqe0Ig5Xasps9CBlPhxDqnziuVhhZvmcarFKG+FyJRbmGYTk8vbXQdxeqp9BY1KYZHAN7BaG
P2U2mcEwkKmDKG2EawvXcwUmqUolHa3SjuzhfZwTt+FwuWNH6nvXEY5ZXMZB0jZQ/ALRKAXolQ3N
HwZJQt4gNyneIfhylGYlxVPlwgHoaD8Qqbtd7uOuMGhOKiF/34GL2IoOCKY0MECZo3/xAdxPAR1H
VLv4hv0ApEJ3uYv64JnmXRr/a4c18YkUGpNk1GAgipWRQm8s47LmmQ5YiL4Op7QELlfMUc8EgbNc
TQ6L47TO29XN6dkNeAjKhas8wi1/ml820IB0SId3p8unS4PjctXdma5r0IdTA7FRSu5vYFpPFxi6
SnlHOplZmYVZ0leLIh4cG6UpRXV8yRM8OF186CoVIK7vmDRedHs/lahuMKwd1Q0iTpDAqn7DQO6S
+FDLX2lAPO6crTPQqD1Li14Hh6JzTT0312XsSQj11v1caVo8u+UfJytihtebtuosdgYSfrEybMCC
0Vk5V5oQzxFxXVIGvV4DhHXAdRjVtL8/P9W6aXFJk+JxTR5tomb6r9LexIbco9OL0yNSdutX0a60
ET5X0dsC76Isfdzw7wZHwzaP3XL9FtYjvwjeHTGVzAFnJaU95sAl5sAcnYxsx7VH1oltmo5pjizy
bySTRZsgJkW//D6c2PYFvFiCXnyoWW7S4PCB1GFgBGJDYADqEuT51GOiiqQ0g72XV5sijYZoOR8i
Um3+wj3poZPnaoDQiBRiowzohdhvs81SkCISdjQI/cm23THIGB0IUR8dmXZX8AS1lFYD3dSvPd22
2L4McQ2kD3I9s4+33PjIstUppeZIzfsxplZkKgUuWt7qqVp+D5o1RBIbBtdHExfIshzPPSGLdiQr
iLgSXvpXJCWOtgb6EhYn1VWFv449MT+gBK+C8BEF/H50YdHBPGNBC8bgd1SpC+BE3xw8dQY6Ciwg
4TJjdCV7UGptJb5oK6laA1rKKEDiClEOJazkLQKAd7Pbu5vpObq4W9yiEF1Mf4PZU2qQ6A3o1CLM
4y1Vpm+7cVgCB1fWvFOgA4i8RJAYgKWOhEFgNfM3gAVPkyKjz1RUBbmYtOAZ3QBtAZBrbbVk3AaZ
ypIyWGjuYTeRkjnLKsAkL3ANt/uW5VEbrCBiSTIItRIqvKnku+FVK8PKiGzlNOFtmlXrSg/CNaX+
Ub3qLElU16paQOUzvUGaBDZcQboaAmVKxbWqykfLeL9kD9U7rGApXkjy9EW1GqdJCnGfKDqC014H
p1kfgYbfBmo2EfSwfbeX72CXa5x/Id8NVOf8C/lO0ZUtDur53s92YI3K+Jeync1d9xLvZLsr2C6K
/DgvupY24hc4a40Wc0H9pHDbkNytk8vteZN8NobA9QTccaeUXmvAg5xCaFprdlHJYc/b2pT1qnQK
HOjfgapmkMAB4waqmkGKBhzEgapmkMQBul5VA6taiJ2Gc77g3KSTczdZR69Ql36Raesu/QKyx1in
1xEgaAdhWcUwcO1fzDJFR5CuRd0SUZP7vTglkw10GMVSMRkE4SnaZSyYztPDNKFwdU++sh0QV/kG
mjkkLbHgNB6Dy/hWz+5jXrSpaZ0Ok2Eo08iKL5XUZsMomQhKeMPfEWuETEn2U692YBBPVezXOYSi
RE8DE2kpvk9yeHSiYjzP4dGJtIGGGL4hkkvl1kCHkFyhmTRe7olkLs9CKXXK6zwLu0qzwN0A1pes
Z275wL3KSZHFXW01wdf1xgsycBFdlgrSs6p9ch9Qtc2ye1V1VJXrS8xAPRXgmtISq2ygzrBkUGSJ
FNZi2qEsojiHT5K1UTzCOtgAqGAFqNFxQBraQQwqzdGaoqal79pUoEEnIyLRehrhryBrXQCrCz2R
o5QI2Z1fn76msuLTCP7MnomULr3oQ4XllaWr6a5cExlgU3JXdDbYBIgNppVEOZq6dFJ0pnef5+fz
6c1vjJ5GNVgDTDqdorVU1tWIxPHaZWtODRKQK98fyJEaRMdIUzkl8kyqH93VSnJ1WqOEMqqrYqgh
Urqqovm0Mn6seqQ3gWCzmRGsUvIpt4SwkiPEPq20u/WaR/gKA4mU/V4zOcBI0rheK3PSzROdq0Qm
FjjcERb0FErAtQhYl0BRDa7XSzr4y1ZOO9OuRTdWBE+mfjpF7/2vNrsnu0wi8vqAFpCOPLsWiOJO
iML5zflpXLAEGrE6WZx2xdEGErxVWKmtugPj9PIPiMH8D8UsraRofI02UZ/wVRl+YnafmO3pjflp
kHsQ54e6PorLcogQDPTy3qj/CRGYdPcGJnv2W1hbSX9yf2f7JW7aAW8yJvro+r/nUueTMLW1Bgcp
fVuaddHvCzedTVu3JDes6XgD9Wp5Klg9Sr65NEDkdUr+jUbBa0iSvoBdK7bNbs4VqlzPdnivC72M
ZjewinW0dKqRzts7NJkvqwC2Z8IrYeuTYAmyF93dzK+q2oPal2eOTz7wbT7lOihpN14QpwUtiMGH
lGx++bgFL4ZNtPxWmJaKApAKSUM3VldbXVH2CMCK2SaY24oKNXx5o2zGhkkzoVbvND6J0Dnd6LzG
TNJagiN6TqKwNYO8pGWgelFrH5go1EDwFQjkL1+YoBvbN3fGcHO4Qu9moD7iY0IzqJxdWO7yIFHu
296Ni0mh4+5ufvoBLZcTZxKG4fvxPXbeW6Zrvp+Ydvg+Wi4t9yQ8CZ1lYIQ5Jiq2IDqI7vkNItCb
78QucjYA38bgv5TBZvsBxM72Tcscm2P4Sv8f7I6zxWXzysgdu77j/eM12xf+uvoHD4PuOwaVrL8r
25ncc9f/643W/08f+v3/9h9pXBxi+/+e/f+W63lec/+/5fh/7f//EY8X7v+PIheHeCn2/1OhGbD9
vxqn2f0vdSKt6oouwDATwdMtGKxPZ7OrBQK9kEQ/gwWDwI7o5A04Qaluy9gTSs4Gemqrgb7RwGoR
xX2HdbbBpzynoRIXLIss2ZWEqG1Atspm1EiT8TIJ0qCRtiJLEjvAG+g58O0WfFeUrldxuljjJFGx
S8AEPh2DCjboiXgbaA00CK/TwityIesgyr6dB0U5WwfpShUS4tmvSHJgMJrxECxuC4tfw3IRp00Q
FQRjUFPPIBBeC8S4DiJ4+P4g/BaISQ3E/wR5CouvA4iBDsqScQvISQ3IPAWxhHCrjcRAhxWOSQuJ
qDQwKGcPW1jr339KTtpArBqQj0nQxZnBm7mGwbDa2l/kvFnR5y6OOpWIgTo0O9cvT++mgmBJ109l
tZW5yFkzjJdxcYnLZhst6+BrqLyXYDXQ3t4vq625RQY7lShv83grK7H0XZaPLKsLDRDkP3Ok29Jg
tdWviE/j7QLnJEF+neVlS54MdGDla7W1r8g+SyhVL/b+IyjaalSkeeMt/5rWZm+gDczK6tCGxWrr
U5F+zdLwZht2IfkeWsxqK1QR3sfb/8yKsr6jd37NOwQ1Zy48xSXwezfutxWsyGPGWxD0b1n+pQUu
hfdB/vMvhwK3APW0fxbbOlhk6ijWTVB0Yt2ALSh+LFa7w0sXejoIGxtbL6YzsYnV6O93finD7bZy
Fmm6ZZaV10EO67uUU5hvwxG5sIVJhEsR+K5iRKfW020VsduqVuzRJzf4GEsN+wu8RvEmWNE6DyiH
l/rFOv1vt1Wx2JwO+v8i2LJu/H0Hi7XVqNhBzr7mjLXLtqgw0IGMnTyRjQiACYg6NFNXy68K2x7x
xb/NivhhGtI+X86VKcFCPL+Mdo7d0xo6G8Laua+vFvPPMkVa9NQfQ9ITR/Jw9P9Kr+iKvKqe12I/
XblERljk0yQEHto311wK9qju0jXJj6K4arci6XJOJG3rZh+AtcFg6SknJLfJYB2KjdBLvAURkHwe
PIjnVTwgXnO3HKjnbzH3WLwkTurAckhrbmxVMj4x361DLu5pOVq0LFXy0dP/UcmC5HuDz+AUVpwW
Du4wEppL2xY5BeHZdFEAQj0nOzZwDqYDcaeF9k4ofQtaOmoOXPUa3DbVj6oorJGga0OtE+C2nCk9
D4CMa7GNbgDsuntWn2JyZMYwzE0P0Jad09Tl0uAFtFdgVmc/3VzP0JLsTCVx7h7MqhPXEgkIAIfg
bfqI9sivOWY6vKCbyP7id9U815tadPpO9fWEmLdbV0DSgxRsn7bG1nQn7dG46bPpcINko8qDo6P2
ikXNBxSgub9loC9i/puF1r1kNH1PW+Q7UjVA7CKE9kWkYsje3rJWLCfUCY1FQZ0zjTVIsTT9UFuk
R5itF5DZruo4JLlKBp4cd8Xk53K+gPnpwS7dj2Err5UasGWuBL6rXi+b0n63nHSTABZjP5pKHhRn
RrxiZ2MoIEW/nraTrQFTePEY44lpn9Zax6bV4kIQchAnI0Cqu6ypF0sfu6djrYHCVpzRYJlgDYzq
ZEYySvrCWiDHiPu2pINDdbCpdD2vBhkFrl2vQeIfWIP0fWvy56lB6ut/zh8xaKAsX7Gm5RdUAvvr
f6bnjpvnf9u2+9f53z/k8bL638RfBlY0MUX9ryE0AyqBrU9oTwS3fLaFlWxiHTu07UVENGGQn4P2
SotaS+74xECTD+grXschaKiEjSBnlbBOsrzq4U7ogUADDhSAUH3g8Z+tGN3SHh2rJY5r7AiDIi43
oLPq6R92qO/4BEgUByMUtAWZj6e6PE5rezS1Z6LzksKTjzodTqutp9XlrIziAhjy2DgmwECMUHlw
G81XlBlaYhJKRejbGqeo+jAJG4mKj3H3ibSHpXVQyszRks7DNrzZJtkjbh0oaqCKydUBhkGSPNYY
Ds5O9dEh/JbnCDz3aNvaHLAjK+ksDDwqvWsO3MYc3NLuM/WMWDoDpCmN+JdsGJVwkp6Q+xQHHgpC
sruHlGuv5xwBn3up/9zi1fU6I+dqtwgL0H9dn31iOcFBJ9bojhHz9WKmHEHIltB5kK529IYED8Qc
R0KfyGX2LY/LEhN5QsU2+wLPkupj/VMPkdihRIwV5IaJ2FgvYuJEHNKbfjG/OKsfB2cgxW5MSEvq
bPF6jBbxKsXRaVAGTM2Axqm6z9HiJ/ItGnYZqH72bO+R7p0a0VKP2yNoLLtDctj0B0mlEeod9O9o
L+9sgV6D+3/98fOw49S8vgMU2lBl7oxY8qt81d4ZV2Gd87TTVX1b7rWyRa5rb29z645Bm3+jWNM2
Lp0BGvDWjSd5S1oYeIU3ZJuUVLz0LamFaO6uOo2tytle0xN9q+eNPWkx2XvBDkd7g8SKJ+kD2UNL
MgdxoiQQ4Fm2ZDEUGbqt3tzSj5JsZ55lG2WfEIQ34LQ+yhRzoxn7DSIHlu0aB5axrngD1Rd/9fHm
gqjeZmL3glgO3y/deix3/wNjubHlj/88sdxzHvr4z/ojzMjSenkLaH/8Z/uW7zT7P33b/iv++xGP
l8V/2Ly3fNubiPiPC82AwE8O1UR82sOoxMnxD+VZSn66Ibq6ESVn45A/4tBxfqvl9Z2iZfXgFtUN
sM+KcWT7G0jnITmiUndg4FNpGdS3R2gxXX0xvYcY5UAwuOkXeib+14zszcCnJEVK3mqdfUaGkBGo
+sxQ6p53wmQ/p5w+l10crMzNrsovEooCMeRi+/j57/JjWf2U6LfZyDbPbSPuYPwwKhfj+JMDvHl4
OyjycAALqG0dmr5QSN0dSlVDDRE4iYCJ/xIO3QtbvGBuBzYm9s+t30MNj6fWWe1wRTa1a3oIB90j
tCsPcFzl/t/16aFi3EOFKKJUzmidEgO59ORYYIa4LihpHSG+d2WSY0wZXt0Rpn2nLYpCSpSFO+LR
104MlfEb40DrGF5CBP/kfn4YL8wK9fGj76hFUafhUG/VX9SiKT9GHzun6Ek0tSgCPX0omqw+ky0P
daiw/gq+N98PbiCVbV/ZlecTZqDDMsvqs+nyPIgKK9sqXsuoMLrYImJbVjXE7VlPfT+6ol1PVp8R
F225HMx5tQG144jLhJ8Rq2CHYD1ekU3TAzhEmhS/03Ky+my5LX+rT8TuR+x56+ClDpeF7rcR28Db
9r62Q1zZPbL/t5z2E060JTnIuae3WUu1aPXiyYJaLl0VSWXE8zS7gYZJYp9nILpHs3JN5rA6HJfd
ENZR36/y6M4ftvqMt2iDDG5wmOWRJkV+iCZMq8/8ij7KzWkbiLJmDgKkz7iKH9HZfP7+QP63vWvr
bduGwn3WryD60q1rEt0dB8hD2nSDh1yMKEX3Vujm1qsiu760yYb+9/GQIkVRIqXYilF05ksckRIp
kTw3nvMdLdYw9zYJnnwgthYAmIfiXJ/VRiKKB72MRMdleBKbGP5IY8H6Q99j0fGMMjkJBzsuj+oa
OB71w5GRkZMCSVlPcbqFYCopjq3jC04pvktW3AZZknABOT1X90yX9CxEkety00yXGngF4bCDHQ+I
UqQhvBk/PigSt26gpmBq2Q8ft3Ucwi3xqqmx/AX7cQuINi1svLCvd2TkWITsk5HTI1IlI7d1fEpI
CjOn6hf9SyBm8P7QvTQ9R+gqvAhxQX0ILyQJhPqddTzRLWH1Y8ivPFlM0zzJHt6Aq7WBGhKAF+al
oh3P+a0MAy/f00BP5uug47YcZkQ+pGmQvKuKrN6W0OEksmUP6liz2wwTHazC1ZrEckkTIqWaXpJ2
HWmMgZ5EV3B0HJ/n0fk7zNMVl0JrqvefUE0O8SJF1t12nAHwh34UvL/2rbR2Zy5i4gGPycF+msfp
deH6Xps1cjg55+3QbF6AsXUIF1Qmn3R0MgXPrROtpxn4xovOP8J3Z1lCWLNN2BVeV30tJZ144TLx
IgnOSE4mEdjQQExECs4Qr+0wnmEn9AOdYMDzAi3x98vSi/RrmvERGPJSCEgjRFo9aqAkx6SBWoeq
4/g8O9ByHQF82uU0n96t7+gwDPRQW7gBbYeKho8ZMGbRndJiOjpeLSQCogMO7zsOmDZ8kgHrGC1P
F8SkQHB2wTR6kTbIwGMmKfJGjzo3MJDt6DKuKcfILWyj25uUIp/wD2kgrmyMblFZvaGJupJlS6lW
ODoW6TEWSfxTpBknEKvEb+WX9UEWfuv04Vz9eYurY2ieLxn4xusog2/RZDCfs7rNbK+bHtKpnY1U
2HFuKRJPs9mKeQ+9yNNvY3zBQPzSr1qkfzhemlJIyPpJMnjdkGROBsvVRBAeyzPO/LPsmMOPtQrf
oDoMJL6KVRXZZ0h06Knoa1ocS+r4hJUv0fVJFFzAm0iwpnEvowZo7kaNAu5vkPMK9yVZkBDGXhII
QxebqppevoNYfGo1aMdAZdhOMYMMi1UMziqBRVkOHQZpL7zTFYm+rr0o5D3h/l5qdFS1SOMeyhtP
egusdpRvUT/OYgivBM2qGInu9QykfkHt61UOmfj/EB9anNAIbejRhnCBnRYIlzh90UWtqr4Zk1Nh
U+lQcIXPQr9TZReqvpOM5apcmzrYyqE0rUFKfcxLUMxajJ482Nbx5Tzi0EDapauZWU0qFSUiZ3lG
R21z6m1XSf+Wrxgca8Ug2Dxc/vIkUrDRe1OVxKoWFy9+GpKjAj/jejFezL5OcwEjF4B3O+YM4AkG
gJfR5jI8r4jdKz9bif9rIAk4eCQmAqmDDLdAEmOSVeZuUDMIBTJyDUSZROeLqVM02VyUi4dJaTS9
IZmccbgoyF4COYIBMrXGgisUrkgT3L6HMX0SmFenGdXNp4EePaO6+TQeP6O6+cTyx2NntNt8qjUD
VzgZvgrOBXpQJDo06jNZHJHgri/Py59/8Z9XAf8ZXJeN30A3WMWn/2siqZUjHVTI1k0KwVwlfK4s
5EJkDAVAXtCW4NCPL8pET4pwZ7QNb70iC6Q6dlo5UmblqNgzWZbBGBC3iNVS5iBS8yuO09IYIq3q
neMeEZn5uhIdFLwz0BjPoUiwG3kLCNTViRctNpqIaOWoLHFU55DygyyzZQgdYZ4jdFVaUjRBz8qO
mG7+hT7iAtzxMxrYAYYPFXTzMmR9sswDdVsE4Vqiym8gXrO553wUTaQo6GSHnvPesWvtPed//iL6
/+MFCdshwgo9eHLfJdFRL33Awhl4yvhvKIX/v4WXCb5uDSzPf4a8XnpvKf9z/39p/l+H8WfMbE7/
NWH6e0H/LuI/XFc5/77js/gPz3NNmH/fc/bxH7so28V/xAnmsQPTIvEfteVTCwIpqgt+V14g9j64
Qc0pq7cKrNL0BkmSRPGB6w5TzCqd+GCYTJyDIcCIOL6FRYB0M1Zpm46Dl6LnWDKrFGoOPXvoDcz+
WGWl16effyX9P7C+TxaQ2i1PtiUDLfgflm3L+B+W5e7x/3dSttv/Voy3GN54bP83Lp8aGWCtGB2Q
qn8v7ivJBLsB04nKc7P4LIbsi4R+YD3uJYoeUJIfpgAvecoh907N39blb9h/8zRd4C2fwO/0nijy
mYHgP3DQLkId4GH4iZgyfK50ZUFXvJfnz2k73Kw6IrtoRr7Hc/xoOBwh8r50RzD9J72Y3k1XJ8jD
ZENNA6XvJukLA9OU9IVhi77Qg5rgHA87giXttYMfskjxv3h61lmKd1NPoh8pLfQfz71fpf+WP3D3
8t9Oynb0f2LHtj+JLRb/y5dPjahfkhpwgSXRv0JDVjcOV59O0NF6uTjKptERdFdWXsxCKiVGWA78
oBcVha4kEjkZmmGFRDrmLsEIXNP/4UwqjfH/fW7+Z+3737dcef/bWF3c7/8dlC3j/6PE8YduyPY/
XT7twf9Fu80Mo4OJbBiNdpmizvkBd/HmRW//64cQtOl/Prf/mb7veYD/gVXA/f7fRdlu/3uuF0Z+
6NT1P6vRANSi+V0mUaPSVzwMX4s4Xv4Jen0WvP1wPro5+houiB61nkym9+z6VV09BOT+5WnFjwAr
Yss0mxCUM6Lwhfksf7ibrZckVJcqavhSWtcA6dNqqPa1J6pUw5fVSngEllxO0O3Nu7dw4WY2W51f
CZREeC+oG78/QaOr0e3o7OLD+CwI3l/fnNNv9OZTGn+eQy5prFFaNnJMen2UJ+k9SwBLHdXSL5Wq
OH8FiFLSVa48vypR7KUmFGz6VQlhz+ovw3vQb08QpnPOwLWObVcnuvEFUKX5rhVZZlVys3ZI84/t
wc8KI6Wk/+Z3erUHFtBG//HKYOc/pjswgf57lren/7so29F/14nj2HLdOv1ny6eVBVQIfXnXTk17
NVJbbmAdsd3YUheGUo7l8Oktda41sPeWun2RikD/e9b6y9Jq/3NsLv/jdYr1f9fxB3v6v4uyJf1P
3MSyJ0Om/yto/h/ZLMJUGDR/gb4vPi4hcYQgyC/W+dEyC+fJYYgriVQ8+0iCz064ED6eJsq75lMi
St/OZtntJxCscfeWhkwX45LIs39spVXyfLyDgxTf7pj5fk+e92Vf9qWf8h+KyuNkAMgAAA==
EOF

# Patch configuration files

sed -e"s%BASE_DIR%${BASE_DIR}%" -i $(find -name \*.ldif)
sed -e"s%BASE_DN%${BASE_DN}%" -i $(find -name \*.ldif)
sed -e"s%INITIAL_PASSWORD%${INITIAL_PASSWORD}%" -i $(find -name \*.ldif)

# Fix CRC32 checksums on configuration files

for FILE in $(find -name \*.ldif); do
CRC32=$(tail -n +3 ${FILE} |crc32 /dev/stdin)
sed -e"s/^# CRC32 [0-9a-f]*$/# CRC32 ${CRC32}/" -i ${FILE}
done

# Add Root DSE

DC=$(echo ${BASE_DN} |cut -d "," -f1 |cut -d "=" -f2)

cat <<EOF |/usr/sbin/slapadd -F "${BASE_DIR}/etc" -b ${BASE_DN}
dn: ${BASE_DN}
dc: ${DC}
objectClass: domain
objectClass: top
structuralObjectClass: domain
EOF

# Print instructions

cat <<EOF

Instructions
============

Launch slapd (debug level 0 - foreground mode)
$ /usr/sbin/slapd -h "ldap://${BIND_IP_ADDR}:${BIND_IP_PORT}/" -F "${BASE_DIR}/etc" -d 0

LDAPvi on cn=config
$ ldapvi -h "ldap://${BIND_IP_ADDR}:${BIND_IP_PORT}/" -D "cn=admin,cn=config" -b "cn=config"

LDAPvi on ${BASE_DN}
$ ldapvi -h "ldap://${BIND_IP_ADDR}:${BIND_IP_PORT}/" -D "cn=admin,${BASE_DN}" -b "${BASE_DN}"

Do not forget to update the intitial passwords for both identities:

cn=admin,cn=config
cn=admin,${BASE_DN}

EOF
</syntaxhighlight>

== Basis-Struktur ergänzen ==

=== Organizational Units ===
Für viele Anwendungsfälle – wie eine Synchronisation mit [[Keycloak installieren|Keycloak]] – wird empfohlen noch zwei <code>Organizational Units</code> zu ergänzen:

'''Editor starten mit:'''
<syntaxhighlight lang=bash>ldapvi -h "ldap://127.0.0.1:12345/" -D "cn=admin,dc=example,dc=com" -b "dc=example,dc=com" </syntaxhighlight>

'''Oben die folgenden Zeilen ergänzen:'''
<syntaxhighlight lang=bash line>
add ou=users,dc=example,dc=com
objectClass: organizationalUnit
objectClass: top
ou: users

add ou=groups,dc=example,dc=com
objectClass: organizationalUnit
objectClass: top
ou: groups
</syntaxhighlight>
Nun den Editor schließen und noch mit <code>y</code> bestätigen.

=== memberof Overlay ===

Um Gruppenmitgliedschaften auch beim User anzuzeigen (mit ldapsearch ... memberof), müssen die Overlays memberof und refint installiert werden.

<syntaxhighlight lang=bash>
export LDAP_PORT=12345
mkdir -p ~/ldif

cat > ~/ldif/add-memberof-modules.ldif << FINISH
dn: cn=module{0},cn=config
changetype: modify
add: olcModuleLoad
olcModuleLoad: memberof.la
olcModuleLoad: refint.la
FINISH

ldapadd -H ldap://127.0.0.1:$LDAP_PORT -D "cn=admin,cn=config" -f ~/ldif/add-memberof-modules.ldif -W

cat > ~/ldif/add-memberof-overlay.ldif << FINISH
dn: olcOverlay=memberof,olcDatabase={1}mdb,cn=config
objectClass: olcMemberOfConfig
objectClass: olcOverlayConfig
objectClass: olcConfig
objectClass: top
olcOverlay: memberof
olcMemberOfDangling: error
olcMemberOfRefInt: TRUE
olcMemberOfGroupOC: groupOfUniqueNames
olcMemberOfMemberAD: uniqueMember
olcMemberOfMemberOfAD: memberOf
FINISH

ldapadd -H ldap://127.0.0.1:$LDAP_PORT -D "cn=admin,cn=config" -f ~/ldif/add-memberof-overlay.ldif -W

cat > ~/ldif/add-refint-overlay.ldif << FINISH
dn: olcOverlay=refint,olcDatabase={1}mdb,cn=config
objectClass: olcConfig
objectClass: olcOverlayConfig
objectClass: olcRefintConfig
objectClass: top
olcOverlay: refint
olcRefintAttribute: memberof
olcRefintAttribute: member
olcRefintAttribute: uniqueMember
olcRefintAttribute: manager
olcRefintAttribute: owner
FINISH

ldapadd -H ldap://127.0.0.1:$LDAP_PORT -D "cn=admin,cn=config" -f ~/ldif/add-refint-overlay.ldif -W
</syntaxhighlight>

== Autostart ==

Um den neuen LDAP-Dienst dauerhaft laufen zu lassen, sollte [[Systemd]] genutzt werden. Hier ein Beispiel dafür:

<syntaxhighlight lang=bash>
mkdir -p .config/systemd/user
</syntaxhighlight>

In das Verzeichnis die Datei <code>slapd.service</code> legen und mit beispielsweise den folgenden Inhalten befüllen:

<syntaxhighlight lang=ini line>
[Unit]
Description=Slapd2 Server

[Service]
Type=forking
Restart=always
WorkingDirectory=%h/ldap/

# eg -d 255 for higher loglevel; but even with -d 0, it won't fork anymore
ExecStart=/usr/sbin/slapd -h ldap://127.0.0.1:12345/ -F %h/slapd2/etc
PIDFile=%h/slapd2/run/slapd.pid

[Install]
WantedBy=default.target
</syntaxhighlight>

Im Anschluss:
<syntaxhighlight lang=bash>
systemctl enable --user slapd
systemctl start --user slapd
</syntaxhighlight>

'''Hinweis:''' unter Umständen muss ein Administator diese Funktionalität erst für Sie freischalten. Ihr User benötigt womöglich außerdem die folgende Umgebungsvariable um die Befehle ausführen zu können:
<syntaxhighlight lang=bash>
export XDG_RUNTIME_DIR=/run/user/$UID
</syntaxhighlight>

== Pflege der LDAP Daten über die Kommandozeile ==
=== Benutzer anlegen ===

Datei adduser.ldif (entsprechende Werte ersetzen):

<syntaxhighlight lang=bash line>
dn: uid=mmustermann,ou=users,dc=example,dc=org
objectClass: inetOrgPerson
cn: Max
sn: Mustermann
uid: mmustermann
userPassword: TopSecret1234
mail: mmustermann@example.org
</syntaxhighlight>

Dann ausführen:
<syntaxhighlight lang=bash>
ldapadd -H ldap://127.0.0.1:$PORT -D "cn=admin,$BASE_DN" -W -f adduser.ldif
</syntaxhighlight>

=== Passwort von Benutzer ändern ===
<syntaxhighlight lang=bash>
export PORT=30389
export BASE_DN="dc=example,dc=org"
ldappasswd -H ldap://127.0.0.1:$PORT -x -D "cn=admin,$BASE_DN" -W -S "uid=mmustermann,ou=users,$BASE_DN"
</syntaxhighlight>

=== Nach Benutzern suchen ===

<syntaxhighlight lang=bash>
export PORT=30389
export BASE_DN="dc=example,dc=org"
ldapsearch -x -b "$BASE_DN" -H ldap://127.0.0.1:$PORT # geht sogar ohne Benutzer
ldapsearch -x -b "$BASE_DN" -H ldap://127.0.0.1:$PORT -D "cn=admin,$BASE_DN" -W
ldapsearch -x -b "$BASE_DN" -H ldap://127.0.0.1:$PORT -D "cn=admin,cn=config" -W
</syntaxhighlight>

Was kann der normale Benutzer sehen:
<syntaxhighlight lang=bash>
ldapsearch -x -b "$BASE_DN" -H ldap://127.0.0.1:$PORT -D "uid=mmustermann,ou=users,$BASE_DN" -W
</syntaxhighlight>

nach Personen mit bestimmter Klasse suchen:
<syntaxhighlight lang=bash>
ldapsearch -x -b "$BASE_DN" -H ldap://127.0.0.1:$PORT -D "cn=admin,$BASE_DN" -W "objectClass=inetOrgPerson"
</syntaxhighlight>

=== Eigenschaften aktualisieren ===

Datei modify_email.ldif:
<syntaxhighlight lang=ldap line>
dn: uid=mmustermann,ou=users,dc=example,dc=org
changetype: modify
replace: mail
mail: mmustermann2@example.org
</syntaxhighlight>

Dann ausführen:
<syntaxhighlight lang=bash>
ldapmodify -H ldap://127.0.0.1:$PORT -D "cn=admin,$BASE_DN" -W -f modify_email.ldif
</syntaxhighlight>

=== Neue Gruppe anlegen ===

Siehe oben, das Overlay memberof sollte installiert sein.

Datei addgroup.ldif (entsprechende Werte ersetzen):

<syntaxhighlight lang=bash line>
dn: cn=admins,ou=groups,dc=example,dc=org
cn: admins
objectclass: groupOfUniqueNames
uniqueMember: uid=mmustermann,ou=users,dc=example,dc=org
</syntaxhighlight>

Dann ausführen:
<syntaxhighlight lang=bash>
ldapadd -H ldap://127.0.0.1:$PORT -D "cn=admin,$BASE_DN" -W -f addgroup.ldif
</syntaxhighlight>

=== Benutzer zu einer Gruppe hinzufügen ===

Datei addmember.ldif (entsprechende Werte ersetzen):

<syntaxhighlight lang=bash line>
dn: cn=admins,ou=groups,dc=example,dc=org
changetype: modify
add: uniqueMember
uniqueMember: uid=mmustermann,ou=users,dc=example,dc=org
</syntaxhighlight>

Dann ausführen:
<syntaxhighlight lang=bash>
ldapmodify -H ldap://127.0.0.1:$PORT -D "cn=admin,$BASE_DN" -W -f addmember.ldif
</syntaxhighlight>

=== Liste alle Benutzer einer Gruppe ===

<syntaxhighlight lang=bash>
export FILTER="(&(objectClass=inetOrgPerson)(memberof=CN=admins,OU=groups,DC=example,DC=org))"
ldapsearch -x -b "$BASE_DN" -H ldap://127.0.0.1:$PORT -D "cn=admin,$BASE_DN" -W $FILTER
</syntaxhighlight>

=== Benutzer aus einer Gruppe entfernen ===

Datei dropmember.ldif (entsprechende Werte ersetzen):

<syntaxhighlight lang=ldap>
dn: cn=admins,ou=groups,dc=example,dc=org
changetype: modify
delete: uniqueMember
uniqueMember: uid=mmustermann,ou=users,dc=example,dc=org
</syntaxhighlight>

Dann ausführen:

<syntaxhighlight lang=bash>
ldapmodify -H ldap://127.0.0.1:$PORT -D "cn=admin,$BASE_DN" -W -f dropmember.ldif
</syntaxhighlight>

=== Benutzer löschen ===

<syntaxhighlight lang=bash>
ldapdelete -H ldap://127.0.0.1:$PORT -D "cn=admin,$BASE_DN" -W "uid=mmustermann,ou=users,$BASE_DN"
</syntaxhighlight>

=== Gruppe löschen ===

Datei delete_group.ldif:

<syntaxhighlight lang=ldap>
dn: cn=Test,ou=groups,dc=example,dc=org
changetype: delete
</syntaxhighlight>

Dann ausführen:
<syntaxhighlight lang=bash>
ldapmodify -H ldap://127.0.0.1:$PORT -D "cn=admin,$BASE_DN" -W -f delete_group.ldif
</syntaxhighlight>

== Links ==
*[https://www.vincentliefooghe.net/content/openldap-setup-multiple-instances-server Ein Setup für mehrere OpenLDAP Instanzen auf einem Server]

----
[[Kategorie:HSDoku]]
[[Kategorie:Installationsanleitungen]]
[[Kategorie:Software]]