Setup:Installationsanleitung/Docker

2025-05-12T14:04:15Z

Fmarkl:

{{Textbox
|boxtype=important
|header=Migration von 4.4
|text=Mit BlueSpice 4.5 gab es einige wichtige Änderungen am Container-Portfolio:
# Es gibt keine „All-in-One“-Container mehr. Weder für die ''free'' noch für die ''pro'' oder ''farm'' Editionen
# Das „Distributed-Services“-Setup für die ''pro'' und ''farm'' Editionen wurde komplett überarbeitet.
Wenn Sie von einem der oben genannten Setups aktualisieren, lesen Sie bitte den [[{{FULLPAGENAME}}/Migration_4.4 to 4.5|Migrationsleitfaden]].
|icon=yes
}}

__TOC__

===Übersicht===
Seit Version 4.5 kann BlueSpice MediaWiki einfach mithilfe eines Stapels von Docker-Container-Images installiert werden. Alles ist modular aufgebaut, um verschiedene Arten von Setups zu ermöglichen.

Die häufigsten Fälle sind
#„All-in-one“ (mit und ohne Let’s Encrypt)
#Benutzerdefinierte Datenbank und Suchdienst
#Benutzerdefinierter Load Balancer / Proxy

===Schritt 1: Den Stack abrufen===
Von https://github.com/hallowelt/bluespice-deploy die „docker-compose“-Dateien abrufen.

Beispiel:
<syntaxhighlight lang="text">
wget https://github.com/hallowelt/bluespice-deploy/archive/refs/heads/main.zip \
&& unzip main.zip \
&& cd bluespice-deploy-main/compose
</syntaxhighlight>

{{Textbox|boxtype=important|header=PRO edition Stack|text=Aktuell ist nur der FREE edition Stack auf GitHub verfügbar. Wir planen auch den PRO Stack zu veröffentlichen. In der Zwischenzeit, kontaktieren Sie bitte unser Sales-Team, wenn Sie den PRO Stack zur Selbstinstallation benötigen.|icon=yes}}

Das Verzeichnis enthält die folgenden Dateien:
{| class="wikitable"
|+
! style="width:350px;" |Dateiname
! style="" |Typ
! style="" |Pflichtfeld
! style="" |Kommentar
|-
| style="width:350px;" |<code>bluespice-deploy</code>
| style="" |bash-script
| style="" |false
| style="" |Wrapper für den allgemeinen Start der benötigten Container
|-
| style="width:350px;" |<code>bluespice-prepare</code>
| style="" |bash-script
| style="" |false
| style="" |Ordner und Berechtigungen vor dem ersten Start vorbereiten, registriert den Dienst auch beim Betriebssystem
|-
| style="width:350px;" |<code>bluespice.service</code>
| style="" |service-script
| style="" |false
| style="" |Richtige Handhabung der Container beim Neustart
|-
| style="width:350px;" |<code>docker-compose.main.yml</code>
| style="" |yml
| style="" |true
| style="" |Hauptanwendungsdienste/ ausgeführt von <code>bluespice-deploy</code>
|-
| style="width:350px;" |<code>docker-compose.persistent-data-services.yml</code>
| style="" |yml
| style="" |false
| style="" |Datenbank und Suche/ ausgeführt von <code>bluespice-deploy</code>
|-
| style="width:350px;" |<code>docker-compose.stateless-services.yml</code>
| style="" |yml
| style="" |true
| style="" |PDF-Renderer/Cache/Formel/Diagramm-Dienst
|-
| style="width:350px;" |<code>docker-compose.proxy.yml</code>
| style="" |yml
| style="" |false, aber empfohlen
| style="" |Proxy-Dienst
|-
| style="width:350px;" |<code>docker-compose.proxy-letsencrypt.yml</code>
| style="" |yml
| style="" |false
| style="" |Zusätzlicher automatischer Erneuerungsdienst für „Let’s Encrypt“-Zertifikate
|-
| style="width:350px;" |<code>docker-compose.kerberos-proxy.yml</code>
| style="" |yml
| style="" |false
| style="" |Zusätzlicher Proxy für Kerberos-basierte Authentifizierung
|-
| style="width:350px;" |<code>.env.sample</code>
| style="" |text-file
| style="" | false
| style="" |Vorlage für .env Datei
|}

Der Einfachheit halber umschließt das Skript <code>bluespice-deploy</code> standardmäßig die ersten vier <code>yml</code>-Dateien. Dies umfasst die Haupt-Wiki-Anwendung und auch erforderliche Backend-Dienste wie eine Datenbank, eine Suche und einen Anwendungscache.

Zusätzliche Dienste können durch Hinzufügen von <code>-f <filename> </code> geladen werden.

