Setup:Installation Guide/Docker

← Installation Guide

• Migration 4.4 to 4.5
• Pro and Farm edition

Overview

Starting with version 4.5, BlueSpice MediaWiki can be installed with a stack of Docker container images.

Everything is built 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

Load project bluespice-deploy from https://github.com/hallowelt/bluespice-deploy/releases/latest and enter the sub-directory compose for Docker Compose files.

For example, run:

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

The directory contains the following files:

Filename	Type	Comment
bluespice-deploy	shell script	Start-up script, wrapping command docker compose and service yml files. Additional service yml files can be loaded by adding -f <filename> .
docker-compose.main.yml	yml	Main containers of the wiki (wiki-web and wiki-task).
docker-compose.persistent-data-services.yml	yml	Containers of database and search services, storing persistent data onto the file system.
docker-compose.stateless-services.yml	yml	Containers for caching, PDF rendering, formula-rendering and diagram editing.
docker-compose.helper-service.yml	yml	Helper containers for file system preparation and automated BlueSpice upgrade. These containers exit automatically after finishing tasks.
docker-compose.proxy.yml	yml	Container of proxy service. Can be replaced by existing proxy/load-balancer infrastructure.
docker-compose.proxy-letsencrypt.yml	yml	Additional service for auto-renewal of "Let's Encrypt" certificates. Only required when using the Let's Encrypt service and having no other TLS termination.
docker-compose.kerberos-proxy.yml	yml	Additional proxy for Kerberos based authentication.
docker-compose.collabpads-service.yml	yml	Containers of back-end services for CollabPads (included in Pro and Farm editions)
.env.sample	text	Sample for creating .env that defines key environment variables.
bluespice.service.demo	service script	Demo-file for control the BlueSpice stack as a systemctl service.

Step 2: Set up environment variables

Create your .env based on the sample file .env.sample.

Example:

DATADIR=/data/bluespice
VERSION=5.1.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=bluespice
DB_PASS=...(mandatory field)
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

If you are deploying pro or farm edition, please run docker login docker.bluespice.com and login with your credentials.

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

Step 3: 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/initialAdminPassword.

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