Setup:Installation Guide/Docker: Difference between revisions

Revision as of 13:37, 4 June 2025

Overview

Since version 4.5, BlueSpice MediaWiki can be easily installed using a stack of Docker container images. Everything is build in a modular way to allow different types of setups.

The most common cases are

"All-in-one" (with and without Let's Encrypt)
Custom database and search service
Custom load balancer / proxy

Architecture

Notes

Internal HTTP connections may use non-standard ports. Those are noted next to the respective services.
- HTTP (in-secure) is only used for internal communication within the virtual network the stack is operated in. All connections to the client use TLS.
Proprietary ports (esp. for database connections) are noted next to the respective services.
There may be additional services and ports in use, based on the setup. Some examples:
- When using LDAP based authentication an LDAPS connection (port 636) is used from the bluespice/wiki containers to the LDAP-Server
- When using Kerberos authentication, a connection (port 88) is used from the bluespice/kerberos-proxy containers to the Kerberos-Server
- When using DeepL or OpenAI services, a HTTPS connection (port 443) is used from the bluespice/wiki containers to to the respective service
- When using OpenIDConnect authentication, a HTTPS connection (port 443) is used from the bluespice/wiki "task" container to to the authentication provider
- When using "Let's Encrypt" Certbot, a HTTPS connection (port 443) is used from the acme-companion container to the "Let's Encrypt" service

Step 1: Get the stack

Get "docker-compose" files from https://github.com/hallowelt/bluespice-deploy

Example:

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

PRO and FARM editions All services configurations for PRO and FARM edition are already included, but the main application image bluespice/wiki needs to be obtained differently. See Pro and Farm edition for details

The directory contains the following files:


Filename	Type	Mandatory	Comment
`bluespice-deploy`	bash-script	false	Wrapper for general start-up of needed containers
`bluespice-prepare`	bash-script	false	Prepare Folder and Permissions before first start also registers the service at the operating system
`bluespice.service`	service-script	false	Proper handling of the containers on reboot
`docker-compose.main.yml`	yml	true	Main application services/ run by `bluespice-deploy`
`docker-compose.persistent-data-services.yml`	yml	false	Database and search/ run by `bluespice-deploy`
`docker-compose.stateless-services.yml`	yml	true	PDF-Renderer/Cache/Formula/Diagram-Service
`docker-compose.proxy.yml`	yml	false, but recommended	Proxy Service
`docker-compose.proxy-letsencrypt.yml`	yml	false	Additional auto-renewal service for "Let's Encrypt" certificates
`docker-compose.kerberos-proxy.yml`	yml	false	Additional proxy for Kerberos based authenication

For convenience, the bluespice-deploy script wraps the first four yml files by default. This includes the main wiki application and also required backend services, like a database, search and application cache. Additional services can be loaded by adding -f <filename> .

Step 2: Set up environment variables

Create .env file according to existing or state-to-be installation.

Example:

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

Different editions The example shows EDITION=pro. Be aware that for pro and farm you need to be logged into docker.bluespice.com.

Step 3: Prepare data directories

Run bluespice-prepare script, helping you set up correct folder structure and permissions. Also installing a service for proper handling of the containers on reboots. Make sure to run this command with in a privileged user context (like root), as it will set permissions on the newly created directories.

Step 4: Start the stack

Initial installation When starting the stack the first time, the wiki-task container will automatically perform the installation. It may take a couple of minutes for the process to set up the database and complete. Once it is finished, the password for the default Admin user can be found in $DATADIR/wiki/adminPassword.

Use bluespice-deploy up -d to start the stack, once the .env file and the "data directories" are ready. Once all containers are shown as "ready" you can navigate to $WIKI_PROTOCOL://$WIKI_HOST:$WIKI_PORT (e.g. https://wiki.company.local) in your favorite web browser and start using the application.

Additional options

SSL certificates

For using Let's Encrypt certificates just set variable LETSENCRYPT to true in your .env file.

Self-signed certificates For using self-signend Certificates please put <bluespice-wiki.com>.crt and <bluespice-wiki.com>.key with the exact name of your Wikis URL in ${DATADIR}/proxy/certs

Operating system level service

Adding additional services

expand the ExecStart parameter in the /etc/systemd/system/bluespice.service Example:

ExecStart=<WORKDIR>/bluespice-deploy -f docker-compose.proxy-letsencrypt.yml up -f -d --remove-orphans

Custom wiki application configuration

After the initial installation, the ${DATADIR}/wiki/bluespice/ contains two files that can be used to set custom application configuration as it may be found on mediawiki.org:

pre-init-settings.php - Can be used to set config that can be picked up by the init process
post-init-settings.php - Can be used to manipulate configs that have been set by the init process

Custom database and search

If you have a MySQL/MariaDB and an OpenSearch server running in your local network, you can remove docker-compose.persistent-data-services.yml entirely from your bluespice-deploy file. Make sure to set the proper variables in the .env file.

Kerberos proxy

For implicit authenticationusing Kerberos, an additional proxy must be used: bluespice/kerberos-proxy . The file docker-compose.kerberos-proxy.yml contains a common configuration. It can be used instead of the regular docker-compose.proxy.yml file inside bluespice-deploy .

Make sure to have the files

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

set up properly.

The file ${DATADIR}/wiki/bluespice/pre-init-settings.php can then be used to set up "Extension:Auth_remoteuser" and the LDAP stack extensions.

SAML authentication

During the initial installation a certificate for message signing will automatically be created. It can be found in ${DATADIR}/wiki/simplesamlphp/certs/.

In order to configure a remote IdP, one must copy the IdP metadata XML to a file called ${DATADIR}/wiki/simplesamlphp/saml_idp_metadata.xml. The SP metadata can then be obtained via https://{{$WIKI_HOST}}/_sp/module.php/saml/sp/metadata.php/default-sp. It must be configured in the remote IdP.

Test authentication You can test authentication directly within the SimpleSAMLphp application. To do so, navigate to https://{{$WIKI_HOST}}/_sp/module.php/admin and log in with admin and the INTERNAL_SIMPLESAMLPHP_ADMIN_PASS found in ${DATADIR}/wiki/.wikienv

Next, the extensions "PluggableAuth" and "SimpleSAMLphp" must be enabled on the wiki. To do so, add

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

to the ${DATADIR}/wiki/bluespice/post-init-settings.php. Run

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

to complete the installation.

After that, the authentication plugin configuration can be applied in Special:BlueSpiceConfigManager under "Authentication".

OpenID Connect authentication

The extensions "PluggableAuth" and "OpenIDConnect" must be enabled on the wiki. To do so, add

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

to the ${DATADIR}/wiki/bluespice/post-init-settings.php. Run

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

to complete the installation.

After that, the authentication plugin configuration can be applied in Special:BlueSpiceConfigManager under "Authentication".

PDF exclude - start

To submit feedback about this documentation, visit our community forum.

PDF exclude - end

@@ Line 1: / Line 1: @@
 __TOC__
-===Overview===
+== Overview ==
 Since version 4.5, BlueSpice MediaWiki can be easily installed using a stack of Docker container images. Everything is build in a modular way to allow different types of setups.
@@ Line 9: / Line 9: @@
 # Custom load balancer / proxy
-==== Architecture ====
+== Architecture ==
 <drawio filename="Setup:Installation_Guide_Docker-Achitecture" alt="Diagram of BlueSpice Docker Stack Architecture" />
@@ Line 23: / Line 23: @@
 ** When using "Let's Encrypt" Certbot, a HTTPS connection (port <code>443</code>) is used from the <code>acme-companion</code> container to the "Let's Encrypt" service
-=== Step 1: Get the stack ===
+== Step 1: Get the stack ==
 Get "docker-compose" files from https://github.com/hallowelt/bluespice-deploy
@@ Line 89: / Line 89: @@
 For convenience, the <code>bluespice-deploy</code> script wraps the first four <code>yml</code> files by default. This includes the main wiki application and also required backend services, like a database, search and application cache. Additional services can be loaded by adding <code>-f <filename> </code>.
-===Step 2: Set up environment variables===
+== Step 2: Set up environment variables ==
 Create <code>.env</code> file according to existing or state-to-be installation.
@@ Line 119: / Line 119: @@
 {{Textbox|boxtype=note|header=Different editions|text=The example shows <code>EDITION=pro</code>. Be aware that for <code>pro</code> and <code>farm</code> you need to be logged into <code>docker.bluespice.com</code>.|icon=yes}}
-=== Step 3: Prepare data directories===
+== Step 3: Prepare data directories ==
 Run <code>bluespice-prepare</code> script, helping you set up correct folder structure and permissions. Also installing a service for proper handling of the containers on reboots. Make sure to run this command with in a privileged user context (like <code>root</code>), as it will set permissions on the newly created directories.
-=== Step 4: Start the stack ===
+== Step 4: Start the stack ==
 {{Textbox
 |boxtype=important
@@ Line 131: / Line 131: @@
 Use <code>bluespice-deploy up -d</code> to start the stack, once the <code>.env</code> file and the "data directories" are ready. Once all containers are shown as "ready" you can navigate to <code>$WIKI_PROTOCOL://$WIKI_HOST:$WIKI_PORT</code> (e.g. <code><nowiki>https://wiki.company.local</nowiki></code>) in your favorite web browser and start using the application.
-=== Additional options ===
+== Additional options ==
-==== SSL certificates ====
+=== SSL certificates ===
 For using Let's Encrypt certificates just set variable <code>LETSENCRYPT</code> to <code>true</code>  in your <code>.env</code> file.
@@ Line 143: / Line 143: @@
 }}
-====Operating system level service====
+=== Operating system level service ===
 {{Textbox
 |boxtype=tip
@@ Line 160: / Line 159: @@
 * <code>post-init-settings.php</code> - Can be used to manipulate configs that have been set by the init process
-==== Custom database and search ====
+=== Custom database and search ===
 If you have a MySQL/MariaDB and an OpenSearch server running in your local network, you can remove <code>docker-compose.persistent-data-services.yml</code> entirely from your <code>bluespice-deploy</code>  file. Make sure to set the proper variables in the <code>.env</code> file.
-====Kerberos proxy====
+=== Kerberos proxy ===
 For implicit authenticationusing Kerberos, an additional proxy must be used: <code>bluespice/kerberos-proxy</code> . The file <code>docker-compose.kerberos-proxy.yml</code> contains a common configuration. It can be used '''instead of''' the regular <code>docker-compose.proxy.yml</code> file inside <code>bluespice-deploy</code> .
@@ Line 175: / Line 174: @@
 The file <code>${DATADIR}/wiki/bluespice/pre-init-settings.php</code> can then be used to set up [[mediawikiwiki:LDAP_hub|"Extension:Auth_remoteuser" and the LDAP stack extensions]].
-====SAML authentication====
+=== SAML authentication ===
 During the initial installation a certificate for message signing will automatically be created. It can be found in <code>${DATADIR}/wiki/simplesamlphp/certs/</code>.
@@ Line 203: / Line 201: @@
 After that, the authentication plugin configuration can be applied in [[Manual:Extension/BlueSpiceConfigManager|Special:BlueSpiceConfigManager]] under "Authentication".
-==== OpenID Connect authentication ====
+=== OpenID Connect authentication ===
 The extensions "PluggableAuth" and "OpenIDConnect" must be enabled on the wiki. To do so, add<syntaxhighlight lang="php">