Setup:Installation Guide/Docker: Difference between revisions

No edit summary
Tag: 2017 source edit
No edit summary
Tag: 2017 source edit
Line 192: Line 192:


In order to configure a remote IDP, one must copy the IdP metadata XML to a file called <code>${DATADIR}/wiki/simplesamlphp/simplesamlphp/saml_idp_metadata.xml</code>. The SP metadata can then be obtained via <code><nowiki>https://{{$WIKI_HOST}}/_sp/module.php/saml/sp/metadata.php/default-sp</nowiki></code>. It must be configured in the remote IdP.
In order to configure a remote IDP, one must copy the IdP metadata XML to a file called <code>${DATADIR}/wiki/simplesamlphp/simplesamlphp/saml_idp_metadata.xml</code>. The SP metadata can then be obtained via <code><nowiki>https://{{$WIKI_HOST}}/_sp/module.php/saml/sp/metadata.php/default-sp</nowiki></code>. It must be configured in the remote IdP.
{{Textbox
|boxtype=tip
|header=Test authentication
|text= You can test authentication directly within the SimpleSAMLphp application. To do so, navigate to <code><nowiki>https://{{$WIKI_HOST}}/_sp/module.php/admin</nowiki></code> and log in with <code>admin</code> and the <code>INTERNAL_SIMPLESAMLPHP_ADMIN_PASS</code> found in <code>${DATADIR}/wiki/.wikienv</code>
|icon=yes
}}


Next, the extensions "PluggableAuth" and "SimpleSAMLphp" must be enabled on the wiki. To do so, add
Next, the extensions "PluggableAuth" and "SimpleSAMLphp" must be enabled on the wiki. To do so, add
Line 202: Line 209:
</syntaxhighlight>
</syntaxhighlight>
to the <code>${DATADIR}/wiki/bluespice/post-init-settings.php</code>
to the <code>${DATADIR}/wiki/bluespice/post-init-settings.php</code>
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 [[ConfigManager|Special:BlueSpiceConfigManager]] under "Authentication".
After that, the authentication plugin configuration can be applied in [[ConfigManager|Special:BlueSpiceConfigManager]] under "Authentication".

Revision as of 07:30, 25 October 2024

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

Step 1: Get the stack

Get "docker-compose" files from https://bluespice.com/de/download/

wget https://bluespice.com/filebase/docker-deployment-script \
    && unzip docker-deployment-script \
    && cd docker-deployment-script/compose

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

Example:

bluespice-deploy \
    -f docker-compose.proxy-letsencrypt.yml \
    up -d

This will start the stack with "Let's Encrypt" certificates. For details, please refer to section SSL certificates.

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

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.

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/adminPasssword.

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 add docker-compose.proxy-letsencrypt.yml in your bluespice-deploy 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 ${VOLUMES_DIR}/nginx/certs


If activating SSL after first creation of wiki please change $wgServer in ${VOLUMES_DIR}/bluespice-data/LocalSettings.php

to https://bluespice-wiki.com

also link your certificate to the bluespice-container in your docker-compose.yml-File:

- ${VOLUMES_DIR}/nginx/certs/<FQDNofyourWiki>.crt:/usr/local/share/ca-certificates/<FQDNofyourWiki>.crt:ro

Please restart containers after changing/adding SSL files.

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

SAML authentication

Setup:SAML ConfigManager EN 01.png

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/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".



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