Setup:Installation Guide/Docker

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

PDF exclude - start

---

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

PDF exclude - end