Setup:Installation Guide/Docker

Migration from 4.4With BlueSpice 4.5 there were some important changes to the container portfolio:

1. There are no "all-in-one" containers anymore. Neither for FREE, nor for PRO and FARM editions
2. The "distributed-services" setup for PRO and FARM edition has completely been reworked

If you are upgrading from one of the above-mentioned setups, please refer to the migration guide

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

1. "All-in-one" (with and without Let's Encrypt)
2. Custom database and search service
3. 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 editionsAll services configurations for PRO and FARM edition are already included, but access to private docker.bluespice.com is required to obtain the images.

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 editionsThe 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 installationWhen 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 certificatesFor 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 servicesexpand 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 authenticationYou 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".

---

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