Setup:Installationsanleitung/Docker

2026-06-18T11:35:11Z

Mstrehl: update latest version to 5.2.4

== Ü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

== Architektur ==
<drawio filename="Setup:Installationsanleitung_Docker-Achitektur" alt="Diagramm der BlueSpice Docker Stack-Architektur" />

'''Hinweise'''
* Interne HTTP-Verbindungen können nicht standardmäßige Ports verwenden. Diese sind neben den jeweiligen Diensten angegeben.
** HTTP (unsicher) wird nur für die interne Kommunikation innerhalb des virtuellen Netzwerks verwendet, in dem der Stack betrieben wird. Alle Verbindungen zum Client verwenden TLS.
* Proprietäre Ports (insbesondere für Datenbankverbindungen) sind neben den jeweiligen Diensten angegeben.
* Je nach Setup können zusätzliche Dienste und Ports genutzt werden. Einige Beispiele:
** Bei Verwendung der LDAP-basierten Authentifizierung wird eine LDAPS-Verbindung (Port <code>636</code>) von den <code>bluespice/wiki</code>-Containern zum LDAP-Server aufgebaut.
** Bei Verwendung der Kerberos-Authentifizierung wird eine Verbindung (Port <code>88</code>) von den <code>bluespice/kerberos-proxy</code>-Containern zum Kerberos-Server aufgebaut.
** Bei Verwendung von DeepL- oder OpenAI-Diensten wird eine HTTPS-Verbindung (Port <code>443</code>) von den <code>bluespice/wiki</code>-Containern zum jeweiligen Dienst aufgebaut.
** Bei Verwendung der OpenIDConnect-Authentifizierung wird eine HTTPS-Verbindung (Port <code>443</code>) vom <code>bluespice/wiki</code>-"Task"-Container zum Authentifizierungsanbieter aufgebaut.
** Bei Verwendung von "Let's Encrypt" Certbot wird eine HTTPS-Verbindung (Port <code>443</code>) vom <code>acme-companion</code>-Container zum Dienst „Let’s Encrypt“ aufgebaut.

== Schritt 1: Den Stack abrufen ==
Laden Sie das Projekt bluespice-deploy von https://github.com/hallowelt/bluespice-deploy/releases/latest und wechseln Sie in das Unterverzeichnis <code>compose</code> für Docker Compose-Dateien.

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

{{Textbox|boxtype=note|header=Einheitliche Versionsnummer verwenden:|text=Die Tag-Nummer 5.2.4 in diesem Befehl (könnte auch 5.1.4, 5.1.5 usw. sein) sollte auch als <code>VERSION=</code>-Nummer in Schritt 2 verwendet werden.|icon=yes}}

