Setup:Installation Guide/Docker

__TOC__

​

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

<drawio filename="Setup:Installation_Guide_Docker-Achitecture" alt="Diagram of BlueSpice Docker Stack 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 <code>636</code>) is used from the <code>bluespice/wiki</code> containers to the LDAP-Server

** When using Kerberos authentication, a connection (port <code>88</code>) is used from the <code>bluespice/kerberos-proxy</code> containers to the Kerberos-Server

** When using DeepL or OpenAI services, a HTTPS connection (port <code>443</code>) is used from the <code>bluespice/wiki</code> containers to to the respective service

** When using OpenIDConnect authentication, a HTTPS connection (port <code>443</code>) is used from the <code>bluespice/wiki</code> "task" container to to the authentication provider

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

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

​

{{Textbox|boxtype=warning|header=PRO and FARM editions|text=All services configurations for PRO and FARM edition are already included, but the main application image <code>bluespice/wiki</code> needs to be obtained differently. See [[{{FULLPAGENAME}}/Pro and Farm edition|Pro and Farm edition]] for details|icon=yes}}

​

The directory contains the following files:

{| class="wikitable"

|+

! style="width:350px;" |Filename

! style="" |Type

! style="" |Mandatory

! style="" |Comment

|-

| style="width:350px;" |<code>bluespice-deploy</code>

| style="" |bash-script

| style="" |false

| style="" |Wrapper for general start-up of needed containers

|-

| style="width:350px;" |<code>bluespice-prepare</code>

| style="" |bash-script

| style="" |false

| style="" |Prepare Folder and Permissions before first start also registers the service at the operating system

|-

| style="width:350px;" |<code>bluespice.service</code>

| style="" |service-script

| style="" |false

| style="" |Proper handling of the containers on reboot

|-

| style="width:350px;" |<code>docker-compose.main.yml</code>

| style="" |yml

| style="" |true

| style="" |Main application services/ run by <code>bluespice-deploy</code>

|-

| style="width:350px;" |<code>docker-compose.persistent-data-services.yml</code>

| style="" |yml

| style="" |false

| style="" |Database and search/ run by <code>bluespice-deploy</code>

|-

| style="width:350px;" |<code>docker-compose.stateless-services.yml</code>

| style="" |yml

| style="" |true

| style="" |PDF-Renderer/Cache/Formula/Diagram-Service

|-

| style="width:350px;" |<code>docker-compose.proxy.yml</code>

| style="" |yml

| style="" |false, but recommended

| style="" |Proxy Service

|-

| style="width:350px;" |<code>docker-compose.proxy-letsencrypt.yml</code>

| style="" |yml

| style="" |false

| style="" |Additional auto-renewal service for "Let's Encrypt" certificates

|-

| style="width:350px;" |<code>docker-compose.kerberos-proxy.yml</code>

| style="" |yml

| style="" |false

| style="" |Additional proxy for Kerberos based authenication

|}

​

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

Create <code>.env</code> 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=...

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

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

{{Textbox

|boxtype=important

|header=Initial installation

|text=When starting the stack the first time, the <code>wiki-task</code> 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 <code>Admin</code> user can be found in <code>$DATADIR/wiki/adminPassword</code>.

|icon=yes

}}

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

​

=== SSL certificates ===

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

​

{{Textbox

|boxtype=tip

|header=Self-signed certificates

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

|icon=yes

}}

​

=== Operating system level service ===

{{Textbox

|boxtype=tip

|header=Adding additional services

|text=expand the <code>ExecStart</code> parameter in the <code>/etc/systemd/system/bluespice.service</code>

Example: 

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

|icon=yes

}}

​

=== Custom wiki application configuration ===

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

​

* <code>pre-init-settings.php</code>  - Can be used to set config that can be picked up by  the init process

* <code>post-init-settings.php</code> - 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 <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 ===

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

​

Make sure to have the files

​

* <code>${DATADIR}/kerberos/krb5.conf</code>

* <code>${DATADIR}/kerberos/kerberos.keytab</code>

​

set up properly.

​

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

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

​

In order to configure a remote IdP, one must copy the IdP metadata XML to a file called <code>${DATADIR}/wiki/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

​

<syntaxhighlight lang="php">

wfLoadExtensions( [

    'PluggableAuth',

    'SimpleSAMLphp'

] );

</syntaxhighlight>[[File:Setup:SAML ConfigManager EN 01.png|thumb|300x300px]]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 [[Manual:Extension/BlueSpiceConfigManager|Special:BlueSpiceConfigManager]] under "Authentication".

​

=== OpenID Connect authentication ===

​

​

The extensions "PluggableAuth" and "OpenIDConnect" must be enabled on the wiki. To do so, add<syntaxhighlight lang="php">

wfLoadExtensions( [

    'PluggableAuth',

    'OpenIDConnect'

] );

</syntaxhighlight>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 [[Manual:Extension/BlueSpiceConfigManager|Special:BlueSpiceConfigManager]] under "Authentication".

​

[[de:Setup:Installationsanleitung/Docker]]

​