Beispiel:<syntaxhighlight lang="text">
bluespice-deploy \
-f docker-compose.proxy-letsencrypt.yml \
up -d
</syntaxhighlight>Dadurch wird der Stapel mit „Let’s Encrypt“-Zertifikaten gestartet. Weitere Einzelheiten finden Sie im Abschnitt [[#SSL-Zertifikate| SSL-Zertifikate]].

===Schritt 2: Umgebungsvariablen einrichten===
Erstellen Sie die Datei <code>.env</code> entsprechend der vorhandenen oder zukünftigen Installation.

Beispiel:<syntaxhighlight lang="text">
DATADIR=/data/bluespice
VERSION=4.5
EDITION=pro
BACKUP_HOUR=04

WIKI_NAME=BlueSpice
WIKI_LANG=en
WIKI_PASSWORDSENDER=no-reply@wiki.company.local
WIKI_EMERGENCYCONTACT=no-reply@wiki.company.local
WIKI_HOST=wiki.company.local
WIKI_PORT=443 WIKI_PROTOCOL=https

DB_USER=bluespice
DB_PASS=...
DB_HOST=database
DB_NAME=bluespice
DB_PREFIX=

SMTP_HOST=mail.company.local
SMTP_PORT=25 SMTP_USER=...
SMTP_PASS=...
SMTP_ID_HOST=...
</syntaxhighlight>

===Schritt 3: Datenverzeichnisse vorbereiten===
Ausführen Das Skript <code>bluespice-prepare</code> hilft Ihnen beim Einrichten der richtigen Ordnerstruktur und Berechtigungen. Außerdem wird ein Dienst für die ordnungsgemäße Handhabung der Container bei Neustarts installiert. Stellen Sie sicher, dass Sie diesen Befehl in einem privilegierten Benutzerkontext (wie <code>root</code>) ausführen, da er Berechtigungen für die neu erstellten Verzeichnisse festlegt.

===Schritt 4: Stack starten===
{{Textbox
|boxtype=important
|header=Erstinstallation
|text=Wenn Sie den Stapel zum ersten Mal starten, führt der Container <code>wiki-task</code> die Installation automatisch durch. Es kann einige Minuten dauern, bis der Vorgang die Datenbank eingerichtet und abgeschlossen hat. Sobald er abgeschlossen ist, finden Sie das Passwort für den Standardbenutzer <code>Admin</code> in <code>$DATADIR/wiki/adminPassword</code>.
|icon=yes
}}
Verwenden Sie <code>bluespice-deploy up -d</code>, um den Stack zu starten, sobald die <code>.env</code>-Datei und die „Datenverzeichnisse“ bereit sind. Sobald alle Container als „bereit“ angezeigt werden, können Sie in Ihrem bevorzugten Webbrowser zu <code>$WIKI_PROTOCOL://$WIKI_HOST:$WIKI_PORT</code> (z. B. <code><nowiki>https://wiki.company.local</nowiki></code>) navigieren und mit der Verwendung der Anwendung beginnen.

===Zusätzliche Optionen===

====SSL-Zertifikate====
Um Let’s Encrypt-Zertifikate zu verwenden, fügen Sie einfach <code>docker-compose.proxy-letsencrypt.yml</code> in Ihre <code>bluespice-deploy</code>-Datei ein.
{{Textbox
|boxtype=tip
|header=Selbstsignierte Zertifikate
|text=Um selbstsignierte Zertifikate zu verwenden, geben Sie bitte <code><bluespice-wiki.com>.crt</code> und <code><bluespice-wiki.com>.key</code> mit dem genauen Namen der URL Ihres Wikis in <code>${DATADIR}/proxy/certs</code> ein
|icon=yes
}}

Wenn Sie SSL nach der ersten Erstellung des Wikis aktivieren, ändern Sie bitte <code>$wgServer</code> in <code>$DATADIR/wiki/bluespice/pre-init-settings.php</code>

in <code><nowiki>https://bluespice-wiki.com</nowiki></code>

verknüpfen Sie Ihr Zertifikat auch mit dem Bluespice-Container in Ihrer <code>docker-compose.yml</code>-Datei:

<code>- $DATADIR/proxy/certs/<FQDNofyourWiki>.crt:/usr/local/share/ca-certificates/<FQDNofyourWiki>.crt:ro</code>

Bitte starten Sie Container nach dem Ändern/Hinzufügen von SSL-Dateien neu.

====Dienst auf Betriebssystemebene====

{{Textbox
|boxtype=tip
|header=Zusätzliche Dienste hinzufügen
|text=Erweitern Sie den Parameter <code>ExecStart</code> in <code>/etc/systemd/system/bluespice.service</code>
Beispiel:
ExecStart=<WORKDIR>/bluespice-deploy -f docker-compose.proxy-letsencrypt.yml up -f -d --remove-orphans
|icon=yes
}}

====Benutzerdefinierte Wiki-Anwendungskonfiguration====
Nach der Erstinstallation enthält <code>${DATADIR}/wiki/bluespice/</code> zwei Dateien, mit denen Sie eine benutzerdefinierte Anwendungskonfiguration festlegen können, wie sie unter [https://www.mediawiki.org mediawiki.org] zu finden ist:

*<code>pre-init-settings.php</code> - Kann verwendet werden, um eine Konfiguration festzulegen, die vom Init übernommen werden kann Prozess
*<code>post-init-settings.php</code> - Kann verwendet werden, um Konfigurationen zu manipulieren, die vom Init-Prozess festgelegt wurden

====Benutzerdefinierte Datenbank und Suche====
Wenn Sie einen MySQL/MariaDB- und einen OpenSearch-Server in Ihrem lokalen Netzwerk laufen haben, können Sie <code>docker-compose.persistent-data-services.yml</code> vollständig aus Ihrer <code>bluespice-deploy</code>-Datei entfernen. Stellen Sie sicher, dass Sie die richtigen Variablen in der <code>.env</code>-Datei festlegen.

====Kerberos-Proxy====
Für die implizite Authentifizierung mit Kerberos muss ein zusätzlicher Proxy verwendet werden: <code>bluespice/kerberos-proxy</code> . Die Datei <code>docker-compose.kerberos-proxy.yml</code> enthält eine gemeinsame Konfiguration. Es kann '''anstelle''' der regulären Datei <code>docker-compose.proxy.yml</code> in <code>bluespice-deploy</code> verwendet werden.

Stellen Sie sicher, dass die Dateien

*<code>${DATADIR}/kerberos/krb5.conf</code>
*<code>${DATADIR}/kerberos/kerberos.keytab</code>

richtig eingerichtet sind.

Die Datei <code>${DATADIR}/wiki/bluespice/pre-init-settings.php</code> kann dann verwendet werden, um „Extension:Auth_remoteuser“ einzurichten.

====SAML-Authentifizierung====

Während der Erstinstallation wird automatisch ein Zertifikat zur Nachrichtensignierung erstellt. Es befindet sich in <code>${DATADIR}/wiki/simplesamlphp/certs/</code>.

Um einen Remote-IDP zu konfigurieren, muss man die IdP-Metadaten-XML in eine Datei namens <code>${DATADIR}/wiki/simplesamlphp/simplesamlphp/saml_idp_metadata.xml</code> kopieren. Die SP-Metadaten können dann über <code><nowiki>https://{{$WIKI_HOST}}/_sp/module.php/saml/sp/metadata.php/default-sp</nowiki></code> abgerufen werden. Sie müssen im Remote-IdP konfiguriert werden.

{{Textbox
|boxtype=tip
|header=Authentifizierung testen
|text= Sie können die Authentifizierung direkt in der SimpleSAMLphp-Anwendung testen. Navigieren Sie dazu zu <code><nowiki>https://{{$WIKI_HOST}}/_sp/module.php/admin</nowiki></code> und melden Sie sich mit <code>admin</code> und dem <code>INTERNAL_SIMPLESAMLPHP_ADMIN_PASS</code> an, der sich in <code>${DATADIR}/wiki/.wikienv</code> befindet
|icon=yes
}}

Als nächstes müssen die Erweiterungen „PluggableAuth“ und „SimpleSAMLphp“ im Wiki aktiviert werden. Fügen Sie dazu in <code>${DATADIR}/wiki/bluespice/post-init-settings.php</code> Folgendes hinzu:

<syntaxhighlight lang="php">
wfLoadExtensions( [
'PluggableAuth',
'SimpleSAMLphp'
] );
</syntaxhighlight>
[[Datei:Installationsanleitung Docker Authentifizierungseinstellung.png|alternativtext=Konfigurationsverwaltung mit ausgewählter Funktion "Authentifizierung"|mini|300x300px|Authentifizierungs-Einstellungen]]
Führen Sie folgenden Befehl aus, um die Installation abzuschließen.<syntaxhighlight lang="text">
./bluespice-deploy exec wiki-task /app/bluespice/w/maintenance/update.php --quick
</syntaxhighlight>Danach kann die Konfiguration des Authentifizierungs-Plugins in [[Handbuch:Erweiterung/BlueSpiceConfigManager|Spezial:BlueSpiceConfigManager]] unter „Authentifizierung“ angewendet werden.

[[en:Setup:Installation_Guide/Docker]]

Benutzer:Fmarkl

2025-05-12T14:03:08Z

Fmarkl: create user page

User blog:Fmarkl

2025-05-12T14:03:08Z

Fmarkl: Haupt-Blogseite erstellt

BlueSpice - Benutzerbeiträge [de]

Setup:Installationsanleitung/Docker

Benutzer:Fmarkl

User blog:Fmarkl