Das Verzeichnis enthält die folgenden Dateien:
{| class="wikitable"
|+
! style="width:350px;" |Dateiname
! style="" |Typ
! style="" |Pflicht
! style="" |Kommentar
|-
| style="width:350px;" |<code>bluespice-deploy</code>
| style="" |bash-script
| style="" |nein
| style="" |Wrapper für den allgemeinen Start der benötigten Container
|-
| style="width:350px;" |<code>docker-compose.main.yml</code>
| style="" |yml
| style="" |ja
| style="" |Hauptanwendungsdienste/ ausgeführt von <code>bluespice-deploy</code>
|-
| style="width:350px;" |<code>docker-compose.persistent-data-services.yml</code>
| style="" |yml
| style="" |nein
| style="" |Datenbank und Suche/ ausgeführt von <code>bluespice-deploy</code>
|-
| style="width:350px;" |<code>docker-compose.stateless-services.yml</code>
| style="" |yml
| style="" |ja
| style="" |PDF-Renderer/Cache/Formel/Diagramm-Dienst
|-
| style="width:350px;" |<code>docker-compose.helper-service.yml</code>
| style="" |yml
| style="" |ja
| style="" |Verschiedene Hilfscontainers für Dateisystem-Vorbereitung, Major-Upgrades und Backups
|-
| style="width:350px;" |<code>docker-compose.proxy.yml</code>
| style="" |yml
| style="" |nein, aber empfohlen
| style="" |Proxy-Dienst
|-
| style="width:350px;" |<code>docker-compose.proxy-letsencrypt.yml</code>
| style="" |yml
| style="" |nein
| style="" |Zusätzlicher Service zur automatischen Verlängerung von „Let's Encrypt“-Zertifikaten
|-
| style="width:350px;" |<code>docker-compose.kerberos-proxy.yml</code>
| style="" |yml
| style="" |nein
| style="" |Zusätzlicher Proxy für Kerberos-basierte Authentifizierung
|-
| style="width:350px;" |<code>docker-compose.collabpads-service.yml</code>
| style="" |yml
| style="" |nein
| style="" |Backend-Dienst für [[Referenz:CollabPads|CollabPads]] (in den Pro- und Farm-Editionen enthalten)
|-
| style="width:350px;" |<code>.env.sample</code>
| style="" |Text
| style="" |ja
| style="" |Beispiel zum Erstellen von <code>.env</code>, das wichtige Umgebungsvariablen definiert
|-
| style="width:350px;" |<code>bluespice.service.demo</code>
| style="" |service-script
| style="" |nein
| style="" |Richtige Handhabung der Container beim Neustart
|}

== Schritt 2: Umgebungsvariablen einrichten ==
Erstellen Sie Ihre <code>.env</code> aus der Vorlagendatei <code>.env.sample</code>.

Beispiel:
<pre>
# set or use your data directory
DATADIR=/data/bluespice
VERSION=5.2.4
EDITION=free
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
WIKI_BASE_PATH=

DB_USER=set_or_use_your_db_user_name
DB_PASS=SET_OR_USE_YOUR_DB_PASS_WORD
DB_ROOT_USER=root
DB_ROOT_PASS=$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=...

LETSENCRYPT=false
</pre>

{{Textbox|boxtype=note|header=Verschiedene Editionen|text=Diese Konfiguration funktioniert für alle Editionen, das Hauptimage der Pro- oder Farm-Edition muss jedoch auf andere Weise bezogen werden, siehe [[{{FULLPAGENAME}}/Pro und Farm Edition|Pro und Farm Edition]]|icon=yes}}

== Schritt 3: Stack starten ==
Starten Sie den Stack mit <code>bluespice-deploy up -d</code>. 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 die Anwendung nutzen.

Beim ersten Start des Stacks führt der <code>wiki-task</code>-Container die Installation automatisch durch. Die Einrichtung der Datenbank und der Abschluss des Vorgangs können einige Minuten dauern. Das Passwort für den Standard-Administratorbenutzer finden Sie anschließend unter <code>$DATADIR/wiki/initialAdminPassword</code>.

== Zusätzliche Optionen ==

=== Container anpassen ===
Seit Tag 5.1.4 und Tag 5.2.0 des Projekts <code>bluespice-deploy</code> können Sie eine separate <code>docker-compose.override.yml</code>-Datei bearbeiten und verwalten, die von Git ignoriert wird.

So können Sie Ihre eigenen Container-Konfigurationen hinzufügen und Ihren Git-Status aktuell halten. Platzieren Sie die Datei einfach neben den anderen <code>docker-compose.*.yml</code>-Dateien und führen Sie <code>./bluespice-deploy up -d</code> aus.

Beispiel:
<syntaxhighlight lang="yaml">
services:
wiki-web:
volumes:
- /backup/:/data/backup
wiki-task:
volumes:
- /backup/:/data/backup
</syntaxhighlight>

=== Konfigurationen für <code>LocalSettings.php</code> ===
Anstatt die <code>LocalSettings.php</code> für [[mediawikiwiki:Manual:LocalSettings.php|hinzufügende Konfigurationen]] zugänglich zu machen, bietet der Stack zwei Einstiegspunkte. Nach der Erstinstallation können Sie Ihre Konfigurationen in zwei Dateien unter <code>${DATADIR}/wiki/bluespice/</code> hinzufügen:

* <code>pre-init-settings.php</code> – Hier können Sie Konfigurationen festlegen, bevor BlueSpice initialisiert wird (Debug-Protokollierung, Bibliotheken, Skins, Erweiterungen und Standardeinstellungen). Die hier festgelegten Konfigurationen werden vom Initialisierungsprozess übernommen.

* <code>post-init-settings.php</code> – Hier können Sie Konfigurationen festlegen, die nach der Initialisierung vorgenommen wurden und die vom Initialisierungsprozess festgelegten Konfigurationen überschreiben.

Wenn Sie beispielsweise die folgenden Zeilen zu <code>pre-init-settings.php</code> hinzufügen, können Sie die ausgegebenen Debug-Protokolle (falls vorhanden) in <code>${DATADIR}/wiki/bluespice/logs/debug.log</code> lesen:<syntaxhighlight lang="php">
$GLOBALS['bsgDebugLogGroups']['exception'] = "/data/bluespice/logs/debug.log";

$wgShowExceptionDetails = true;

</syntaxhighlight>

=== Wartungsskripte ===
Um [https://en.wiki.bluespice.com/wiki/Setup:Installation_Guide/Advanced/Maintenance_scripts Wartungsskripte] von MediaWiki oder anderen Erweiterungen auszuführen, verwenden Sie bitte den <code>wiki-task</code>-Container, der alle Backend-Aufgaben und -Prozesse verwaltet. Sie können sich auf zwei Arten mit dem Container verbinden:

* Führen Sie im Docker-Compose-Verzeichnis <code>./bluespice-deploy exec -it wiki-task bash</code> aus.

* Alternativ können Sie <code>docker exec -it bluespice-wiki-task bash</code> von einem beliebigen Ort auf dem Host-Rechner ausführen.

Im Container gelangen Sie mit <code>cd /app/bluespice/w</code> in das Wiki-Quellverzeichnis. Dort können Sie Skripte wie <code>php maintenance/run.php update --quick</code>, <code>php extensions/BlueSpiceExtendedSearch/maintenance/updateWikiPageIndex.php</code> usw. ausführen.

=== SSL-Zertifikate ===
Um ein Let's Encrypt-Zertifikat für Ihre Domain zu verwenden, setzen Sie <code>LETSENCRYPT=true</code> in Ihrer <code>.env</code>-Datei.

Um ein selbstsigniertes Zertifikat für Ihre Domain zu verwenden, legen Sie dessen <code>.crt</code>- und <code>.key</code>-Dateien in <code>${DATADIR}/proxy/certs</code> ab. Für <code>wiki.company.local</code> benötigen Sie beispielsweise die Dateien <code>wiki.company.local.crt</code> und wiki.company.local.key.

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

=== OpenID Connect-Authentifizierung ===
Die Erweiterungen „PluggableAuth“ und „OpenIDConnect“ müssen im Wiki aktiviert sein. Fügen Sie dazu<syntaxhighlight lang="php">
wfLoadExtensions( [
'PluggableAuth',
'OpenIDConnect'
] );
</syntaxhighlight>zur Datei <code>${DATADIR}/wiki/bluespice/post-init-settings.php</code> hinzu. 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>Anschließend kann die Konfiguration des Authentifizierungs-Plugins in der [[Handbuch:Erweiterung/BlueSpiceConfigManager|Konfigurationsverwaltung]] unter „Authentifizierung“ angewendet werden.

[[en:Setup:Installation_Guide/Docker]]

Benutzer:Mstrehl

2026-06-08T14:09:46Z

Mstrehl: create user page

User blog:Mstrehl

2026-06-08T14:09:46Z

Mstrehl: Haupt-Blogseite erstellt

BlueSpice Helpdesk - Benutzerbeiträge [de]

Setup:Installationsanleitung/Docker

Benutzer:Mstrehl

User blog:Mstrehl