Setup:Installationsanleitung/Docker

Ü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

1. „All-in-one“ (mit und ohne Let’s Encrypt)
2. Benutzerdefinierte Datenbank und Suchdienst
3. Benutzerdefinierter Load Balancer / Proxy

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 636) von den bluespice/wiki-Containern zum LDAP-Server aufgebaut.
  • Bei Verwendung der Kerberos-Authentifizierung wird eine Verbindung (Port 88) von den bluespice/kerberos-proxy-Containern zum Kerberos-Server aufgebaut.
  • Bei Verwendung von DeepL- oder OpenAI-Diensten wird eine HTTPS-Verbindung (Port 443) von den bluespice/wiki-Containern zum jeweiligen Dienst aufgebaut.
  • Bei Verwendung der OpenIDConnect-Authentifizierung wird eine HTTPS-Verbindung (Port 443) vom bluespice/wiki-"Task"-Container zum Authentifizierungsanbieter aufgebaut.
  • Bei Verwendung von "Let's Encrypt" Certbot wird eine HTTPS-Verbindung (Port 443) vom acme-companion-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 compose für Docker Compose-Dateien.

Beispiel:

wget https://github.com/hallowelt/bluespice-deploy/archive/refs/tags/5.2.1.zip \
  && unzip 5.2.1.zip \
  && cd bluespice-deploy-5.2.1/compose

Einheitliche Versionsnummer verwenden:

Die Tag-Nummer 5.2.1 in diesem Befehl (könnte auch 5.1.4, 5.1.5 usw. sein) sollte auch als VERSION=-Nummer in Schritt 2 verwendet werden.

Das Verzeichnis enthält die folgenden Dateien:

Dateiname	Typ	Pflicht	Kommentar
bluespice-deploy	bash-script	nein	Wrapper für den allgemeinen Start der benötigten Container
docker-compose.main.yml	yml	ja	Hauptanwendungsdienste/ ausgeführt von bluespice-deploy
docker-compose.persistent-data-services.yml	yml	nein	Datenbank und Suche/ ausgeführt von bluespice-deploy
docker-compose.stateless-services.yml	yml	ja	PDF-Renderer/Cache/Formel/Diagramm-Dienst
docker-compose.helper-service.yml	yml	ja	Verschiedene Hilfscontainers für Dateisystem-Vorbereitung, Major-Upgrades und Backups
docker-compose.proxy.yml	yml	nein, aber empfohlen	Proxy-Dienst
docker-compose.proxy-letsencrypt.yml	yml	nein	Zusätzlicher Service zur automatischen Verlängerung von „Let's Encrypt“-Zertifikaten
docker-compose.kerberos-proxy.yml	yml	nein	Zusätzlicher Proxy für Kerberos-basierte Authentifizierung
docker-compose.collabpads-service.yml	yml	nein	Backend-Dienst für CollabPads (in den Pro- und Farm-Editionen enthalten)
.env.sample	Text	ja	Beispiel zum Erstellen von .env, das wichtige Umgebungsvariablen definiert
bluespice.service.demo	service-script	nein	Richtige Handhabung der Container beim Neustart

Schritt 2: Umgebungsvariablen einrichten

Erstellen Sie Ihre .env aus der Vorlagendatei .env.sample.

Beispiel:

# set or use your data directory 
DATADIR=/data/bluespice
VERSION=5.2.1
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

Verschiedene Editionen

Diese Konfiguration funktioniert für alle Editionen, das Hauptimage der Pro- oder Farm-Edition muss jedoch auf andere Weise bezogen werden, siehe Pro und Farm Edition

Schritt 3: Stack starten

Starten Sie den Stack mit bluespice-deploy up -d. Sobald alle Container als „bereit“ angezeigt werden, können Sie in Ihrem bevorzugten Webbrowser zu $WIKI_PROTOCOL://$WIKI_HOST:$WIKI_PORT (z. B. https://wiki.company.local) navigieren und die Anwendung nutzen.

Beim ersten Start des Stacks führt der wiki-task-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 $DATADIR/wiki/initialAdminPassword.

Zusätzliche Optionen

Container anpassen

Seit Tag 5.1.4 und Tag 5.2.0 des Projekts bluespice-deploy können Sie eine separate docker-compose.override.yml-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 docker-compose.*.yml-Dateien und führen Sie ./bluespice-deploy up -d aus.

Beispiel:

services:
  wiki-web:
    volumes:
      - /backup/:/data/backup
  wiki-task:
    volumes:
      - /backup/:/data/backup

Konfigurationen für LocalSettings.php

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

• pre-init-settings.php – 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.

• post-init-settings.php – 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 pre-init-settings.php hinzufügen, können Sie die ausgegebenen Debug-Protokolle (falls vorhanden) in ${DATADIR}/wiki/bluespice/logs/debug.log lesen:

$GLOBALS['bsgDebugLogGroups']['exception'] = "/data/bluespice/logs/debug.log";

$wgShowExceptionDetails = true;

Wartungsskripte

Um von MediaWiki oder anderen Erweiterungen auszuführen, verwenden Sie bitte den wiki-task-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 ./bluespice-deploy exec -it wiki-task bash aus.

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

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

SSL-Zertifikate

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

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

Kerberos-Proxy

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

Stellen Sie sicher, dass die Dateien

• ${DATADIR}/kerberos/krb5.conf
• ${DATADIR}/kerberos/kerberos.keytab

richtig eingerichtet sind.

Die Datei ${DATADIR}/wiki/bluespice/pre-init-settings.php 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 ${DATADIR}/wiki/simplesamlphp/certs/.

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

Authentifizierung testen

Sie können die Authentifizierung direkt in der SimpleSAMLphp-Anwendung testen. Navigieren Sie dazu zu https://{{$WIKI_HOST}}/_sp/module.php/admin und melden Sie sich mit admin und dem INTERNAL_SIMPLESAMLPHP_ADMIN_PASS an, der sich in ${DATADIR}/wiki/.wikienv befindet

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

wfLoadExtensions( [
'PluggableAuth',
'SimpleSAMLphp'
] );

Authentifizierungs-Einstellungen

Führen Sie folgenden Befehl aus, um die Installation abzuschließen.

./bluespice-deploy exec wiki-task /app/bluespice/w/maintenance/update.php --quick

Danach kann die Konfiguration des Authentifizierungs-Plugins in Spezial:BlueSpiceConfigManager unter „Authentifizierung“ angewendet werden.

OpenID Connect-Authentifizierung

Die Erweiterungen „PluggableAuth“ und „OpenIDConnect“ müssen im Wiki aktiviert sein. Fügen Sie dazu

wfLoadExtensions( [
'PluggableAuth',
'OpenIDConnect'
] );

zur Datei ${DATADIR}/wiki/bluespice/post-init-settings.php hinzu. Führen Sie folgenden Befehl aus, um die Installation abzuschließen.

./bluespice-deploy exec wiki-task /app/bluespice/w/maintenance/update.php --quick

Anschließend kann die Konfiguration des Authentifizierungs-Plugins in der Konfigurationsverwaltung unter „Authentifizierung“ angewendet werden.

PDF-Ausschluss - Start

---

Feedback zur Dokumentation ist im Community-Forum möglich.

PDF-Ausschluss - Ende

Protokoll zur Verschlüsselung und Authentifizierung der Kommunikation zwischen Webserver und Browser im World Wide Web.

Tag: XML-Tags, welche beliebig parametrisiert werden können und eine vom Programmierer gewünschte Ausgabe produzieren. Fügt man beispielsweise das <bs:bookshelf>-Tag ein, dann erhält der Artikel die Kapitelnavigation des PDF-Buches, in dem der Artikel verlinkt ist.