BlueSpice - User contributions [en]

Setup:Installation Guide/Docker

2026-02-12T15:08:35Z

Hjing: Add comment on version number

== 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:
# "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 ==
Load project <code>bluespice-deploy</code> from https://github.com/hallowelt/bluespice-deploy/releases/latest and enter the sub-directory <code>compose</code> for Docker Compose files.

For example, run:
<syntaxhighlight lang=sh>
wget https://github.com/hallowelt/bluespice-deploy/archive/refs/tags/5.2.1.zip \
&& unzip 5.2.1.zip \
&& cd bluespice-deploy-5.2.1/compose
</syntaxhighlight>
{{Textbox|boxtype=note|header=Use one consistent version number|text=The tag number 5.2.1 in this command (could be 5.1.4, 5.1.5 etc. as well) should also be used as the <code>VERSION=</code> number in Step 2.|icon=yes}}

The directory contains the following files:
{| class="wikitable"
|+
! style="width:375px;" |Filename
! style="" |Type
! style="" |Comment
|-
| style="width:375px;" |<code>bluespice-deploy</code>
| style="" |shell script
| style="" |Start-up script, wrapping command <code>docker compose</code> and service <code>yml</code> files. Additional service <code>yml</code> files can be loaded by adding <code>-f <filename> </code>.
|-
| style="width:375px;" |<code>docker-compose.main.yml</code>
| style="" |yml
| style="" |Main containers of the wiki (<code>wiki-web</code> and <code>wiki-task</code>).
|-
| style="width:375px;" |<code>docker-compose.persistent-data-services.yml</code>
| style="" |yml
| style="" |Containers of database and search services, storing persistent data onto the file system. Optionally with external MySQL/MariaDB and OpenSearch one can skip loading this <code>.yml</code> in <code>bluespice-deploy</code>. Please then wire your services properly in the <code>.env</code> file.
|-
| style="width:375px;" |<code>docker-compose.stateless-services.yml</code>
| style="" |yml
| style="" |Containers for caching, PDF rendering, formula-rendering and diagram editing.
|-
| style="width:375px;" |<code>docker-compose.helper-service.yml</code>
| style="" |yml
| style="" |Helper containers for file system preparation and automated BlueSpice upgrade. These containers exit automatically after finishing tasks.
|-
| style="width:375px;" |<code>docker-compose.proxy.yml</code>
| style="" |yml
| style="" |Container of proxy service. Can be replaced by existing proxy/load-balancer infrastructure.
|-
| style="width:375px;" |<code>docker-compose.proxy-letsencrypt.yml</code>
| style="" |yml
| style="" |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.
|-
| style="width:375px;" |<code>docker-compose.kerberos-proxy.yml</code>
| style="" |yml
| style="" |Additional proxy for Kerberos based authentication.
|-
| style="width:375px;" |<code>docker-compose.collabpads-service.yml</code>
|yml
|Containers of back-end services for [[Manual:Extension/CollabPads|CollabPads]] (included in Pro and Farm editions).
|-
| style="width:375px;" |<code>.env.sample</code>
| style="" |text
| style="" |Sample for creating <code>.env</code> that defines key environment variables.
|-
| style="width:375px;" |<code>bluespice.service.demo</code>
| style="" |service script
| style="" |Demo-file for control the BlueSpice stack as a <code>systemctl</code> service. One can create e.g a <code>/etc/systemd/system/bluespice.service</code>.
|}

== Step 2: Set up environment variables ==
Create your <code>.env</code> based on the sample file <code>.env.sample</code>.

Example:
<pre>
# set or use your data directory
DATADIR=/data/bluespice
VERSION=5.2.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=set_or_use_your_db_user_name
DB_PASS=SET_OR_USE_YOUR_DB_PASS_WORD
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
</pre>
{{Textbox|boxtype=note|header=Different editions|text=This config works for all editions, but the main image of Pro or Farm edition needs to be obtained differently, see [[{{FULLPAGENAME}}/Pro and Farm edition|Pro and Farm edition]]|icon=yes}}

== Step 3: Start the stack ==
Use <code>bluespice-deploy up -d</code> to start the stack. 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 preferred web browser and start using the application.

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/initialAdminPassword</code>.

== Additional options ==

=== Add Customizations to containers ===
Since tag 5.1.4 and tag 5.2.0 of project <code>bluespice-deploy</code>, we allow to edit and maintain a separate <code>docker-compose.override.yml</code> which will be ignored by git.

This way you can add your own Container-Configurations and be able to maintain your git status up to date. just place the file next to the other <code>docker-compose.*.yml</code> s and run <code>./bluespice-deploy up -d</code>

Example:<syntaxhighlight lang="yaml">
services:
wiki-web:
volumes:
- /backup/:/data/backup
wiki-task:
volumes:
- /backup/:/data/backup
</syntaxhighlight>

=== Configs for <code>LocalSettings.php</code> ===
Instead of exposing the <code>LocalSettings.php</code> for [[mediawikiwiki:Manual:LocalSettings.php|adding additional configurations]], the stack offers two entry points. After the initial installation, you can add your configs to two files in <code>${DATADIR}/wiki/bluespice/</code>:

* <code>pre-init-settings.php</code> - Set configs before the initialization of BlueSpice's debug logging, libraries, skins, extensions and default settings. Configs set here can be picked up by the init process.
* <code>post-init-settings.php</code> - Set configs after the initialization, manipulating configs that have been set by the init process.
For example, if you add the following lines to <code>pre-init-settings.php</code>, you can then read outputted debug logs (if any) in <code>${DATADIR}/wiki/bluespice/logs/debug.log</code>:<syntaxhighlight lang="php">
$GLOBALS['bsgDebugLogGroups']['exception'] = "/data/bluespice/logs/debug.log";
$wgShowExceptionDetails = true;
</syntaxhighlight>

=== Maintenance scripts ===
To run [[Setup:Installation Guide/Advanced/Maintenance scripts|maintenance scripts]] from MediaWiki or from other extensions, please use the <code>wiki-task</code> container, which handles all back-end jobs and processes. You can connect into the container in two different ways:

* run <code>./bluespice-deploy exec -it wiki-task bash</code> in the <code>compose</code> directory for Docker Compose files
* or alternatively, run <code>docker exec -it bluespice-wiki-task bash</code> wherever you are on the host machine

Inside the container you can enter the wiki's code base with <code>cd /app/bluespice/w</code> , where one can run scripts like <code>php maintenance/run.php update --quick</code>, <code>php extensions/BlueSpiceExtendedSearch/maintenance/updateWikiPageIndex.php</code> and so on.

=== SSL certificates ===
To use a Let's Encrypt certificate for your domain name, set <code>LETSENCRYPT=true</code> in your <code>.env</code> file.

To use a self-signend certificate for your domain name, put its <code>.crt</code> and <code>.key</code> files in <code>${DATADIR}/proxy/certs</code>. For example, with <code>wiki.company.local</code> you should prepare <code>wiki.company.local.crt</code> and <code>wiki.company.local.key</code> files.

=== Kerberos proxy ===
For implicit authentication using 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]]

Setup:Installation Guide/Update from 4.5 to 5.1

2026-01-14T09:42:08Z

Hjing: /* External MySQL/MariaDB database */

{{Textbox|boxtype=important|header=Version compatibility|text=
*If you want to update from a BlueSpice version < 4.4, the intermediate step of [[Setup:Installation Guide/Patch Update|updating to 4.4]] is required.
*If you want to update from a Docker container 4.4 to 5.1, first update to 4.5.
|icon=yes}}

== Determine your update scenario ==
With version 4.5 of BlueSpice, there were two options for installation:

=== Container stack (bluespice-deploy) ===
If you have already installed BlueSpice 4.5 as a Docker container, follow the update instructions below to BlueSpice 5:

→ '''[[{{FULLPAGENAME}}/bluespice-deploy|Upgrade from <code>bluespice-deploy</code> installation]]'''

=== Direct installation (classic tarball) ===
If you have already installed BlueSpice 4.5 as a Docker container, follow the update instructions below to BlueSpice 5:

→ '''[[{{FULLPAGENAME}}/Classic_tarball|Upgrade from classic tarball installation]]'''

Based on which of those you are starting from, the update to BlueSpice version 5.1 may require different steps.

{{Textbox|boxtype=warning|header=Create a backup|text=Before performing any of the following steps, make sure to make a backup of all databases and filesystem locations related to the process.|icon=yes}}

== Special cases ==
Before running the database schema updates, based on the previously installed edition of BlueSpice and optionally enabled extensions, some minor changes on the database may be required.

=== Extension:OATHAuth ===
In some cases the [https://github.com/wikimedia/mediawiki-extensions-OATHAuth/blob/master/sql/mysql/tables-generated.sql extension tables] must be added manually to the database before the update.

=== Extension:OpenIDConnect ===

In some cases this patch needs to be applied before the update.<syntaxhighlight lang="sql">
ALTER TABLE openid_connect DROP COLUMN oidc_id;
ALTER TABLE openid_connect ADD PRIMARY KEY (oidc_user);

</syntaxhighlight>{{Textbox|boxtype=important|header=Duplicate keys|text=In case the <code>openid_connect</code> table contains duplicate entries of <code>oidc_subject</code>, you can safely remove all duplicates, that have a tailing slash in the <code>oidc_issuer</code> field.|icon=yes}}

=== External MySQL/MariaDB database ===

If your wiki uses an external database server before update, and you plan to continue using the same external database server after the update, please make sure that the task runner processes of your wiki before update are completely shut down:
* For 4.5 installations with Docker containers, please make sure that:
*# the previous stack is stopped
*# its daemon service <code>bluespice.service</code> is removed/disabled
*# the containers in the previous stack are down, and will not start automatically upon server restart
* For 4.5 installations directly within the Linux system of the host machine:
*# check the Crontab attributes for your root user, comment out job runner / process runner lines
*# check and kill remaining processes

== Collabpads database update ==
The easiest way to update from MongoDB 4.4 to 8.0 is to export and import the databases:

Example:

On Mongo 4.4 run
mongodump --db <dbname> --gzip --archive > /tmp/collabpads_dump.gz
On Mongo 8.0 run
mongorestore --gzip --archive=/tmp/collabpads_dump.gz

== SAML authentication ==
If you were using SAML with the previous version of BlueSpice, you will probably need to re-register the Service Provider with your Identity Provider.

To do so, download the new <code>metadata.xml</code> file from <code>https://<wikiserver>/_sp/module.php/saml/sp/metadata.php/default-sp</code>

[[de:Setup:Installationsanleitung/Update_von_BlueSpice_4.5_auf_5.1]]

Setup:Installation Guide/Docker

2025-10-28T12:20:06Z

Hjing: Bump version 5.1.3

== 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:
# "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 ==
Load project <code>bluespice-deploy</code> from https://github.com/hallowelt/bluespice-deploy/releases/latest and enter the sub-directory <code>compose</code> for Docker Compose files.

For example, run:
<syntaxhighlight lang=sh>
wget https://github.com/hallowelt/bluespice-deploy/archive/refs/tags/5.1.3.zip \
&& unzip 5.1.3.zip \
&& cd bluespice-deploy-5.1.3/compose
</syntaxhighlight>

The directory contains the following files:
{| class="wikitable"
|+
! style="width:375px;" |Filename
! style="" |Type
! style="" |Comment
|-
| style="width:375px;" |<code>bluespice-deploy</code>
| style="" |shell script
| style="" |Start-up script, wrapping command <code>docker compose</code> and service <code>yml</code> files. Additional service <code>yml</code> files can be loaded by adding <code>-f <filename> </code>.
|-
| style="width:375px;" |<code>docker-compose.main.yml</code>
| style="" |yml
| style="" |Main containers of the wiki (<code>wiki-web</code> and <code>wiki-task</code>).
|-
| style="width:375px;" |<code>docker-compose.persistent-data-services.yml</code>
| style="" |yml
| style="" |Containers of database and search services, storing persistent data onto the file system. Optionally with external MySQL/MariaDB and OpenSearch one can skip loading this <code>.yml</code> in <code>bluespice-deploy</code>. Please then wire your services properly in the <code>.env</code> file.
|-
| style="width:375px;" |<code>docker-compose.stateless-services.yml</code>
| style="" |yml
| style="" |Containers for caching, PDF rendering, formula-rendering and diagram editing.
|-
| style="width:375px;" |<code>docker-compose.helper-service.yml</code>
| style="" |yml
| style="" |Helper containers for file system preparation and automated BlueSpice upgrade. These containers exit automatically after finishing tasks.
|-
| style="width:375px;" |<code>docker-compose.proxy.yml</code>
| style="" |yml
| style="" |Container of proxy service. Can be replaced by existing proxy/load-balancer infrastructure.
|-
| style="width:375px;" |<code>docker-compose.proxy-letsencrypt.yml</code>
| style="" |yml
| style="" |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.
|-
| style="width:375px;" |<code>docker-compose.kerberos-proxy.yml</code>
| style="" |yml
| style="" |Additional proxy for Kerberos based authentication.
|-
| style="width:375px;" |<code>docker-compose.collabpads-service.yml</code>
|yml
|Containers of back-end services for [[Manual:Extension/CollabPads|CollabPads]] (included in Pro and Farm editions).
|-
| style="width:375px;" |<code>.env.sample</code>
| style="" |text
| style="" |Sample for creating <code>.env</code> that defines key environment variables.
|-
| style="width:375px;" |<code>bluespice.service.demo</code>
| style="" |service script
| style="" |Demo-file for control the BlueSpice stack as a <code>systemctl</code> service. One can create e.g a <code>/etc/systemd/system/bluespice.service</code>.
|}

== Step 2: Set up environment variables ==
Create your <code>.env</code> based on the sample file <code>.env.sample</code>.

Example:
<pre>
# set or use your data directory
DATADIR=/data/bluespice
VERSION=5.1.3
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=set_or_use_your_db_user_name
DB_PASS=SET_OR_USE_YOUR_DB_PASS_WORD
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
</pre>
{{Textbox|boxtype=note|header=Different editions|text=This config works for all editions, but the main image of Pro or Farm edition needs to be obtained differently, see [[{{FULLPAGENAME}}/Pro and Farm edition|Pro and Farm edition]]|icon=yes}}

== Step 3: Start the stack ==
Use <code>bluespice-deploy up -d</code> to start the stack. 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 preferred web browser and start using the application.

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/initialAdminPassword</code>.

== Additional options ==

=== Configs for <code>LocalSettings.php</code> ===
Instead of exposing the <code>LocalSettings.php</code> for [[mediawikiwiki:Manual:LocalSettings.php|adding additional configurations]], the stack offers two entry points. After the initial installation, you can add your configs to two files in <code>${DATADIR}/wiki/bluespice/</code>:

* <code>pre-init-settings.php</code> - Set configs before the initialization of BlueSpice's debug logging, libraries, skins, extensions and default settings. Configs set here can be picked up by the init process.
* <code>post-init-settings.php</code> - Set configs after the initialization, manipulating configs that have been set by the init process.
For example, if you add the following lines to <code>pre-init-settings.php</code>, you can then read outputted debug logs (if any) in <code>${DATADIR}/wiki/bluespice/logs/debug.log</code>:<syntaxhighlight lang="php">
$GLOBALS['bsgDebugLogGroups']['exception'] = "/data/bluespice/logs/debug.log";
$wgShowExceptionDetails = true;
</syntaxhighlight>

=== Maintenance scripts ===
To run [[Setup:Installation Guide/Advanced/Maintenance scripts|maintenance scripts]] from MediaWiki or from other extensions, please use the <code>wiki-task</code> container, which handles all back-end jobs and processes. You can connect into the container in two different ways:

* run <code>./bluespice-deploy exec -it wiki-task bash</code> in the <code>compose</code> directory for Docker Compose files
* or alternatively, run <code>docker exec -it bluespice-wiki-task bash</code> wherever you are on the host machine

Inside the container you can enter the wiki's code base with <code>cd /app/bluespice/w</code> , where one can run scripts like <code>php maintenance/run.php update --quick</code>, <code>php extensions/BlueSpiceExtendedSearch/maintenance/updateWikiPageIndex.php</code> and so on.

=== SSL certificates ===
To use a Let's Encrypt certificate for your domain name, set <code>LETSENCRYPT=true</code> in your <code>.env</code> file.

To use a self-signend certificate for your domain name, put its <code>.crt</code> and <code>.key</code> files in <code>${DATADIR}/proxy/certs</code>. For example, with <code>wiki.company.local</code> you should prepare <code>wiki.company.local.crt</code> and <code>wiki.company.local.key</code> files.

=== Kerberos proxy ===
For implicit authentication using 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]]

Setup:Installation Guide/Docker

2025-07-29T13:21:14Z

Hjing: /* Maintenance scripts */

== 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:
# "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 ==
Load project <code>bluespice-deploy</code> from https://github.com/hallowelt/bluespice-deploy/releases/latest and enter the sub-directory <code>compose</code> for Docker Compose files.

For example, run:
<syntaxhighlight lang=sh>
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
</syntaxhighlight>

The directory contains the following files:
{| class="wikitable"
|+
! style="width:375px;" |Filename
! style="" |Type
! style="" |Comment
|-
| style="width:375px;" |<code>bluespice-deploy</code>
| style="" |shell script
| style="" |Start-up script, wrapping command <code>docker compose</code> and service <code>yml</code> files. Additional service <code>yml</code> files can be loaded by adding <code>-f <filename> </code>.
|-
| style="width:375px;" |<code>docker-compose.main.yml</code>
| style="" |yml
| style="" |Main containers of the wiki (<code>wiki-web</code> and <code>wiki-task</code>).
|-
| style="width:375px;" |<code>docker-compose.persistent-data-services.yml</code>
| style="" |yml
| style="" |Containers of database and search services, storing persistent data onto the file system. Optionally with external MySQL/MariaDB and OpenSearch one can skip loading this <code>.yml</code> in <code>bluespice-deploy</code>. Please then wire your services properly in the <code>.env</code> file.
|-
| style="width:375px;" |<code>docker-compose.stateless-services.yml</code>
| style="" |yml
| style="" |Containers for caching, PDF rendering, formula-rendering and diagram editing.
|-
| style="width:375px;" |<code>docker-compose.helper-service.yml</code>
| style="" |yml
| style="" |Helper containers for file system preparation and automated BlueSpice upgrade. These containers exit automatically after finishing tasks.
|-
| style="width:375px;" |<code>docker-compose.proxy.yml</code>
| style="" |yml
| style="" |Container of proxy service. Can be replaced by existing proxy/load-balancer infrastructure.
|-
| style="width:375px;" |<code>docker-compose.proxy-letsencrypt.yml</code>
| style="" |yml
| style="" |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.
|-
| style="width:375px;" |<code>docker-compose.kerberos-proxy.yml</code>
| style="" |yml
| style="" |Additional proxy for Kerberos based authentication.
|-
| style="width:375px;" |<code>docker-compose.collabpads-service.yml</code>
|yml
|Containers of back-end services for [[Manual:Extension/CollabPads|CollabPads]] (included in Pro and Farm editions).
|-
| style="width:375px;" |<code>.env.sample</code>
| style="" |text
| style="" |Sample for creating <code>.env</code> that defines key environment variables.
|-
| style="width:375px;" |<code>bluespice.service.demo</code>
| style="" |service script
| style="" |Demo-file for control the BlueSpice stack as a <code>systemctl</code> service. One can create e.g a <code>/etc/systemd/system/bluespice.service</code>.
|}

== Step 2: Set up environment variables ==
Create your <code>.env</code> based on the sample file <code>.env.sample</code>.

Example:
<pre>
# set or use your data directory
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=set_or_use_your_db_user_name
DB_PASS=SET_OR_USE_YOUR_DB_PASS_WORD
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
</pre>
{{Textbox|boxtype=note|header=Different editions|text=This config works for all editions, but the main image of Pro or Farm edition needs to be obtained differently, see [[{{FULLPAGENAME}}/Pro and Farm edition|Pro and Farm edition]]|icon=yes}}

== Step 3: Start the stack ==
Use <code>bluespice-deploy up -d</code> to start the stack. 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 preferred web browser and start using the application.

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/initialAdminPassword</code>.

== Additional options ==

=== Configs for <code>LocalSettings.php</code> ===
Instead of exposing the <code>LocalSettings.php</code> for [[mediawikiwiki:Manual:LocalSettings.php|adding additional configurations]], the stack offers two entry points. After the initial installation, you can add your configs to two files in <code>${DATADIR}/wiki/bluespice/</code>:

* <code>pre-init-settings.php</code> - Set configs before the initialization of BlueSpice's debug logging, libraries, skins, extensions and default settings. Configs set here can be picked up by the init process.
* <code>post-init-settings.php</code> - Set configs after the initialization, manipulating configs that have been set by the init process.
For example, if you add the following lines to <code>pre-init-settings.php</code>, you can then read outputted debug logs (if any) in <code>${DATADIR}/wiki/bluespice/logs/debug.log</code>:<syntaxhighlight lang="php">
$GLOBALS['bsgDebugLogGroups']['exception'] = "/data/bluespice/logs/debug.log";
$wgShowExceptionDetails = true;
</syntaxhighlight>

=== Maintenance scripts ===
To run [[Setup:Installation Guide/Advanced/Maintenance scripts|maintenance scripts]] from MediaWiki or from other extensions, please use the <code>wiki-task</code> container, which handles all back-end jobs and processes. You can connect into the container in two different ways:

* run <code>./bluespice-deploy exec -it wiki-task bash</code> in the <code>compose</code> directory for Docker Compose files
* or alternatively, run <code>docker exec -it bluespice-wiki-task bash</code> wherever you are on the host machine

Inside the container you can enter the wiki's code base with <code>cd /app/bluespice/w</code> , where one can run scripts like <code>php maintenance/run.php update --quick</code>, <code>php extensions/BlueSpiceExtendedSearch/maintenance/updateWikiPageIndex.php</code> and so on.

=== SSL certificates ===
To use a Let's Encrypt certificate for your domain name, set <code>LETSENCRYPT=true</code> in your <code>.env</code> file.

To use a self-signend certificate for your domain name, put its <code>.crt</code> and <code>.key</code> files in <code>${DATADIR}/proxy/certs</code>. For example, with <code>wiki.company.local</code> you should prepare <code>wiki.company.local.crt</code> and <code>wiki.company.local.key</code> files.

=== Kerberos proxy ===
For implicit authentication using 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]]

Setup:Installation Guide/Docker

2025-07-28T13:18:48Z

Hjing:

== 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:
# "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 ==
Load project <code>bluespice-deploy</code> from https://github.com/hallowelt/bluespice-deploy/releases/latest and enter the sub-directory <code>compose</code> for Docker Compose files.

For example, run:
<syntaxhighlight lang=sh>
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
</syntaxhighlight>

The directory contains the following files:
{| class="wikitable"
|+
! style="width:375px;" |Filename
! style="" |Type
! style="" |Comment
|-
| style="width:375px;" |<code>bluespice-deploy</code>
| style="" |shell script
| style="" |Start-up script, wrapping command <code>docker compose</code> and service <code>yml</code> files. Additional service <code>yml</code> files can be loaded by adding <code>-f <filename> </code>.
|-
| style="width:375px;" |<code>docker-compose.main.yml</code>
| style="" |yml
| style="" |Main containers of the wiki (<code>wiki-web</code> and <code>wiki-task</code>).
|-
| style="width:375px;" |<code>docker-compose.persistent-data-services.yml</code>
| style="" |yml
| style="" |Containers of database and search services, storing persistent data onto the file system. Optionally with external MySQL/MariaDB and OpenSearch one can skip loading this <code>.yml</code> in <code>bluespice-deploy</code>. Please then wire your services properly in the <code>.env</code> file.
|-
| style="width:375px;" |<code>docker-compose.stateless-services.yml</code>
| style="" |yml
| style="" |Containers for caching, PDF rendering, formula-rendering and diagram editing.
|-
| style="width:375px;" |<code>docker-compose.helper-service.yml</code>
| style="" |yml
| style="" |Helper containers for file system preparation and automated BlueSpice upgrade. These containers exit automatically after finishing tasks.
|-
| style="width:375px;" |<code>docker-compose.proxy.yml</code>
| style="" |yml
| style="" |Container of proxy service. Can be replaced by existing proxy/load-balancer infrastructure.
|-
| style="width:375px;" |<code>docker-compose.proxy-letsencrypt.yml</code>
| style="" |yml
| style="" |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.
|-
| style="width:375px;" |<code>docker-compose.kerberos-proxy.yml</code>
| style="" |yml
| style="" |Additional proxy for Kerberos based authentication.
|-
| style="width:375px;" |<code>docker-compose.collabpads-service.yml</code>
|yml
|Containers of back-end services for [[Manual:Extension/CollabPads|CollabPads]] (included in Pro and Farm editions).
|-
| style="width:375px;" |<code>.env.sample</code>
| style="" |text
| style="" |Sample for creating <code>.env</code> that defines key environment variables.
|-
| style="width:375px;" |<code>bluespice.service.demo</code>
| style="" |service script
| style="" |Demo-file for control the BlueSpice stack as a <code>systemctl</code> service. One can create e.g a <code>/etc/systemd/system/bluespice.service</code>.
|}

== Step 2: Set up environment variables ==
Create your <code>.env</code> based on the sample file <code>.env.sample</code>.

Example:
<pre>
# set or use your data directory
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=set_or_use_your_db_user_name
DB_PASS=SET_OR_USE_YOUR_DB_PASS_WORD
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
</pre>
{{Textbox|boxtype=note|header=Different editions|text=This config works for all editions, but the main image of Pro or Farm edition needs to be obtained differently, see [[{{FULLPAGENAME}}/Pro and Farm edition|Pro and Farm edition]]|icon=yes}}

== Step 3: Start the stack ==
Use <code>bluespice-deploy up -d</code> to start the stack. 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 preferred web browser and start using the application.

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/initialAdminPassword</code>.

== Additional options ==

=== Configs for <code>LocalSettings.php</code> ===
Instead of exposing the <code>LocalSettings.php</code> for [[mediawikiwiki:Manual:LocalSettings.php|adding additional configurations]], the stack offers two entry points. After the initial installation, you can add your configs to two files in <code>${DATADIR}/wiki/bluespice/</code>:

* <code>pre-init-settings.php</code> - Set configs before the initialization of BlueSpice's debug logging, libraries, skins, extensions and default settings. Configs set here can be picked up by the init process.
* <code>post-init-settings.php</code> - Set configs after the initialization, manipulating configs that have been set by the init process.
For example, if you add the following lines to <code>pre-init-settings.php</code>, you can then read outputted debug logs (if any) in <code>${DATADIR}/wiki/bluespice/logs/debug.log</code>:<syntaxhighlight lang="php">
$GLOBALS['bsgDebugLogGroups']['exception'] = "/data/bluespice/logs/debug.log";
$wgShowExceptionDetails = true;
</syntaxhighlight>

=== Maintenance scripts ===
To run scripts from MediaWiki or from other extensions, please use the <code>wiki-task</code> container, which handles all back-end jobs and processes. You can connect into the container in two different ways:

* run <code>./bluespice-deploy exec -it wiki-task bash</code> in the <code>compose</code> directory for Docker Compose files
* or alternatively, run <code>docker exec -it bluespice-wiki-task bash</code> wherever you are on the host machine

Inside the container you can enter the wiki's code base with <code>cd /app/bluespice/w</code> , where one can run scripts like <code>php maintenance/run.php update --quick</code>, <code>php extensions/BlueSpiceExtendedSearch/maintenance/updateWikiPageIndex.php</code> and so on.

=== SSL certificates ===
To use a Let's Encrypt certificate for your domain name, set <code>LETSENCRYPT=true</code> in your <code>.env</code> file.

To use a self-signend certificate for your domain name, put its <code>.crt</code> and <code>.key</code> files in <code>${DATADIR}/proxy/certs</code>. For example, with <code>wiki.company.local</code> you should prepare <code>wiki.company.local.crt</code> and <code>wiki.company.local.key</code> files.

=== Kerberos proxy ===
For implicit authentication using 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]]

Setup:Installation Guide/Docker

2025-07-28T13:17:55Z

Hjing:

== 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:
# "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 ==
Load project <code>bluespice-deploy</code> from https://github.com/hallowelt/bluespice-deploy/releases/latest and enter the sub-directory <code>compose</code> for Docker Compose files.

For example, run:
<syntaxhighlight lang=sh>
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
</syntaxhighlight>

The directory contains the following files:
{| class="wikitable"
|+
! style="width:375px;" |Filename
! style="" |Type
! style="" |Comment
|-
| style="width:375px;" |<code>bluespice-deploy</code>
| style="" |shell script
| style="" |Start-up script, wrapping command <code>docker compose</code> and service <code>yml</code> files. Additional service <code>yml</code> files can be loaded by adding <code>-f <filename> </code>.
|-
| style="width:375px;" |<code>docker-compose.main.yml</code>
| style="" |yml
| style="" |Main containers of the wiki (<code>wiki-web</code> and <code>wiki-task</code>).
|-
| style="width:375px;" |<code>docker-compose.persistent-data-services.yml</code>
| style="" |yml
| style="" |Containers of database and search services, storing persistent data onto the file system. Optionally with external MySQL/MariaDB and OpenSearch one can skip loading this <code>.yml</code> in <code>bluespice-deploy</code>. Please then wire your services properly in the <code>.env</code> file.
|-
| style="width:375px;" |<code>docker-compose.stateless-services.yml</code>
| style="" |yml
| style="" |Containers for caching, PDF rendering, formula-rendering and diagram editing.
|-
| style="width:375px;" |<code>docker-compose.helper-service.yml</code>
| style="" |yml
| style="" |Helper containers for file system preparation and automated BlueSpice upgrade. These containers exit automatically after finishing tasks.
|-
| style="width:375px;" |<code>docker-compose.proxy.yml</code>
| style="" |yml
| style="" |Container of proxy service. Can be replaced by existing proxy/load-balancer infrastructure.
|-
| style="width:375px;" |<code>docker-compose.proxy-letsencrypt.yml</code>
| style="" |yml
| style="" |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.
|-
| style="width:375px;" |<code>docker-compose.kerberos-proxy.yml</code>
| style="" |yml
| style="" |Additional proxy for Kerberos based authentication.
|-
| style="width:375px;" |<code>docker-compose.collabpads-service.yml</code>
|yml
|Containers of back-end services for [[Manual:Extension/CollabPads|CollabPads]] (included in Pro and Farm editions).
|-
| style="width:375px;" |<code>.env.sample</code>
| style="" |text
| style="" |Sample for creating <code>.env</code> that defines key environment variables.
|-
| style="width:375px;" |<code>bluespice.service.demo</code>
| style="" |service script
| style="" |Demo-file for control the BlueSpice stack as a <code>systemctl</code> service. One can create e.g a <code>/etc/systemd/system/bluespice.service</code>.
|}

== Step 2: Set up environment variables ==
Create your <code>.env</code> based on the sample file <code>.env.sample</code>.

Example:
<pre>
# set or use your data directory
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=set_or_use_your_db_user_name
DB_PASS=SET_OR_USE_YOUR_DB_PASS_WORD
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
</pre>
{{Textbox|boxtype=note|header=Different editions|text=This config works for all editions, but the main image of Pro or Farm edition needs to be obtained differently, see [[{{FULLPAGENAME}}/Pro and Farm edition|Pro and Farm edition]]|icon=yes}}

== Step 3: Start the stack ==
Use <code>bluespice-deploy up -d</code> to start the stack. 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 preferred web browser and start using the application.

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/initialAdminPassword</code>.

== Additional options ==

=== Configs for <code>LocalSettings.php</code> ===
Instead of exposing the <code>LocalSettings.php</code> for [[mediawikiwiki:Manual:LocalSettings.php|adding additional configurations]], the stack offers two entry points. After the initial installation, you can add your configs to two files in <code>${DATADIR}/wiki/bluespice/</code>:

* <code>pre-init-settings.php</code> - Set configs before the initialization of BlueSpice's debug logging, libraries, skins, extensions and default settings. Configs set here can be picked up by the init process.
* <code>post-init-settings.php</code> - Set configs after the initialization, manipulating configs that have been set by the init process.
For example, if you add the following lines to <code>pre-init-settings.php</code>, you can then read outputted debug logs (if any) in <code>${DATADIR}/wiki/bluespice/logs/debug.log</code>:<syntaxhighlight lang="php">
$GLOBALS['bsgDebugLogGroups']['exception'] = "/data/bluespice/logs/debug.log";
$wgShowExceptionDetails = true;
</syntaxhighlight>

=== Maintenance scripts ===
To run scripts from MediaWiki or from other extensions, please use the <code>wiki-task</code> container, which handles all back-end jobs and processes. You can connect into the container in two different ways:

* run <code>./bluespice-deploy exec -it wiki-task bash</code> in the <code>compose</code> directory for Docker Compose files
* or alternatively, run <code>docker exec -it bluespice-wiki-task bash</code> regardless where you are on the host machine

Inside the container you can enter the wiki's code base with <code>cd /app/bluespice/w</code> , where one can run scripts like <code>php maintenance/run.php update --quick</code>, <code>php extensions/BlueSpiceExtendedSearch/maintenance/updateWikiPageIndex.php</code> and so on.

=== SSL certificates ===
To use a Let's Encrypt certificate for your domain name, set <code>LETSENCRYPT=true</code> in your <code>.env</code> file.

To use a self-signend certificate for your domain name, put its <code>.crt</code> and <code>.key</code> files in <code>${DATADIR}/proxy/certs</code>. For example, with <code>wiki.company.local</code> you should prepare <code>wiki.company.local.crt</code> and <code>wiki.company.local.key</code> files.

=== Kerberos proxy ===
For implicit authentication using 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]]

Setup:Installation Guide/Docker

2025-07-28T13:15:27Z

Hjing:

== 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:
# "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 ==
Load project <code>bluespice-deploy</code> from https://github.com/hallowelt/bluespice-deploy/releases/latest and enter the sub-directory <code>compose</code> for Docker Compose files.

For example, run:
<syntaxhighlight lang=sh>
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
</syntaxhighlight>

The directory contains the following files:
{| class="wikitable"
|+
! style="width:375px;" |Filename
! style="" |Type
! style="" |Comment
|-
| style="width:375px;" |<code>bluespice-deploy</code>
| style="" |shell script
| style="" |Start-up script, wrapping command <code>docker compose</code> and service <code>yml</code> files. Additional service <code>yml</code> files can be loaded by adding <code>-f <filename> </code>.
|-
| style="width:375px;" |<code>docker-compose.main.yml</code>
| style="" |yml
| style="" |Main containers of the wiki (<code>wiki-web</code> and <code>wiki-task</code>).
|-
| style="width:375px;" |<code>docker-compose.persistent-data-services.yml</code>
| style="" |yml
| style="" |Containers of database and search services, storing persistent data onto the file system. Optionally with external MySQL/MariaDB and OpenSearch one can skip loading this <code>.yml</code> in <code>bluespice-deploy</code>. Please then wire your services properly in the <code>.env</code> file.
|-
| style="width:375px;" |<code>docker-compose.stateless-services.yml</code>
| style="" |yml
| style="" |Containers for caching, PDF rendering, formula-rendering and diagram editing.
|-
| style="width:375px;" |<code>docker-compose.helper-service.yml</code>
| style="" |yml
| style="" |Helper containers for file system preparation and automated BlueSpice upgrade. These containers exit automatically after finishing tasks.
|-
| style="width:375px;" |<code>docker-compose.proxy.yml</code>
| style="" |yml
| style="" |Container of proxy service. Can be replaced by existing proxy/load-balancer infrastructure.
|-
| style="width:375px;" |<code>docker-compose.proxy-letsencrypt.yml</code>
| style="" |yml
| style="" |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.
|-
| style="width:375px;" |<code>docker-compose.kerberos-proxy.yml</code>
| style="" |yml
| style="" |Additional proxy for Kerberos based authentication.
|-
| style="width:375px;" |<code>docker-compose.collabpads-service.yml</code>
|yml
|Containers of back-end services for [[Manual:Extension/CollabPads|CollabPads]] (included in Pro and Farm editions).
|-
| style="width:375px;" |<code>.env.sample</code>
| style="" |text
| style="" |Sample for creating <code>.env</code> that defines key environment variables.
|-
| style="width:375px;" |<code>bluespice.service.demo</code>
| style="" |service script
| style="" |Demo-file for control the BlueSpice stack as a <code>systemctl</code> service. One can create e.g a <code>/etc/systemd/system/bluespice.service</code>.
|}

== Step 2: Set up environment variables ==
Create your <code>.env</code> based on the sample file <code>.env.sample</code>.

Example:
<pre>
# set or use your data directory
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=set_or_use_your_db_user_name
DB_PASS=SET_OR_USE_YOUR_DB_PASS_WORD
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
</pre>
{{Textbox|boxtype=note|header=Different editions|text=This config works for all editions, but the main image of Pro or Farm edition needs to be obtained differently, see [[{{FULLPAGENAME}}/Pro and Farm edition|Pro and Farm edition]]|icon=yes}}

== Step 3: Start the stack ==
Use <code>bluespice-deploy up -d</code> to start the stack. 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 preferred web browser and start using the application.

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/initialAdminPassword</code>.

== Additional options ==

=== Configs for <code>LocalSettings.php</code> ===
Instead of exposing the <code>LocalSettings.php</code> for [[mediawikiwiki:Manual:LocalSettings.php|adding additional configurations]], the stack offers two entry points. After the initial installation, you can add your configs to two files in <code>${DATADIR}/wiki/bluespice/</code>:

* <code>pre-init-settings.php</code> - Set configs before the initialization of BlueSpice's debug logging, libraries, skins, extensions and default settings. Configs set here can be picked up by the init process.
* <code>post-init-settings.php</code> - Set configs after the initialization, manipulating configs that have been set by the init process.
For example, if you add the following lines to <code>pre-init-settings.php</code>, you can then read outputted debug logs (if any) in <code>${DATADIR}/wiki/bluespice/logs/debug.log</code>:<syntaxhighlight lang="php">
$GLOBALS['bsgDebugLogGroups']['exception'] = "/data/bluespice/logs/debug.log";
$wgShowExceptionDetails = true;
</syntaxhighlight>

=== Maintenance scripts ===
To run scripts from MediaWiki or from other extensions, please use the <code>wiki-task</code> container, which handles all back-end jobs and processes. You can connect into the container in two different ways:

* run <code>./bluespice-deploy exec -it wiki-task bash</code> in the <code>compose</code> directory for Docker Compose files, or
* run <code>docker exec -it bluespice-wiki-task bash</code> anywhere.

Inside the container you can enter the wiki's code base with <code>cd /app/bluespice/w</code> , where one can run scripts like <code>php maintenance/run.php update --quick</code>, <code>php extensions/BlueSpiceExtendedSearch/maintenance/updateWikiPageIndex.php</code> and so on.

=== SSL certificates ===
To use a Let's Encrypt certificate for your domain name, set <code>LETSENCRYPT=true</code> in your <code>.env</code> file.

To use a self-signend certificate for your domain name, put its <code>.crt</code> and <code>.key</code> files in <code>${DATADIR}/proxy/certs</code>. For example, with <code>wiki.company.local</code> you should prepare <code>wiki.company.local.crt</code> and <code>wiki.company.local.key</code> files.

=== Kerberos proxy ===
For implicit authentication using 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]]

Setup:Installation Guide/Docker

2025-07-28T13:06:59Z

Hjing:

== 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:
# "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 ==
Load project <code>bluespice-deploy</code> from https://github.com/hallowelt/bluespice-deploy/releases/latest and enter the sub-directory <code>compose</code> for Docker Compose files.

For example, run:
<syntaxhighlight lang=sh>
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
</syntaxhighlight>

The directory contains the following files:
{| class="wikitable"
|+
! style="width:375px;" |Filename
! style="" |Type
! style="" |Comment
|-
| style="width:375px;" |<code>bluespice-deploy</code>
| style="" |shell script
| style="" |Start-up script, wrapping command <code>docker compose</code> and service <code>yml</code> files. Additional service <code>yml</code> files can be loaded by adding <code>-f <filename> </code>.
|-
| style="width:375px;" |<code>docker-compose.main.yml</code>
| style="" |yml
| style="" |Main containers of the wiki (<code>wiki-web</code> and <code>wiki-task</code>).
|-
| style="width:375px;" |<code>docker-compose.persistent-data-services.yml</code>
| style="" |yml
| style="" |Containers of database and search services, storing persistent data onto the file system. Optionally with external MySQL/MariaDB and OpenSearch one can skip loading this <code>.yml</code> in <code>bluespice-deploy</code>. Please then wire your services properly in the <code>.env</code> file.
|-
| style="width:375px;" |<code>docker-compose.stateless-services.yml</code>
| style="" |yml
| style="" |Containers for caching, PDF rendering, formula-rendering and diagram editing.
|-
| style="width:375px;" |<code>docker-compose.helper-service.yml</code>
| style="" |yml
| style="" |Helper containers for file system preparation and automated BlueSpice upgrade. These containers exit automatically after finishing tasks.
|-
| style="width:375px;" |<code>docker-compose.proxy.yml</code>
| style="" |yml
| style="" |Container of proxy service. Can be replaced by existing proxy/load-balancer infrastructure.
|-
| style="width:375px;" |<code>docker-compose.proxy-letsencrypt.yml</code>
| style="" |yml
| style="" |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.
|-
| style="width:375px;" |<code>docker-compose.kerberos-proxy.yml</code>
| style="" |yml
| style="" |Additional proxy for Kerberos based authentication.
|-
| style="width:375px;" |<code>docker-compose.collabpads-service.yml</code>
|yml
|Containers of back-end services for [[Manual:Extension/CollabPads|CollabPads]] (included in Pro and Farm editions).
|-
| style="width:375px;" |<code>.env.sample</code>
| style="" |text
| style="" |Sample for creating <code>.env</code> that defines key environment variables.
|-
| style="width:375px;" |<code>bluespice.service.demo</code>
| style="" |service script
| style="" |Demo-file for control the BlueSpice stack as a <code>systemctl</code> service. One can create e.g a <code>/etc/systemd/system/bluespice.service</code>.
|}

== Step 2: Set up environment variables ==
Create your <code>.env</code> based on the sample file <code>.env.sample</code>.

Example:
<pre>
# set or use your data directory
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=set_or_use_your_db_user_name
DB_PASS=SET_OR_USE_YOUR_DB_PASS_WORD
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
</pre>
{{Textbox|boxtype=note|header=Different editions|text=This config works for all editions, but the main image of Pro or Farm edition needs to be obtained differently, see [[{{FULLPAGENAME}}/Pro and Farm edition|Pro and Farm edition]]|icon=yes}}

== Step 3: Start the stack ==
Use <code>bluespice-deploy up -d</code> to start the stack. 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 preferred web browser and start using the application.

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/initialAdminPassword</code>.

== Additional options ==

=== SSL certificates ===
To use a Let's Encrypt certificate for your domain name, set <code>LETSENCRYPT=true</code> in your <code>.env</code> file.

To use a self-signend certificate for your domain name, put its <code>.crt</code> and <code>.key</code> files in <code>${DATADIR}/proxy/certs</code>. For example, with <code>wiki.company.local</code> you should prepare <code>wiki.company.local.crt</code> and <code>wiki.company.local.key</code> files.

=== Configs for <code>LocalSettings.php</code> ===
Instead of exposing the <code>LocalSettings.php</code> for [[mediawikiwiki:Manual:LocalSettings.php|adding additional configurations]], the stack offers two entry points. After the initial installation, you can add your configs to two files in <code>${DATADIR}/wiki/bluespice/</code>:

* <code>pre-init-settings.php</code> - Set configs before the initialization of BlueSpice's debug logging, libraries, skins, extensions and default settings. Configs set here can be picked up by the init process.
* <code>post-init-settings.php</code> - Set configs after the initialization, manipulating configs that have been set by the init process.
For example, if you add the following lines to <code>pre-init-settings.php</code>, you can then read outputted debug logs (if any) in <code>${DATADIR}/wiki/bluespice/logs/debug.log</code>:<syntaxhighlight lang="php">
$GLOBALS['bsgDebugLogGroups']['exception'] = "/data/bluespice/logs/debug.log";
$wgShowExceptionDetails = true;
</syntaxhighlight>

=== Run maintenance scripts ===
To run scripts from MediaWiki or from other extensions, please use the <code>wiki-task</code> container, which handles all back-end jobs and processes. You can connect into the container in two different ways:

* run <code>./bluespice-deploy exec -it wiki-task bash</code> in the <code>compose</code> directory for Docker Compose files, or
* run <code>docker exec -it bluespice-wiki-task bash</code> anywhere.

Inside the container you can enter the wiki's code base with <code>cd /app/bluespice/w</code> , where one can run for example <code>php maintenance/run.php update --quick</code>.

=== Kerberos proxy ===
For implicit authentication using 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]]

Setup:Installation Guide/Docker

2025-07-28T13:06:38Z

Hjing:

== 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:
# "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 ==
Load project <code>bluespice-deploy</code> from https://github.com/hallowelt/bluespice-deploy/releases/latest and enter the sub-directory <code>compose</code> for Docker Compose files.

For example, run:
<syntaxhighlight lang=sh>
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
</syntaxhighlight>

The directory contains the following files:
{| class="wikitable"
|+
! style="width:375px;" |Filename
! style="" |Type
! style="" |Comment
|-
| style="width:375px;" |<code>bluespice-deploy</code>
| style="" |shell script
| style="" |Start-up script, wrapping command <code>docker compose</code> and service <code>yml</code> files. Additional service <code>yml</code> files can be loaded by adding <code>-f <filename> </code>.
|-
| style="width:375px;" |<code>docker-compose.main.yml</code>
| style="" |yml
| style="" |Main containers of the wiki (<code>wiki-web</code> and <code>wiki-task</code>).
|-
| style="width:375px;" |<code>docker-compose.persistent-data-services.yml</code>
| style="" |yml
| style="" |Containers of database and search services, storing persistent data onto the file system. Optionally with external MySQL/MariaDB and OpenSearch one can skip loading this <code>.yml</code> in <code>bluespice-deploy</code>. Please then wire your services properly in the <code>.env</code> file.
|-
| style="width:375px;" |<code>docker-compose.stateless-services.yml</code>
| style="" |yml
| style="" |Containers for caching, PDF rendering, formula-rendering and diagram editing.
|-
| style="width:375px;" |<code>docker-compose.helper-service.yml</code>
| style="" |yml
| style="" |Helper containers for file system preparation and automated BlueSpice upgrade. These containers exit automatically after finishing tasks.
|-
| style="width:375px;" |<code>docker-compose.proxy.yml</code>
| style="" |yml
| style="" |Container of proxy service. Can be replaced by existing proxy/load-balancer infrastructure.
|-
| style="width:375px;" |<code>docker-compose.proxy-letsencrypt.yml</code>
| style="" |yml
| style="" |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.
|-
| style="width:375px;" |<code>docker-compose.kerberos-proxy.yml</code>
| style="" |yml
| style="" |Additional proxy for Kerberos based authentication.
|-
| style="width:375px;" |<code>docker-compose.collabpads-service.yml</code>
|yml
|Containers of back-end services for [[Manual:Extension/CollabPads|CollabPads]] (included in Pro and Farm editions).
|-
| style="width:375px;" |<code>.env.sample</code>
| style="" |text
| style="" |Sample for creating <code>.env</code> that defines key environment variables.
|-
| style="width:375px;" |<code>bluespice.service.demo</code>
| style="" |service script
| style="" |Demo-file for control the BlueSpice stack as a <code>systemctl</code> service. One can create e.g a <code>/etc/systemd/system/bluespice.service</code>.
|}

== Step 2: Set up environment variables ==
Create your <code>.env</code> based on the sample file <code>.env.sample</code>.

Example:
<pre>
# set or use your data directory
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=set_or_use_your_db_user_name
DB_PASS=SET_OR_USE_YOUR_DB_PASS_WORD
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
</pre>
{{Textbox|boxtype=note|header=Different editions|text=This config works for all editions, but the main image of Pro or Farm edition needs to be obtained differently, see [[{{FULLPAGENAME}}/Pro and Farm edition|Pro and Farm edition]]|icon=yes}}

== Step 3: Start the stack ==
Use <code>bluespice-deploy up -d</code> to start the stack. 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 preferred web browser and start using the application.

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/initialAdminPassword</code>.

== Additional options ==

=== SSL certificates ===
To use a Let's Encrypt certificate for your domain name, set <code>LETSENCRYPT=true</code> in your <code>.env</code> file.

To use a self-signend certificate for your domain name, put its <code>.crt</code> and <code>.key</code> files in <code>${DATADIR}/proxy/certs</code>. For example, with <code>wiki.company.local</code> you should prepare <code>wiki.company.local.crt</code> and <code>wiki.company.local.key</code> files.


=== Configs for <code>LocalSettings.php</code> ===
Instead of exposing the <code>LocalSettings.php</code> for [[mediawikiwiki:Manual:LocalSettings.php|adding additional configurations]], the stack offers two entry points. After the initial installation, you can add your configs to two files in <code>${DATADIR}/wiki/bluespice/</code>:

* <code>pre-init-settings.php</code> - Set configs before the initialization of BlueSpice's debug logging, libraries, skins, extensions and default settings. Configs set here can be picked up by the init process.
* <code>post-init-settings.php</code> - Set configs after the initialization, manipulating configs that have been set by the init process.
For example, if you add the following lines to <code>pre-init-settings.php</code>, you can then read outputted debug logs (if any) in <code>${DATADIR}/wiki/bluespice/logs/debug.log</code>:<syntaxhighlight lang="php">
$GLOBALS['bsgDebugLogGroups']['exception'] = "/data/bluespice/logs/debug.log";
$wgShowExceptionDetails = true;
</syntaxhighlight>

=== Run maintenance scripts ===
To run scripts from MediaWiki or from other extensions, please use the <code>wiki-task</code> container, which handles all back-end jobs and processes. You can connect into the container in two different ways:

* run <code>./bluespice-deploy exec -it wiki-task bash</code> in the <code>compose</code> directory for Docker Compose files, or
* run <code>docker exec -it bluespice-wiki-task bash</code> anywhere.

Inside the container you can enter the wiki's code base with <code>cd /app/bluespice/w</code> , where one can run for example <code>php maintenance/run.php update --quick</code>.

=== Kerberos proxy ===
For implicit authentication using 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]]

Setup:Installation Guide/Docker

2025-07-28T12:57:05Z

Hjing:

== 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:
# "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 ==
Load project <code>bluespice-deploy</code> from https://github.com/hallowelt/bluespice-deploy/releases/latest and enter the sub-directory <code>compose</code> for Docker Compose files.

For example, run:
<syntaxhighlight lang=sh>
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
</syntaxhighlight>

The directory contains the following files:
{| class="wikitable"
|+
! style="width:375px;" |Filename
! style="" |Type
! style="" |Comment
|-
| style="width:375px;" |<code>bluespice-deploy</code>
| style="" |shell script
| style="" |Start-up script, wrapping command <code>docker compose</code> and service <code>yml</code> files. Additional service <code>yml</code> files can be loaded by adding <code>-f <filename> </code>.
|-
| style="width:375px;" |<code>docker-compose.main.yml</code>
| style="" |yml
| style="" |Main containers of the wiki (<code>wiki-web</code> and <code>wiki-task</code>).
|-
| style="width:375px;" |<code>docker-compose.persistent-data-services.yml</code>
| style="" |yml
| style="" |Containers of database and search services, storing persistent data onto the file system. Optionally with external MySQL/MariaDB and OpenSearch one can skip loading this <code>.yml</code> in <code>bluespice-deploy</code>. Please then wire your services properly in the <code>.env</code> file.
|-
| style="width:375px;" |<code>docker-compose.stateless-services.yml</code>
| style="" |yml
| style="" |Containers for caching, PDF rendering, formula-rendering and diagram editing.
|-
| style="width:375px;" |<code>docker-compose.helper-service.yml</code>
| style="" |yml
| style="" |Helper containers for file system preparation and automated BlueSpice upgrade. These containers exit automatically after finishing tasks.
|-
| style="width:375px;" |<code>docker-compose.proxy.yml</code>
| style="" |yml
| style="" |Container of proxy service. Can be replaced by existing proxy/load-balancer infrastructure.
|-
| style="width:375px;" |<code>docker-compose.proxy-letsencrypt.yml</code>
| style="" |yml
| style="" |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.
|-
| style="width:375px;" |<code>docker-compose.kerberos-proxy.yml</code>
| style="" |yml
| style="" |Additional proxy for Kerberos based authentication.
|-
| style="width:375px;" |<code>docker-compose.collabpads-service.yml</code>
|yml
|Containers of back-end services for [[Manual:Extension/CollabPads|CollabPads]] (included in Pro and Farm editions).
|-
| style="width:375px;" |<code>.env.sample</code>
| style="" |text
| style="" |Sample for creating <code>.env</code> that defines key environment variables.
|-
| style="width:375px;" |<code>bluespice.service.demo</code>
| style="" |service script
| style="" |Demo-file for control the BlueSpice stack as a <code>systemctl</code> service. One can create e.g a <code>/etc/systemd/system/bluespice.service</code>.
|}

== Step 2: Set up environment variables ==
Create your <code>.env</code> based on the sample file <code>.env.sample</code>.

Example:
<pre>
# set or use your data directory
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=set_or_use_your_db_user_name
DB_PASS=SET_OR_USE_YOUR_DB_PASS_WORD
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
</pre>
{{Textbox|boxtype=note|header=Different editions|text=This config works for all editions, but the main image of Pro or Farm edition needs to be obtained differently, see [[{{FULLPAGENAME}}/Pro and Farm edition|Pro and Farm edition]]|icon=yes}}

== Step 3: Start the stack ==
Use <code>bluespice-deploy up -d</code> to start the stack. 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 preferred web browser and start using the application.

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/initialAdminPassword</code>.

== Configurations, maintenance and more extensions ==

=== Configs for <code>LocalSettings.php</code> ===
Instead of exposing the <code>LocalSettings.php</code> for [[mediawikiwiki:Manual:LocalSettings.php|adding additional configurations]], the stack offers two entry points. After the initial installation, you can add your configs to two files in <code>${DATADIR}/wiki/bluespice/</code>:

* <code>pre-init-settings.php</code> - Set configs before the initialization of BlueSpice's debug logging, libraries, skins, extensions and default settings. Configs set here can be picked up by the init process.
* <code>post-init-settings.php</code> - Set configs after the initialization, manipulating configs that have been set by the init process.
For example, if you add the following lines to <code>pre-init-settings.php</code>, you can then read outputted debug logs (if any) in <code>${DATADIR}/wiki/bluespice/logs/debug.log</code>:<syntaxhighlight lang="php">
$GLOBALS['bsgDebugLogGroups']['exception'] = "/data/bluespice/logs/debug.log";
$wgShowExceptionDetails = true;
</syntaxhighlight>

=== Run maintenance scripts ===
To run scripts from MediaWiki or from other extensions, please use the <code>wiki-task</code> container, which handles all back-end jobs and processes. You can connect into the container in two different ways:

* run <code>./bluespice-deploy exec -it wiki-task bash</code> in the <code>compose</code> directory for Docker Compose files, or
* run <code>docker exec -it bluespice-wiki-task bash</code> anywhere.

Inside the container you can enter the wiki's code base with <code>cd /app/bluespice/w</code> , where one can run for example <code>php maintenance/run.php update --quick</code>.

=== Install more MediaWiki extensions ===
To install more MediaWiki extensions, especially those complicated ones that relies on external libraries, one will need to manage the wiki's code base outside the <code>wiki-web</code> and the <code>wiki-task</code> containers, add your wanted extensions then load libraries with [https://getcomposer.org/ Composer]. Please follow the steps:

# Enter the sub-directory <code>compose</code> for the Docker Compose files of the directory where you load project <code>bluespice-deploy</code>, see [[Setup:Installation Guide/Docker#Step 1: Get the stack|Step 1]].
# Replace placeholders in the following piece of code (with correct absolute path in your case), then run the code.<syntaxhighlight lang="sh">./bluespice-deploy cp wiki-web:/app/bluespice/w ../code
cat <<EOF >> docker-compose.override.yml
services:
wiki-web:
volumes:
- /<absolute-path-to-the-project>/code:/app/bluespice/w
wiki-task:
volumes:
- /<absolute-path-to-the-project>/code:/app/bluespice/w
EOF</syntaxhighlight>
# tba



== Additional options ==

=== SSL certificates ===
To use a Let's Encrypt certificate for your domain name, set <code>LETSENCRYPT=true</code> in your <code>.env</code> file.

To use a self-signend certificate for your domain name, put its <code>.crt</code> and <code>.key</code> files in <code>${DATADIR}/proxy/certs</code>. For example, with <code>wiki.company.local</code> you should prepare <code>wiki.company.local.crt</code> and <code>wiki.company.local.key</code> files.


=== Kerberos proxy ===
For implicit authentication using 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]]

Setup:Installation Guide/Docker

2025-07-24T16:16:30Z

Hjing: Improve tutorial

== 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:
# "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 ==
Load project <code>bluespice-deploy</code> from https://github.com/hallowelt/bluespice-deploy/releases/latest and enter the sub-directory <code>compose</code> for Docker Compose files.

For example, run:
<syntaxhighlight lang=sh>
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
</syntaxhighlight>

The directory contains the following files:
{| class="wikitable"
|+
! style="width:375px;" |Filename
! style="" |Type
! style="" |Comment
|-
| style="width:375px;" |<code>bluespice-deploy</code>
| style="" |shell script
| style="" |Start-up script, wrapping command <code>docker compose</code> and service <code>yml</code> files. Additional service <code>yml</code> files can be loaded by adding <code>-f <filename> </code>.
|-
| style="width:375px;" |<code>docker-compose.main.yml</code>
| style="" |yml
| style="" |Main containers of the wiki (<code>wiki-web</code> and <code>wiki-task</code>).
|-
| style="width:375px;" |<code>docker-compose.persistent-data-services.yml</code>
| style="" |yml
| style="" |Containers of database and search services, storing persistent data onto the file system. Optionally with external MySQL/MariaDB and OpenSearch one can skip loading this <code>.yml</code> in <code>bluespice-deploy</code>. Please then wire your services properly in the <code>.env</code> file.
|-
| style="width:375px;" |<code>docker-compose.stateless-services.yml</code>
| style="" |yml
| style="" |Containers for caching, PDF rendering, formula-rendering and diagram editing.
|-
| style="width:375px;" |<code>docker-compose.helper-service.yml</code>
| style="" |yml
| style="" |Helper containers for file system preparation and automated BlueSpice upgrade. These containers exit automatically after finishing tasks.
|-
| style="width:375px;" |<code>docker-compose.proxy.yml</code>
| style="" |yml
| style="" |Container of proxy service. Can be replaced by existing proxy/load-balancer infrastructure.
|-
| style="width:375px;" |<code>docker-compose.proxy-letsencrypt.yml</code>
| style="" |yml
| style="" |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.
|-
| style="width:375px;" |<code>docker-compose.kerberos-proxy.yml</code>
| style="" |yml
| style="" |Additional proxy for Kerberos based authentication.
|-
| style="width:375px;" |<code>docker-compose.collabpads-service.yml</code>
|yml
|Containers of back-end services for [[Manual:Extension/CollabPads|CollabPads]] (included in Pro and Farm editions).
|-
| style="width:375px;" |<code>.env.sample</code>
| style="" |text
| style="" |Sample for creating <code>.env</code> that defines key environment variables.
|-
| style="width:375px;" |<code>bluespice.service.demo</code>
| style="" |service script
| style="" |Demo-file for control the BlueSpice stack as a <code>systemctl</code> service. One can create e.g a <code>/etc/systemd/system/bluespice.service</code>.
|}

== Step 2: Set up environment variables ==
Create your <code>.env</code> based on the sample file <code>.env.sample</code>.

Example:
<pre>
# set or use your data directory
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=set_or_use_your_db_user_name
DB_PASS=SET_OR_USE_YOUR_DB_PASS_WORD
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
</pre>
{{Textbox|boxtype=note|header=Different editions|text=This config works for all editions, but the main image of Pro or Farm edition needs to be obtained differently, see [[{{FULLPAGENAME}}/Pro and Farm edition|Pro and Farm edition]]|icon=yes}}

== Step 3: Start the stack ==
Use <code>bluespice-deploy up -d</code> to start the stack. 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 preferred web browser and start using the application.

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/initialAdminPassword</code>.

== Additional options ==

=== SSL certificates ===
To use a Let's Encrypt certificate for your domain name, set <code>LETSENCRYPT=true</code> in your <code>.env</code> file.

To use a self-signend certificate for your domain name, put its <code>.crt</code> and <code>.key</code> files in <code>${DATADIR}/proxy/certs</code>. For example, with <code>wiki.company.local</code> you should prepare <code>wiki.company.local.crt</code> and <code>wiki.company.local.key</code> files.


=== Configs for <code>LocalSettings.php</code> ===
Instead of exposing the <code>LocalSettings.php</code> for [[mediawikiwiki:Manual:LocalSettings.php|adding additional configurations]], the stack offers two entry points. After the initial installation, you can add your configs to two files in <code>${DATADIR}/wiki/bluespice/</code> :

* <code>pre-init-settings.php</code> - Set configs before the initialization of BlueSpice's debug logging, libraries, skins, extensions and default settings. Configs set here can be picked up by the init process.
* <code>post-init-settings.php</code> - Set configs after the initialization, manipulating configs that have been set by the init process.

=== Run maintenance scripts ===
To run scripts from MediaWiki or from other extensions, please use the <code>wiki-task</code> container, which handles all back-end jobs and processes. You can connect into the container in two different ways:

* run <code>./bluespice-deploy exec -it wiki-task bash</code> in the <code>compose</code> directory for Docker Compose files, or
* run <code>docker exec -it bluespice-wiki-task bash</code> anywhere.

Inside the container you can find code base of the wiki at <code>/app/bluespice/w</code> , where one can run for example <code>php maintenance/run.php update --quick</code>.

=== Install further MediaWiki extensions ===

== Additional authentication services ==

=== Kerberos proxy ===
For implicit authentication using 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]]

Setup:Installation Guide/Docker

2025-07-24T14:36:38Z

Hjing:

== 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:
# "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 ==
Load project <code>bluespice-deploy</code> from https://github.com/hallowelt/bluespice-deploy/releases/latest and enter the sub-directory <code>compose</code> for Docker Compose files.

For example, run:
<syntaxhighlight lang=sh>
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
</syntaxhighlight>

The directory contains the following files:
{| class="wikitable"
|+
! style="width:350px;" |Filename
! style="" |Type
! style="" |Comment
|-
| style="width:350px;" |<code>bluespice-deploy</code>
| style="" |shell script
| style="" |Start-up script, wrapping command <code>docker compose</code> and service <code>yml</code> files. Additional service <code>yml</code> files can be loaded by adding <code>-f <filename> </code>.
|-
| style="width:350px;" |<code>docker-compose.main.yml</code>
| style="" |yml
| style="" |Main containers of the wiki (<code>wiki-web</code> and <code>wiki-task</code>).
|-
| style="width:350px;" |<code>docker-compose.persistent-data-services.yml</code>
| style="" |yml
| style="" |Containers of database and search services, storing persistent data onto the file system.
|-
| style="width:350px;" |<code>docker-compose.stateless-services.yml</code>
| style="" |yml
| style="" |Containers for caching, PDF rendering, formula-rendering and diagram editing.
|-
| style="width:350px;" |<code>docker-compose.helper-service.yml</code>
| style="" |yml
| style="" |Helper containers for file system preparation and automated BlueSpice upgrade. These containers exit automatically after finishing tasks.
|-
| style="width:350px;" |<code>docker-compose.proxy.yml</code>
| style="" |yml
| style="" |Container of proxy service. Can be replaced by existing proxy/load-balancer infrastructure.
|-
| style="width:350px;" |<code>docker-compose.proxy-letsencrypt.yml</code>
| style="" |yml
| style="" |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.
|-
| style="width:350px;" |<code>docker-compose.kerberos-proxy.yml</code>
| style="" |yml
| style="" |Additional proxy for Kerberos based authentication.
|-
| style="width:350px;" |<code>docker-compose.collabpads-service.yml</code>
|yml
|Containers of back-end services for [[Manual:Extension/CollabPads|CollabPads]] (included in Pro and Farm editions)
|-
| style="width:350px;" |<code>.env.sample</code>
| style="" |text
| style="" |Sample for creating <code>.env</code> that defines key environment variables.
|-
| style="width:350px;" |<code>bluespice.service.demo</code>
| style="" |service script
| style="" |Demo-file for control the BlueSpice stack as a <code>systemctl</code> service.
|}

== Step 2: Set up environment variables ==
Create your <code>.env</code> based on the sample file <code>.env.sample</code>.

Example:
<pre>
# set or use your data directory
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=set_or_use_your_db_user_name
DB_PASS=SET_OR_USE_YOUR_DB_PASS_WORD
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
</pre>
{{Textbox|boxtype=note|header=Different editions|text=This config works for all editions, but the main image of Pro or Farm edition needs to be obtained differently, see [[{{FULLPAGENAME}}/Pro and Farm edition|Pro and Farm edition]]|icon=yes}}

== Step 3: Start the stack ==
Use <code>bluespice-deploy up -d</code> to start the stack. 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 preferred web browser and start using the application.
{{Textbox
|boxtype=note
|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/initialAdminPassword</code>.
|icon=yes
}}

== Additional options ==

=== SSL certificates ===
To use a Let's Encrypt certificate for your domain name, set <code>LETSENCRYPT=true</code> in your <code>.env</code> file.

To use a self-signend certificate for your domain name, put its <code>.crt</code> and <code>.key</code> files in <code>${DATADIR}/proxy/certs</code>. For example, with <code>wiki.company.local</code> you should prepare <code>wiki.company.local.crt</code> and <code>wiki.company.local.key</code> files.


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

Setup:Installation Guide/Docker

2025-07-24T10:45:40Z

Hjing: Improve default value for db settings

== 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:
# "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 ==
Load project <code>bluespice-deploy</code> from https://github.com/hallowelt/bluespice-deploy/releases/latest and enter the sub-directory <code>compose</code> for Docker Compose files.

For example, run:
<syntaxhighlight lang=sh>
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
</syntaxhighlight>

The directory contains the following files:
{| class="wikitable"
|+
! style="width:350px;" |Filename
! style="" |Type
! style="" |Comment
|-
| style="width:350px;" |<code>bluespice-deploy</code>
| style="" |shell script
| style="" |Start-up script, wrapping command <code>docker compose</code> and service <code>yml</code> files. Additional service <code>yml</code> files can be loaded by adding <code>-f <filename> </code>.
|-
| style="width:350px;" |<code>docker-compose.main.yml</code>
| style="" |yml
| style="" |Main containers of the wiki (<code>wiki-web</code> and <code>wiki-task</code>).
|-
| style="width:350px;" |<code>docker-compose.persistent-data-services.yml</code>
| style="" |yml
| style="" |Containers of database and search services, storing persistent data onto the file system.
|-
| style="width:350px;" |<code>docker-compose.stateless-services.yml</code>
| style="" |yml
| style="" |Containers for caching, PDF rendering, formula-rendering and diagram editing.
|-
| style="width:350px;" |<code>docker-compose.helper-service.yml</code>
| style="" |yml
| style="" |Helper containers for file system preparation and automated BlueSpice upgrade. These containers exit automatically after finishing tasks.
|-
| style="width:350px;" |<code>docker-compose.proxy.yml</code>
| style="" |yml
| style="" |Container of proxy service. Can be replaced by existing proxy/load-balancer infrastructure.
|-
| style="width:350px;" |<code>docker-compose.proxy-letsencrypt.yml</code>
| style="" |yml
| style="" |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.
|-
| style="width:350px;" |<code>docker-compose.kerberos-proxy.yml</code>
| style="" |yml
| style="" |Additional proxy for Kerberos based authentication.
|-
| style="width:350px;" |<code>docker-compose.collabpads-service.yml</code>
|yml
|Containers of back-end services for [[Manual:Extension/CollabPads|CollabPads]] (included in Pro and Farm editions)
|-
| style="width:350px;" |<code>.env.sample</code>
| style="" |text
| style="" |Sample for creating <code>.env</code> that defines key environment variables.
|-
| style="width:350px;" |<code>bluespice.service.demo</code>
| style="" |service script
| style="" |Demo-file for control the BlueSpice stack as a <code>systemctl</code> service.
|}

== Step 2: Set up environment variables ==
Create your <code>.env</code> based on the sample file <code>.env.sample</code>.

Example:
<pre>
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=set_or_use_your_db_user_name
DB_PASS=SET_OR_USE_YOUR_DB_PASS_WORD
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
</pre>
{{Textbox|boxtype=note|header=Different editions|text=All services configurations for Pro and Farm editions are included here, but the main application image <code>bluespice/wiki</code> needs to be obtained differently. If you are deploying Pro or Farm edition, please see [[{{FULLPAGENAME}}/Pro and Farm edition|Pro and Farm edition]] for details|icon=yes}}

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

Setup:Installation Guide/Docker

2025-07-21T13:47:07Z

Hjing:

== 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:
# "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 ==
Load project <code>bluespice-deploy</code> from https://github.com/hallowelt/bluespice-deploy/releases/latest and enter the sub-directory <code>compose</code> for Docker Compose files.

For example, run:
<syntaxhighlight lang=sh>
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
</syntaxhighlight>

The directory contains the following files:
{| class="wikitable"
|+
! style="width:350px;" |Filename
! style="" |Type
! style="" |Comment
|-
| style="width:350px;" |<code>bluespice-deploy</code>
| style="" |shell script
| style="" |Start-up script, wrapping command <code>docker compose</code> and service <code>yml</code> files. Additional service <code>yml</code> files can be loaded by adding <code>-f <filename> </code>.
|-
| style="width:350px;" |<code>docker-compose.main.yml</code>
| style="" |yml
| style="" |Main containers of the wiki (<code>wiki-web</code> and <code>wiki-task</code>).
|-
| style="width:350px;" |<code>docker-compose.persistent-data-services.yml</code>
| style="" |yml
| style="" |Containers of database and search services, storing persistent data onto the file system.
|-
| style="width:350px;" |<code>docker-compose.stateless-services.yml</code>
| style="" |yml
| style="" |Containers for caching, PDF rendering, formula-rendering and diagram editing.
|-
| style="width:350px;" |<code>docker-compose.helper-service.yml</code>
| style="" |yml
| style="" |Helper containers for file system preparation and automated BlueSpice upgrade. These containers exit automatically after finishing tasks.
|-
| style="width:350px;" |<code>docker-compose.proxy.yml</code>
| style="" |yml
| style="" |Container of proxy service. Can be replaced by existing proxy/load-balancer infrastructure.
|-
| style="width:350px;" |<code>docker-compose.proxy-letsencrypt.yml</code>
| style="" |yml
| style="" |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.
|-
| style="width:350px;" |<code>docker-compose.kerberos-proxy.yml</code>
| style="" |yml
| style="" |Additional proxy for Kerberos based authentication.
|-
| style="width:350px;" |<code>docker-compose.collabpads-service.yml</code>
|yml
|Containers of back-end services for [[Manual:Extension/CollabPads|CollabPads]] (included in Pro and Farm editions)
|-
| style="width:350px;" |<code>.env.sample</code>
| style="" |text
| style="" |Sample for creating <code>.env</code> that defines key environment variables.
|-
| style="width:350px;" |<code>bluespice.service.demo</code>
| style="" |service script
| style="" |Demo-file for control the BlueSpice stack as a <code>systemctl</code> service.
|}

== Step 2: Set up environment variables ==
Create your <code>.env</code> based on the sample file <code>.env.sample</code>.

Example:
<pre>
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
</pre>
{{Textbox|boxtype=note|header=Different editions|text=All services configurations for Pro and Farm editions are included here, but the main application image <code>bluespice/wiki</code> needs to be obtained differently. If you are deploying Pro or Farm edition, please see [[{{FULLPAGENAME}}/Pro and Farm edition|Pro and Farm edition]] for details|icon=yes}}

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

Setup:Installation Guide/Docker

2025-07-21T13:44:53Z

Hjing: /* Step 1: Get the stack */

== 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:
# "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 ==
Load project <code>bluespice-deploy</code> from https://github.com/hallowelt/bluespice-deploy/releases/latest and enter the sub-directory <code>compose</code> for Docker Compose files.

For example, run:
<syntaxhighlight lang=sh>
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
</syntaxhighlight>

The directory contains the following files:
{| class="wikitable"
|+
! style="width:350px;" |Filename
! style="" |Type
! style="" |Comment
|-
| style="width:350px;" |<code>bluespice-deploy</code>
| style="" |shell script
| style="" |Start-up script, wrapping command <code>docker compose</code> and service <code>yml</code> files. Additional service <code>yml</code> files can be loaded by adding <code>-f <filename> </code>.
|-
| style="width:350px;" |<code>docker-compose.main.yml</code>
| style="" |yml
| style="" |Main containers of the wiki (<code>wiki-web</code> and <code>wiki-task</code>).
|-
| style="width:350px;" |<code>docker-compose.persistent-data-services.yml</code>
| style="" |yml
| style="" |Containers of database and search services, storing persistent data onto the file system.
|-
| style="width:350px;" |<code>docker-compose.stateless-services.yml</code>
| style="" |yml
| style="" |Containers for caching, PDF rendering, formula-rendering and diagram editing.
|-
| style="width:350px;" |<code>docker-compose.helper-service.yml</code>
| style="" |yml
| style="" |Helper containers for file system preparation and automated BlueSpice upgrade. These containers exit automatically after finishing tasks.
|-
| style="width:350px;" |<code>docker-compose.proxy.yml</code>
| style="" |yml
| style="" |Container of proxy service. Can be replaced by existing proxy/load-balancer infrastructure.
|-
| style="width:350px;" |<code>docker-compose.proxy-letsencrypt.yml</code>
| style="" |yml
| style="" |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.
|-
| style="width:350px;" |<code>docker-compose.kerberos-proxy.yml</code>
| style="" |yml
| style="" |Additional proxy for Kerberos based authentication.
|-
| style="width:350px;" |<code>docker-compose.collabpads-service.yml</code>
|yml
|Containers of back-end services for [[Manual:Extension/CollabPads|CollabPads]] (included in Pro and Farm editions)
|-
| style="width:350px;" |<code>.env.sample</code>
| style="" |text
| style="" |Sample for creating <code>.env</code> that defines key environment variables.
|-
| style="width:350px;" |<code>bluespice.service.demo</code>
| style="" |service script
| style="" |Demo-file for control the BlueSpice stack as a <code>systemctl</code> service.
|}

== Step 2: Set up environment variables ==
Create your <code>.env</code> based on the sample file <code>.env.sample</code>.

Example:
<pre>
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
</pre>
If you are deploying <code>pro</code> or <code>farm</code> edition, please run <code>docker login docker.bluespice.com</code> and login with your credentials.
{{Textbox|boxtype=note|header=Different editions|text=All services configurations for Pro and Farm editions are included here, 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}}

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

Setup:Installation Guide/Docker

2025-07-21T12:34:10Z

Hjing:

== 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:
# "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/releases/latest

Example:
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

{{Textbox|boxtype=note|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>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.helper-service.yml</code>
| style="" |yml
| style="" |true
| style="" |Provides different helper containers for Filesystem-preparation, major-upgrades and backups
|-
| 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 authentication
|-
| style="width:350px;" |<code>docker-compose.collabpads-service.yml</code>
|yml
|false
|Provides back-end services for [[Manual:Extension/CollabPads|CollabPads]] (included in Pro and Farm editions)
|-
| style="width:350px;" |<code>.env.sample</code>
|text
|true
|Sample for creating <code>.env</code> that defines key environment variables
|-
| style="width:350px;" |<code>bluespice.service.demo</code>
|service script
|false
|A Demo-file for control the BlueSpice stack as systemctl service
|}

For convenience, the <code>bluespice-deploy</code> script wraps the first five <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 service <code>yml</code> files can be loaded by adding <code>-f <filename> </code>.

== Step 2: Set up environment variables ==
Create your <code>.env</code> based on the sample file <code>.env.sample</code>.

Example:
<pre>
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
</pre>
{{Textbox|boxtype=note|header=Different editions|text=To deploy <code>pro</code> or <code>farm</code> edition, you will need credentials to the private registry <code>docker.bluespice.com</code>. Please login in by running <code>docker login docker.bluespice.com</code>.|icon=yes}}

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

Setup:Installation Guide/Docker

2025-07-21T12:27:11Z

Hjing: /* Step 1: Get the stack */

== 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:
# "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/releases/latest

Example:
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

{{Textbox|boxtype=note|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>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.helper-service.yml</code>
| style="" |yml
| style="" |true
| style="" |Provides different helper containers for Filesystem-preparation, major-upgrades and backups
|-
| 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 authentication
|-
| style="width:350px;" |<code>docker-compose.collabpads-service.yml</code>
|yml
|false
|Provides back-end services for [[Manual:Extension/CollabPads|CollabPads]] (included in Pro and Farm editions)
|-
| style="width:350px;" |<code>.env.sample</code>
|text
|true
|Sample for creating <code>.env</code> that defines key environment variables
|-
| style="width:350px;" |<code>bluespice.service.demo</code>
|service script
|false
|A Demo-file for control the BlueSpice stack as systemctl service
|}

For convenience, the <code>bluespice-deploy</code> script wraps the first five <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 service <code>yml</code> files can be loaded by adding <code>-f <filename> </code>.

== Step 2: Set up environment variables ==
Based on the sample file <code>.env.sample</code>, please create your new <code>.env</code> config file or edit your existing config file.

Example:
<pre>
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
</pre>
{{Textbox|boxtype=note|header=Different editions|text=To deploy <code>pro</code> or <code>farm</code> edition, you will need credentials to the private registry <code>docker.bluespice.com</code>. Please login in by running <code>docker login docker.bluespice.com</code>.|icon=yes}}

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

Setup:Installation Guide/Docker

2025-07-21T12:26:08Z

Hjing: /* Step 2: Set up environment variables */

== 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:
# "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/releases/latest

Example:
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

{{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>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.helper-service.yml</code>
| style="" |yml
| style="" |true
| style="" |Provides different helper containers for Filesystem-preparation, major-upgrades and backups
|-
| 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 authentication
|-
| style="width:350px;" |<code>docker-compose.collabpads-service.yml</code>
|yml
|false
|Provides back-end services for [[Manual:Extension/CollabPads|CollabPads]] (included in Pro and Farm editions)
|-
| style="width:350px;" |<code>.env.sample</code>
|text
|true
|Sample for creating <code>.env</code> that defines key environment variables
|-
| style="width:350px;" |<code>bluespice.service.demo</code>
|service script
|false
|A Demo-file for control the BlueSpice stack as systemctl service
|}

For convenience, the <code>bluespice-deploy</code> script wraps the first five <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 service <code>yml</code> files can be loaded by adding <code>-f <filename> </code>.

== Step 2: Set up environment variables ==
Based on the sample file <code>.env.sample</code>, please create your new <code>.env</code> config file or edit your existing config file.

Example:
<pre>
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
</pre>
{{Textbox|boxtype=note|header=Different editions|text=To deploy <code>pro</code> or <code>farm</code> edition, you will need credentials to the private registry <code>docker.bluespice.com</code>. Please login in by running <code>docker login docker.bluespice.com</code>.|icon=yes}}

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

Setup:Installation Guide/Docker

2025-07-21T11:53:03Z

Hjing: /* Step 1: Get the stack */

== 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:
# "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/releases/latest

Example:
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

{{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>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.helper-service.yml</code>
| style="" |yml
| style="" |true
| style="" |Provides different helper containers for Filesystem-preparation, major-upgrades and backups
|-
| 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 authentication
|-
| style="width:350px;" |<code>docker-compose.collabpads-service.yml</code>
|yml
|false
|Provides back-end services for [[Manual:Extension/CollabPads|CollabPads]] (included in Pro and Farm editions)
|-
| style="width:350px;" |<code>.env.sample</code>
|text
|true
|Sample for creating <code>.env</code> that defines key environment variables
|-
| style="width:350px;" |<code>bluespice.service.demo</code>
|service script
|false
|A Demo-file for control the BlueSpice stack as systemctl service
|}

For convenience, the <code>bluespice-deploy</code> script wraps the first five <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 service <code>yml</code> files can be loaded by adding <code>-f <filename> </code>.

== Step 2: Set up environment variables ==
Copy .env.sample to <code>.env</code> and adjust the variables 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: 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/initialAdminPassword</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]]

File:Setup:Installation Guide Docker-Achitecture.png

2025-07-21T11:03:36Z

Hjing: Hjing uploaded a new version of File:Setup:Installation Guide Docker-Achitecture.png

Setup:Installation Guide/Docker

2025-07-21T09:45:47Z

Hjing: /* Step 3: Start the stack */

== 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:
# "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/releases/latest

Example:
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

{{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>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 authentication
|-
| style="width:350px;" |<code>docker-compose.helper-service.yml</code>
|yml
|true
|Provides different helper containers for Filesystem-preparation, major-upgrades and backups
|-
| style="width:350px;" |<code>docker-compose.collabpads-service.yml</code>
|yml
|false
|Provides back-end services for [[Manual:Extension/CollabPads|CollabPads]] (included in Pro and Farm editions)
|-
| style="width:350px;" |<code>.env.sample</code>
|text
|true
|Sample for creating <code>.env</code> that defines key environment variables
|-
| style="width:350px;" |<code>bluespice.service.demo</code>
|service script
|false
|A Demo-file for control the BlueSpice stack as systemctl service
|}

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 ==
Copy .env.sample to <code>.env</code> and adjust the variables 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: 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/initialAdminPassword</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]]

Setup:Installation Guide/Docker

2025-07-18T09:17:10Z

Hjing: fix typos

== 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:
# "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/releases/latest

Example:
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

{{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>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 authentication
|-
| style="width:350px;" |<code>docker-compose.helper-service.yml</code>
|yml
|true
|Provides different helper containers for Filesystem-preparation, major-upgrades and backups
|-
| style="width:350px;" |<code>docker-compose.collabpads-service.yml</code>
|yml
|false
|Provides back-end services for [[Manual:Extension/CollabPads|CollabPads]] (included in Pro and Farm editions)
|-
| style="width:350px;" |<code>.env.sample</code>
|text
|true
|Sample for creating <code>.env</code> that defines key environment variables
|-
| style="width:350px;" |<code>bluespice.service.demo</code>
|service script
|false
|A Demo-file for control the BlueSpice stack as systemctl service
|}

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 ==
Copy .env.sample to <code>.env</code> and adjust the variables 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: 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]]

Setup:Installation Guide/Docker

2025-07-18T08:53:23Z

Hjing: fix table style

== 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:
# "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/releases/latest

Example:
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

{{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>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
|-
| style="width:350px;" |<code>docker-compose.helper-service.yml</code>
|yml
|true
|Provde different help Containers for Filesystem-preparation, Major-Upgrades and Backups(planned)
|-
| style="width:350px;" |<code>docker-compose.collabpads-service.yml</code>
|yml
|false
|Provides Backend for [[Manual:Extension/CollabPads|CollabPads]] (pro and farm only)
|-
| style="width:350px;" |<code>.env.sample</code>
|txt
|true
|A sample of minimum Variables needed for complete distribution
|-
| style="width:350px;" |<code>bluespice.service.demo</code>
|txt
|false
|A Demo-file for control the BluespiceStack as systemctl service
|}

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 ==
Copy .env.sample to <code>.env</code> and adjust the variables 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: 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]]

Setup:Installation Guide/Docker

2025-07-18T08:50:39Z

Hjing: Use release tags instead of the main branch of bluespice-deploy

== 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:
# "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/releases/latest

Example:
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

{{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>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
|-
|docker-compose.helper-service.yml
|yml
|true
|Provde different help Containers for Filesystem-preparation, Major-Upgrades and Backups(planned)
|-
|docker-compose.collabpads-service.yml
|yml
|false
|Provides Backend for [[Manual:Extension/CollabPads|CollabPads]] (pro and farm only)
|-
|.env.sample
|txt
|true
|A sample of minimum Variables needed for complete distribution
|-
|bluespice.service.demo
|txt
|false
|A Demo-file for control the BluespiceStack as systemctl service
|}

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 ==
Copy .env.sample to <code>.env</code> and adjust the variables 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: 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]]

Setup:Installation Guide/Migration from MediaWiki to BlueSpice

2025-06-17T16:30:25Z

Hjing:

==Before you start==
It is important to check the compatibility of your current MediaWiki installation and the BlueSpice version to which you want to migrate:

* BlueSpice version 3.x is based on MediaWiki 1.31.x
* BlueSpice version 4.x until 4.2.7 is based on MediaWiki 1.35.x
* BlueSpice version 4.x starting from 4.3 is based on MediaWiki 1.39.x
* BlueSpice version 5.x is based on MediaWiki 1.43.x

==Backup==
Create a full backup of your current installation. Commands may differ depending on your operating system.

#Create a directory to store the backup:<syntaxhighlight>
mkdir -p /opt/mediawiki-migration-backup/{db,web}
</syntaxhighlight> 
#Create the database dump:<syntaxhighlight>
mysqldump -u DB_USER_OR_ROOT -p MEDIAWIKI_DATABASE_NAME > /opt/mediawiki-migration-backup/db/database.sql
</syntaxhighlight> 
#Copy everything in the web root to the backup folder:<syntaxhighlight>
cp -Rvf /PATH/TO/MEDIAWIKI/FOLDER/* /opt/mediawiki-migration-backup/web/
</syntaxhighlight> 

We will use this backup later for the migration process as well.

==Preparing the migration==
You can create a separate user account and database for BlueSpice. This step is optional but recommended. The following steps are based on such a separately created user and database.

If you choose not to create a separate user account and database, replace the following commands accordingly.

#Create a MySQL/MariaDB user via MySQL CLI:<syntaxhighlight lang="text">
CREATE USER 'bluespice'@'localhost' IDENFITIED BY 'PleaseChooseAComplexPassword';
</syntaxhighlight> 
#Create a database for BlueSpice via MySQL CLI:<syntaxhighlight lang="text">
CREATE DATABASE bluespice;
</syntaxhighlight> 
#Grant the required privileges for the bluespice user to the bluespice database via MySQL CLI:<syntaxhighlight lang="text">
GRANT ALL PRIVILEGES ON bluespice.* TO 'bluespice'@'localhost';
FLUSH PRIVILEGES;
</syntaxhighlight>Now we have an empty SQL database and are ready to import.

==Importing the data==

#Import the SQL dump from the backup you created earlier:<syntaxhighlight lang="text">
mysql -u bluespice -p bluespice < /opt/mediawiki-migration-backup/db/database.sql
</syntaxhighlight>After this command, enter the password you chose for the <code>bluespice</code> database user.
#Next, clean up the old installation folder and create an empty one.<syntaxhighlight lang="text">
rm -Rf /PATH/TO/MEDIAWIKI/FOLDER/
</syntaxhighlight>and<syntaxhighlight lang="text">
mkdir -p /PATH/TO/MEDIAWIKI/FOLDER/
</syntaxhighlight> 
#Next, extract the BlueSpice package and place it into the /PATH/TO/MEDIAWIKI/FOLDER/ <syntaxhighlight lang="text">
cd /PATH/TO/MEDIAWIKI/FOLDER/
</syntaxhighlight> 
#Copy the ''images'' folder from the backup to the /PATH/TO/MEDIAWIKI/FOLDER/ :<syntaxhighlight lang="bash">
cp -Rf /opt/mediawiki-migration-backup/images .
</syntaxhighlight>
#Set the correct permissions based on your operating system to the folder /PATH/TO/MEDIAWIKI/FOLDER/ .

==Configuration settings==

{{Textbox|boxtype=important|header=|text=If you are migrating to [[Setup:Installation_Guide/Docker|a Docker installation]] using <code>bluespice-deploy</code>, your new installation does not provide a concrete <code>LocalSettings.php</code>.

Instead, you can add your customized settings to <code>pre-init-settings.php</code> or <code>post-init-settings.php</code>.

Please check [[Setup:Installation_Guide/Docker#Custom_wiki_application_configuration]] for details.|icon=yes}}
#In /PATH/TO/MEDIAWIKI/FOLDER/, create a new file named ''<code>LocalSettings.php</code>'' and copy the following content into the file:<syntaxhighlight lang="php" line="1">
<?php
# This file was automatically generated by the MediaWiki 1.35.3
# installer. If you make manual changes, please keep track in case you
# need to recreate them later.
#
# See includes/DefaultSettings.php for all configurable settings
# and their default values, but don't forget to make changes in _this_
# file, not there.
#
# Further documentation for configuration settings may be found at:
# https://www.mediawiki.org/wiki/Manual:Configuration_settings

# Protect against web entry
if ( !defined( 'MEDIAWIKI' ) ) {
exit;
}

## Uncomment this to disable output compression
# $wgDisableOutputCompression = true;

$wgSitename = "YOUR_WIKI_NAME";

## The URL base path to the directory containing the wiki;
## defaults for all runtime URL paths are based off of this.
## For more information on customizing the URLs
## (like /w/index.php/Page_title to /wiki/Page_title) please see:
## https://www.mediawiki.org/wiki/Manual:Short_URL
$wgScriptPath = "/w"; # <--- PLEASE CHECK YOUR DOCUMENTROOT

## The protocol and server name to use in fully-qualified URLs
$wgServer = "http(s)://your-domain.ltd";

## The URL path to static resources (images, scripts, etc.)
$wgResourceBasePath = $wgScriptPath;

## The URL paths to the logo. Make sure you change this from the default,
## or else you'll overwrite your logo when you upgrade!
$wgLogos = [ '1x' => "$wgResourceBasePath/resources/assets/wiki.png" ];

## UPO means: this is also a user preference option

$wgEnableEmail = true;
$wgEnableUserEmail = true; # UPO

$wgEmergencyContact = "nomail@localhost.localdomain";
$wgPasswordSender = "nomail@localhost.localdomain";

$wgEnotifUserTalk = false; # UPO
$wgEnotifWatchlist = false; # UPO
$wgEmailAuthentication = true;

## Database settings
$wgDBtype = "mysql";
$wgDBserver = "YOUR_DATABASE_SERVER";
$wgDBname = "bluespice";
$wgDBuser = "bluespice";
$wgDBpassword = "PleaseChooseAComplexPassword";

# MySQL specific settings
$wgDBprefix = "";

# MySQL table options to use during installation or update
$wgDBTableOptions = "ENGINE=InnoDB, DEFAULT CHARSET=binary";

# Shared database table
# This has no effect unless $wgSharedDB is also set.
$wgSharedTables[] = "actor";

## Shared memory settings
$wgMainCacheType = CACHE_NONE;
$wgMemCachedServers = [];

## To enable image uploads, make sure the 'images' directory
## is writable, then set this to true:
$wgEnableUploads = false;
$wgUseImageMagick = true;
$wgImageMagickConvertCommand = "/usr/bin/convert";

# InstantCommons allows wiki to use images from https://commons.wikimedia.org
$wgUseInstantCommons = false;

# Periodically send a pingback to https://www.mediawiki.org/ with basic data
# about this MediaWiki instance. The Wikimedia Foundation shares this data
# with MediaWiki developers to help guide future development efforts.
$wgPingback = false;

## If you use ImageMagick (or any other shell command) on a
## Linux server, this will need to be set to the name of an
## available UTF-8 locale. This should ideally be set to an English
## language locale so that the behaviour of C library functions will
## be consistent with typical installations. Use $wgLanguageCode to
## localise the wiki.
$wgShellLocale = "C.UTF-8";

## Set $wgCacheDirectory to a writable directory on the web server
## to make your wiki go slightly faster. The directory should not
## be publicly accessible from the web.
#$wgCacheDirectory = "$IP/cache";

# Site language code, should be one of the list in ./languages/data/Names.php
$wgLanguageCode = "en";

$wgSecretKey = "68a265061a4101d0d3dee2a06eeb734abaa6710a7dbe103838f2a26a50fc7835";

# Changing this will log out all existing sessions.
$wgAuthenticationTokenVersion = "1";

# Site upgrade key. Must be set to a string (default provided) to turn on the
# web installer while LocalSettings.php is in place
$wgUpgradeKey = "8775d57b99d672b8";

## For attaching licensing metadata to pages, and displaying an
## appropriate copyright notice / icon. GNU Free Documentation
## License and Creative Commons licenses are supported so far.
$wgRightsPage = ""; # Set to the title of a wiki page that describes your license/copyright
$wgRightsUrl = "";
$wgRightsText = "";
$wgRightsIcon = "";

# Path to the GNU diff3 utility. Used for conflict resolution.
$wgDiff3 = "/usr/bin/diff3";

## Default skin: you can change the default skin. Use the internal symbolic
## names, ie 'vector', 'monobook':
$wgDefaultSkin = "bluespicediscovery";

# End of automatically generated settings.
# Add more configuration options below.

# This is the main settings file for all BlueSpice extensions and settings
# It will include all files in "$IP/settings.d/" directory
require_once "$IP/LocalSettings.BlueSpice.php";

$wgUserMergeProtectedGroups = array();
$wgUserMergeUnmergeable = array();
$wgMetaNamespace = 'Project';
$bsgGroupRoles['*']['reader'] = false;

# Convenience for debugging
# $wgShowSQLErrors = true;
# $wgDebugDumpSql = true;
# $wgShowExceptionDetails = true;
# $wgShowDBErrorBacktrace = true;
</syntaxhighlight>
#Edit this ''<code>LocalSettings.php</code>'' and set the correct values to fit your installation. This current ''<code>LocalSettings.php</code>'' might look like different from your MediaWiki installation, because BlueSpice comes with a separate folder for custom settings (''<code>settings.d</code>''). 

==Migrating the system==
The system is ready to migrate.

#Run the following script to start the migration:<syntaxhighlight lang="text">
php /PATH/TO/MEDIAWIKI/FOLDER/maintenance/update.php --quick
</syntaxhighlight>Now BlueSpice should be reachable.
#Execute the following additional scripts (install [[Archive:Setup:Installation_Guide/System_Preparation/Linux/OpenSearch|OpenSearch]] before initiating search index):<syntaxhighlight lang="text">
php /PATH/TO/MEDIAWIKI/FOLDER/maintenance/rebuildall.php

php /PATH/TO/MEDIAWIKI/FOLDER/extensions/BlueSpiceExtendedSearch/maintenance/initBackends.php --quick
php /PATH/TO/MEDIAWIKI/FOLDER/extensions/BlueSpiceExtendedSearch/maintenance/rebuildIndex.php --quick

php /PATH/TO/MEDIAWIKI/FOLDER/maintenance/runJobs.php --memory-limit=max
</syntaxhighlight> 

Your migration is complete and your BlueSpice is ready to use!

You can use your old credentials to login.

==After the migration==
Please check and clean up your <code>MediaWiki:Common.js</code> and <code>MediaWiki:Common.css</code> pages, and inspect if you have any legacy script pieces and style rules that might incompatible with the BlueSpice interface. By default BlueSpice does not have working content in these two pages.

'''Questions?''' Seek help from the [https://community.bluespice.com BlueSpice help forum]

 
[[en:{{FULLPAGENAME}}]]
[[de:Setup:Installationsanleitung/Migration_von_MediaWiki_auf_BlueSpice]]

Setup:Installation Guide/Migration from MediaWiki to BlueSpice

2025-06-17T16:23:47Z

Hjing:

==Before you start==
It is important to check the compatibility of your current MediaWiki installation and the BlueSpice version to which you want to migrate:

* BlueSpice version 3.x is based on MediaWiki 1.31.x
* BlueSpice version 4.x until 4.2.7 is based on MediaWiki 1.35.x
* BlueSpice version 4.x starting from 4.3 is based on MediaWiki 1.39.x
* BlueSpice version 5.x is based on MediaWiki 1.43.x

==Backup==
Create a full backup of your current installation. Commands may differ depending on your operating system.

#Create a directory to store the backup:<syntaxhighlight>
mkdir -p /opt/mediawiki-migration-backup/{db,web}
</syntaxhighlight> 
#Create the database dump:<syntaxhighlight>
mysqldump -u DB_USER_OR_ROOT -p MEDIAWIKI_DATABASE_NAME > /opt/mediawiki-migration-backup/db/database.sql
</syntaxhighlight> 
#Copy everything in the web root to the backup folder:<syntaxhighlight>
cp -Rvf /PATH/TO/MEDIAWIKI/FOLDER/* /opt/mediawiki-migration-backup/web/
</syntaxhighlight> 

We will use this backup later for the migration process as well.

==Preparing the migration==
You can create a separate user account and database for BlueSpice. This step is optional but recommended. The following steps are based on such a separately created user and database.

If you choose not to create a separate user account and database, replace the following commands accordingly.

#Create a MySQL/MariaDB user via MySQL CLI:<syntaxhighlight lang="text">
CREATE USER 'bluespice'@'localhost' IDENFITIED BY 'PleaseChooseAComplexPassword';
</syntaxhighlight> 
#Create a database for BlueSpice via MySQL CLI:<syntaxhighlight lang="text">
CREATE DATABASE bluespice;
</syntaxhighlight> 
#Grant the required privileges for the bluespice user to the bluespice database via MySQL CLI:<syntaxhighlight lang="text">
GRANT ALL PRIVILEGES ON bluespice.* TO 'bluespice'@'localhost';
FLUSH PRIVILEGES;
</syntaxhighlight>Now we have an empty SQL database and are ready to import.

==Importing the data==

#Import the SQL dump from the backup you created earlier:<syntaxhighlight lang="text">
mysql -u bluespice -p bluespice < /opt/mediawiki-migration-backup/db/database.sql
</syntaxhighlight>After this command, enter the password you chose for the <code>bluespice</code> database user.
#Next, clean up the old installation folder and create an empty one.<syntaxhighlight lang="text">
rm -Rf /PATH/TO/MEDIAWIKI/FOLDER/
</syntaxhighlight>and<syntaxhighlight lang="text">
mkdir -p /PATH/TO/MEDIAWIKI/FOLDER/
</syntaxhighlight> 
#Next, extract the BlueSpice package and place it into the /PATH/TO/MEDIAWIKI/FOLDER/ <syntaxhighlight lang="text">
cd /PATH/TO/MEDIAWIKI/FOLDER/
</syntaxhighlight> 
#Copy the ''images'' folder from the backup to the /PATH/TO/MEDIAWIKI/FOLDER/ :<syntaxhighlight lang="bash">
cp -Rf /opt/mediawiki-migration-backup/images .
</syntaxhighlight>
#Set the correct permissions based on your operating system to the folder /PATH/TO/MEDIAWIKI/FOLDER/ .

==Configuration settings==

{{Textbox|boxtype=important|header=|text=If you are migrating to [[Setup:Installation_Guide/Docker|a Docker installation]] using <code>bluespice-deploy</code>, your new installation does not provide a concrete <code>LocalSettings.php</code>.

Instead, you can add your customized settings to <code>pre-init-settings.php</code> or <code>post-init-settings.php</code>.

Please check [[Setup:Installation_Guide/Docker#Custom_wiki_application_configuration]] for details.|icon=yes}}
#In /PATH/TO/MEDIAWIKI/FOLDER/, create a new file named ''<code>LocalSettings.php</code>'' and copy the following content into the file:<syntaxhighlight lang="php" line="1">
<?php
# This file was automatically generated by the MediaWiki 1.35.3
# installer. If you make manual changes, please keep track in case you
# need to recreate them later.
#
# See includes/DefaultSettings.php for all configurable settings
# and their default values, but don't forget to make changes in _this_
# file, not there.
#
# Further documentation for configuration settings may be found at:
# https://www.mediawiki.org/wiki/Manual:Configuration_settings

# Protect against web entry
if ( !defined( 'MEDIAWIKI' ) ) {
exit;
}

## Uncomment this to disable output compression
# $wgDisableOutputCompression = true;

$wgSitename = "YOUR_WIKI_NAME";

## The URL base path to the directory containing the wiki;
## defaults for all runtime URL paths are based off of this.
## For more information on customizing the URLs
## (like /w/index.php/Page_title to /wiki/Page_title) please see:
## https://www.mediawiki.org/wiki/Manual:Short_URL
$wgScriptPath = "/w"; # <--- PLEASE CHECK YOUR DOCUMENTROOT

## The protocol and server name to use in fully-qualified URLs
$wgServer = "http(s)://your-domain.ltd";

## The URL path to static resources (images, scripts, etc.)
$wgResourceBasePath = $wgScriptPath;

## The URL paths to the logo. Make sure you change this from the default,
## or else you'll overwrite your logo when you upgrade!
$wgLogos = [ '1x' => "$wgResourceBasePath/resources/assets/wiki.png" ];

## UPO means: this is also a user preference option

$wgEnableEmail = true;
$wgEnableUserEmail = true; # UPO

$wgEmergencyContact = "nomail@localhost.localdomain";
$wgPasswordSender = "nomail@localhost.localdomain";

$wgEnotifUserTalk = false; # UPO
$wgEnotifWatchlist = false; # UPO
$wgEmailAuthentication = true;

## Database settings
$wgDBtype = "mysql";
$wgDBserver = "YOUR_DATABASE_SERVER";
$wgDBname = "bluespice";
$wgDBuser = "bluespice";
$wgDBpassword = "PleaseChooseAComplexPassword";

# MySQL specific settings
$wgDBprefix = "";

# MySQL table options to use during installation or update
$wgDBTableOptions = "ENGINE=InnoDB, DEFAULT CHARSET=binary";

# Shared database table
# This has no effect unless $wgSharedDB is also set.
$wgSharedTables[] = "actor";

## Shared memory settings
$wgMainCacheType = CACHE_NONE;
$wgMemCachedServers = [];

## To enable image uploads, make sure the 'images' directory
## is writable, then set this to true:
$wgEnableUploads = false;
$wgUseImageMagick = true;
$wgImageMagickConvertCommand = "/usr/bin/convert";

# InstantCommons allows wiki to use images from https://commons.wikimedia.org
$wgUseInstantCommons = false;

# Periodically send a pingback to https://www.mediawiki.org/ with basic data
# about this MediaWiki instance. The Wikimedia Foundation shares this data
# with MediaWiki developers to help guide future development efforts.
$wgPingback = false;

## If you use ImageMagick (or any other shell command) on a
## Linux server, this will need to be set to the name of an
## available UTF-8 locale. This should ideally be set to an English
## language locale so that the behaviour of C library functions will
## be consistent with typical installations. Use $wgLanguageCode to
## localise the wiki.
$wgShellLocale = "C.UTF-8";

## Set $wgCacheDirectory to a writable directory on the web server
## to make your wiki go slightly faster. The directory should not
## be publicly accessible from the web.
#$wgCacheDirectory = "$IP/cache";

# Site language code, should be one of the list in ./languages/data/Names.php
$wgLanguageCode = "en";

$wgSecretKey = "68a265061a4101d0d3dee2a06eeb734abaa6710a7dbe103838f2a26a50fc7835";

# Changing this will log out all existing sessions.
$wgAuthenticationTokenVersion = "1";

# Site upgrade key. Must be set to a string (default provided) to turn on the
# web installer while LocalSettings.php is in place
$wgUpgradeKey = "8775d57b99d672b8";

## For attaching licensing metadata to pages, and displaying an
## appropriate copyright notice / icon. GNU Free Documentation
## License and Creative Commons licenses are supported so far.
$wgRightsPage = ""; # Set to the title of a wiki page that describes your license/copyright
$wgRightsUrl = "";
$wgRightsText = "";
$wgRightsIcon = "";

# Path to the GNU diff3 utility. Used for conflict resolution.
$wgDiff3 = "/usr/bin/diff3";

## Default skin: you can change the default skin. Use the internal symbolic
## names, ie 'vector', 'monobook':
$wgDefaultSkin = "bluespicediscovery";

# End of automatically generated settings.
# Add more configuration options below.

# This is the main settings file for all BlueSpice extensions and settings
# It will include all files in "$IP/settings.d/" directory
require_once "$IP/LocalSettings.BlueSpice.php";

$wgUserMergeProtectedGroups = array();
$wgUserMergeUnmergeable = array();
$wgMetaNamespace = 'Project';
$bsgGroupRoles['*']['reader'] = false;

# Convenience for debugging
# $wgShowSQLErrors = true;
# $wgDebugDumpSql = true;
# $wgShowExceptionDetails = true;
# $wgShowDBErrorBacktrace = true;
</syntaxhighlight>
#Edit this ''<code>LocalSettings.php</code>'' and set the correct values to fit your installation. This current ''<code>LocalSettings.php</code>'' might look like different from your MediaWiki installation, because BlueSpice comes with a separate folder for custom settings (''<code>settings.d</code>''). 

==Migrating the system==
The system is ready to migrate.

#Run the following script to start the migration:<syntaxhighlight lang="text">
php /PATH/TO/MEDIAWIKI/FOLDER/maintenance/update.php --quick
</syntaxhighlight>Now BlueSpice should be reachable.
#Execute the following additional scripts (install [[Archive:Setup:Installation_Guide/System_Preparation/Linux/OpenSearch|opensearch]] before initiating search index):<syntaxhighlight lang="text">
php /PATH/TO/MEDIAWIKI/FOLDER/maintenance/rebuildall.php

php /PATH/TO/MEDIAWIKI/FOLDER/extensions/BlueSpiceExtendedSearch/maintenance/initBackends.php --quick
php /PATH/TO/MEDIAWIKI/FOLDER/extensions/BlueSpiceExtendedSearch/maintenance/rebuildIndex.php --quick

php /PATH/TO/MEDIAWIKI/FOLDER/maintenance/runJobs.php --memory-limit=max
</syntaxhighlight> 

Your migration is complete and your BlueSpice is ready to use!

You can use your old credentials to login.

==After the migration==
Please check and clean up your <code>MediaWiki:Common.js</code> and <code>MediaWiki:Common.css</code> pages, and inspect if you have any legacy script pieces and style rules that might incompatible with the BlueSpice interface. By default BlueSpice does not have working content in these two pages.

'''Questions?''' Seek help from the [https://community.bluespice.com BlueSpice help forum]

 
[[en:{{FULLPAGENAME}}]]
[[de:Setup:Installationsanleitung/Migration_von_MediaWiki_auf_BlueSpice]]

Setup:Installation Guide/Migration from MediaWiki to BlueSpice

2025-06-17T16:23:27Z

Hjing:

==Before you start==
It is important to check the compatibility of your current MediaWiki installation and the BlueSpice version to which you want to migrate:

* BlueSpice version 3.x is based on MediaWiki 1.31.x
* BlueSpice version 4.x until 4.2.7 is based on MediaWiki 1.35.x
* BlueSpice version 4.x starting from 4.3 is based on MediaWiki 1.39.x
* BlueSpice version 5.x is based on MediaWiki 1.43.x

==Backup==
Create a full backup of your current installation. Commands may differ depending on your operating system.

#Create a directory to store the backup:<syntaxhighlight>
mkdir -p /opt/mediawiki-migration-backup/{db,web}
</syntaxhighlight> 
#Create the database dump:<syntaxhighlight>
mysqldump -u DB_USER_OR_ROOT -p MEDIAWIKI_DATABASE_NAME > /opt/mediawiki-migration-backup/db/database.sql
</syntaxhighlight> 
#Copy everything in the web root to the backup folder:<syntaxhighlight>
cp -Rvf /PATH/TO/MEDIAWIKI/FOLDER/* /opt/mediawiki-migration-backup/web/
</syntaxhighlight> 

We will use this backup later for the migration process as well.

==Preparing the migration==
You can create a separate user account and database for BlueSpice. This step is optional but recommended. The following steps are based on such a separately created user and database.

If you choose not to create a separate user account and database, replace the following commands accordingly.

#Create a MySQL/MariaDB user via MySQL CLI:<syntaxhighlight lang="text">
CREATE USER 'bluespice'@'localhost' IDENFITIED BY 'PleaseChooseAComplexPassword';
</syntaxhighlight> 
#Create a database for BlueSpice via MySQL CLI:<syntaxhighlight lang="text">
CREATE DATABASE bluespice;
</syntaxhighlight> 
#Grant the required privileges for the bluespice user to the bluespice database via MySQL CLI:<syntaxhighlight lang="text">
GRANT ALL PRIVILEGES ON bluespice.* TO 'bluespice'@'localhost';
FLUSH PRIVILEGES;
</syntaxhighlight>Now we have an empty SQL database and are ready to import.

==Importing the data==

#Import the SQL dump from the backup you created earlier:<syntaxhighlight lang="text">
mysql -u bluespice -p bluespice < /opt/mediawiki-migration-backup/db/database.sql
</syntaxhighlight>After this command, enter the password you chose for the <code>bluespice</code> database user.
#Next, clean up the old installation folder and create an empty one.<syntaxhighlight lang="text">
rm -Rf /PATH/TO/MEDIAWIKI/FOLDER/
</syntaxhighlight>and<syntaxhighlight lang="text">
mkdir -p /PATH/TO/MEDIAWIKI/FOLDER/
</syntaxhighlight> 
#Next, extract the BlueSpice package and place it into the /PATH/TO/MEDIAWIKI/FOLDER/ <syntaxhighlight lang="text">
cd /PATH/TO/MEDIAWIKI/FOLDER/
</syntaxhighlight> 
#Copy the ''images'' folder from the backup to the /PATH/TO/MEDIAWIKI/FOLDER/ :<syntaxhighlight lang="bash">
cp -Rf /opt/mediawiki-migration-backup/images .
</syntaxhighlight>
#Set the correct permissions based on your operating system to the folder /PATH/TO/MEDIAWIKI/FOLDER/ .

==Configuration settings==

{{Textbox|boxtype=important|header=|text=If you are migrating to [[Setup:Installation_Guide/Docker|a Docker installation]] using <code>bluespice-deploy</code>, your new installation does not provide a concrete <code>LocalSettings.php</code>.

Instead, you can add your customized settings to <code>pre-init-settings.php</code> or <code>post-init-settings.php</code>.

Please check [[Setup:Installation_Guide/Docker#Custom_wiki_application_configuration]] for details.|icon=yes}}
#In /PATH/TO/MEDIAWIKI/FOLDER/, create a new file named ''<code>LocalSettings.php</code>'' and copy the following content into the file:<syntaxhighlight lang="php" line="1">
<?php
# This file was automatically generated by the MediaWiki 1.35.3
# installer. If you make manual changes, please keep track in case you
# need to recreate them later.
#
# See includes/DefaultSettings.php for all configurable settings
# and their default values, but don't forget to make changes in _this_
# file, not there.
#
# Further documentation for configuration settings may be found at:
# https://www.mediawiki.org/wiki/Manual:Configuration_settings

# Protect against web entry
if ( !defined( 'MEDIAWIKI' ) ) {
exit;
}

## Uncomment this to disable output compression
# $wgDisableOutputCompression = true;

$wgSitename = "YOUR_WIKI_NAME";

## The URL base path to the directory containing the wiki;
## defaults for all runtime URL paths are based off of this.
## For more information on customizing the URLs
## (like /w/index.php/Page_title to /wiki/Page_title) please see:
## https://www.mediawiki.org/wiki/Manual:Short_URL
$wgScriptPath = "/w"; # <--- PLEASE CHECK YOUR DOCUMENTROOT

## The protocol and server name to use in fully-qualified URLs
$wgServer = "http(s)://your-domain.ltd";

## The URL path to static resources (images, scripts, etc.)
$wgResourceBasePath = $wgScriptPath;

## The URL paths to the logo. Make sure you change this from the default,
## or else you'll overwrite your logo when you upgrade!
$wgLogos = [ '1x' => "$wgResourceBasePath/resources/assets/wiki.png" ];

## UPO means: this is also a user preference option

$wgEnableEmail = true;
$wgEnableUserEmail = true; # UPO

$wgEmergencyContact = "nomail@localhost.localdomain";
$wgPasswordSender = "nomail@localhost.localdomain";

$wgEnotifUserTalk = false; # UPO
$wgEnotifWatchlist = false; # UPO
$wgEmailAuthentication = true;

## Database settings
$wgDBtype = "mysql";
$wgDBserver = "YOUR_DATABASE_SERVER";
$wgDBname = "bluespice";
$wgDBuser = "bluespice";
$wgDBpassword = "PleaseChooseAComplexPassword";

# MySQL specific settings
$wgDBprefix = "";

# MySQL table options to use during installation or update
$wgDBTableOptions = "ENGINE=InnoDB, DEFAULT CHARSET=binary";

# Shared database table
# This has no effect unless $wgSharedDB is also set.
$wgSharedTables[] = "actor";

## Shared memory settings
$wgMainCacheType = CACHE_NONE;
$wgMemCachedServers = [];

## To enable image uploads, make sure the 'images' directory
## is writable, then set this to true:
$wgEnableUploads = false;
$wgUseImageMagick = true;
$wgImageMagickConvertCommand = "/usr/bin/convert";

# InstantCommons allows wiki to use images from https://commons.wikimedia.org
$wgUseInstantCommons = false;

# Periodically send a pingback to https://www.mediawiki.org/ with basic data
# about this MediaWiki instance. The Wikimedia Foundation shares this data
# with MediaWiki developers to help guide future development efforts.
$wgPingback = false;

## If you use ImageMagick (or any other shell command) on a
## Linux server, this will need to be set to the name of an
## available UTF-8 locale. This should ideally be set to an English
## language locale so that the behaviour of C library functions will
## be consistent with typical installations. Use $wgLanguageCode to
## localise the wiki.
$wgShellLocale = "C.UTF-8";

## Set $wgCacheDirectory to a writable directory on the web server
## to make your wiki go slightly faster. The directory should not
## be publicly accessible from the web.
#$wgCacheDirectory = "$IP/cache";

# Site language code, should be one of the list in ./languages/data/Names.php
$wgLanguageCode = "en";

$wgSecretKey = "68a265061a4101d0d3dee2a06eeb734abaa6710a7dbe103838f2a26a50fc7835";

# Changing this will log out all existing sessions.
$wgAuthenticationTokenVersion = "1";

# Site upgrade key. Must be set to a string (default provided) to turn on the
# web installer while LocalSettings.php is in place
$wgUpgradeKey = "8775d57b99d672b8";

## For attaching licensing metadata to pages, and displaying an
## appropriate copyright notice / icon. GNU Free Documentation
## License and Creative Commons licenses are supported so far.
$wgRightsPage = ""; # Set to the title of a wiki page that describes your license/copyright
$wgRightsUrl = "";
$wgRightsText = "";
$wgRightsIcon = "";

# Path to the GNU diff3 utility. Used for conflict resolution.
$wgDiff3 = "/usr/bin/diff3";

## Default skin: you can change the default skin. Use the internal symbolic
## names, ie 'vector', 'monobook':
$wgDefaultSkin = "bluespicediscovery";

# End of automatically generated settings.
# Add more configuration options below.

# This is the main settings file for all BlueSpice extensions and settings
# It will include all files in "$IP/settings.d/" directory
require_once "$IP/LocalSettings.BlueSpice.php";

$wgUserMergeProtectedGroups = array();
$wgUserMergeUnmergeable = array();
$wgMetaNamespace = 'Project';
$bsgGroupRoles['*']['reader'] = false;

# Convenience for debugging
# $wgShowSQLErrors = true;
# $wgDebugDumpSql = true;
# $wgShowExceptionDetails = true;
# $wgShowDBErrorBacktrace = true;
</syntaxhighlight>
#Edit this ''<code>LocalSettings.php</code>'' and set the correct values to fit your installation. This current ''<code>LocalSettings.php</code>'' might look like different from your MediaWiki installation, because BlueSpice comes with a separate folder for custom settings (''<code>settings.d</code>''). 

==Migrating the system==
The system is ready to migrate.

#Run the following script to start the migration:<syntaxhighlight lang="text">
php /PATH/TO/MEDIAWIKI/FOLDER/maintenance/update.php --quick
</syntaxhighlight>Now BlueSpice should be reachable.
#Execute the following additional scripts (install [[Archive:Setup:Installation_Guide/System_Preparation/Linux/OpenSearch|opensearch]] before initiating search index):
<syntaxhighlight lang="text">
php /PATH/TO/MEDIAWIKI/FOLDER/maintenance/rebuildall.php

php /PATH/TO/MEDIAWIKI/FOLDER/extensions/BlueSpiceExtendedSearch/maintenance/initBackends.php --quick
php /PATH/TO/MEDIAWIKI/FOLDER/extensions/BlueSpiceExtendedSearch/maintenance/rebuildIndex.php --quick

php /PATH/TO/MEDIAWIKI/FOLDER/maintenance/runJobs.php --memory-limit=max
</syntaxhighlight> 

Your migration is complete and your BlueSpice is ready to use!

You can use your old credentials to login.

==After the migration==
Please check and clean up your <code>MediaWiki:Common.js</code> and <code>MediaWiki:Common.css</code> pages, and inspect if you have any legacy script pieces and style rules that might incompatible with the BlueSpice interface. By default BlueSpice does not have working content in these two pages.

'''Questions?''' Seek help from the [https://community.bluespice.com BlueSpice help forum]

 
[[en:{{FULLPAGENAME}}]]
[[de:Setup:Installationsanleitung/Migration_von_MediaWiki_auf_BlueSpice]]

Setup:Installation Guide/Migration from MediaWiki to BlueSpice

2025-06-13T12:35:44Z

Hjing: Correct MW version, add docker hint and Common.js/.css hint, correct community link

==Before you start==
It is important to check the compatibility of your current MediaWiki installation and the BlueSpice version to which you want to migrate:

* BlueSpice version 3.x is based on MediaWiki 1.31.x
* BlueSpice version 4.x until 4.2.7 is based on MediaWiki 1.35.x
* BlueSpice version 4.x starting from 4.3 is based on MediaWiki 1.39.x
* BlueSpice version 5.x is based on MediaWiki 1.43.x

==Backup==
Create a full backup of your current installation. Commands may differ depending on your operating system.

#Create a directory to store the backup:<syntaxhighlight>
mkdir -p /opt/mediawiki-migration-backup/{db,web}
</syntaxhighlight> 
#Create the database dump:<syntaxhighlight>
mysqldump -u DB_USER_OR_ROOT -p MEDIAWIKI_DATABASE_NAME > /opt/mediawiki-migration-backup/db/database.sql
</syntaxhighlight> 
#Copy everything in the web root to the backup folder:<syntaxhighlight>
cp -Rvf /PATH/TO/MEDIAWIKI/FOLDER/* /opt/mediawiki-migration-backup/web/
</syntaxhighlight> 

We will use this backup later for the migration process as well.

==Preparing the migration==
You can create a separate user account and database for BlueSpice. This step is optional but recommended. The following steps are based on such a separately created user and database.

If you choose not to create a separate user account and database, replace the following commands accordingly.

#Create a MySQL/MariaDB user via MySQL CLI:<syntaxhighlight lang="text">
CREATE USER 'bluespice'@'localhost' IDENFITIED BY 'PleaseChooseAComplexPassword';
</syntaxhighlight> 
#Create a database for BlueSpice via MySQL CLI:<syntaxhighlight lang="text">
CREATE DATABASE bluespice;
</syntaxhighlight> 
#Grant the required privileges for the bluespice user to the bluespice database via MySQL CLI:<syntaxhighlight lang="text">
GRANT ALL PRIVILEGES ON bluespice.* TO 'bluespice'@'localhost';
FLUSH PRIVILEGES;
</syntaxhighlight>Now we have an empty SQL database and are ready to import.

==Importing the data==

#Import the SQL dump from the backup you created earlier:<syntaxhighlight lang="text">
mysql -u bluespice -p bluespice < /opt/mediawiki-migration-backup/db/database.sql
</syntaxhighlight>After this command, enter the password you chose for the <code>bluespice</code> database user.
#Next, clean up the old installation folder and create an empty one.<syntaxhighlight lang="text">
rm -Rf /PATH/TO/MEDIAWIKI/FOLDER/
</syntaxhighlight>and<syntaxhighlight lang="text">
mkdir -p /PATH/TO/MEDIAWIKI/FOLDER/
</syntaxhighlight> 
#Next, extract the BlueSpice package and place it into the /PATH/TO/MEDIAWIKI/FOLDER/ <syntaxhighlight lang="text">
cd /PATH/TO/MEDIAWIKI/FOLDER/
</syntaxhighlight> 
#Copy the ''images'' folder from the backup to the /PATH/TO/MEDIAWIKI/FOLDER/ :<syntaxhighlight lang="bash">
cp -Rf /opt/mediawiki-migration-backup/images .
</syntaxhighlight>
#Set the correct permissions based on your operating system to the folder /PATH/TO/MEDIAWIKI/FOLDER/ .

==Configuration settings==

{{Textbox|boxtype=important|header=|text=If you are migrating to [[Setup:Installation_Guide/Docker|a Docker installation]] using <code>bluespice-deploy</code>, your new installation does not provide a concrete <code>LocalSettings.php</code>.

Instead, you can add your customized settings to <code>pre-init-settings.php</code> or <code>post-init-settings.php</code>.

Please check [[Setup:Installation_Guide/Docker#Custom_wiki_application_configuration]] for details.|icon=yes}}
#In /PATH/TO/MEDIAWIKI/FOLDER/, create a new file named ''<code>LocalSettings.php</code>'' and copy the following content into the file:<syntaxhighlight lang="php" line="1">
<?php
# This file was automatically generated by the MediaWiki 1.35.3
# installer. If you make manual changes, please keep track in case you
# need to recreate them later.
#
# See includes/DefaultSettings.php for all configurable settings
# and their default values, but don't forget to make changes in _this_
# file, not there.
#
# Further documentation for configuration settings may be found at:
# https://www.mediawiki.org/wiki/Manual:Configuration_settings

# Protect against web entry
if ( !defined( 'MEDIAWIKI' ) ) {
exit;
}

## Uncomment this to disable output compression
# $wgDisableOutputCompression = true;

$wgSitename = "YOUR_WIKI_NAME";

## The URL base path to the directory containing the wiki;
## defaults for all runtime URL paths are based off of this.
## For more information on customizing the URLs
## (like /w/index.php/Page_title to /wiki/Page_title) please see:
## https://www.mediawiki.org/wiki/Manual:Short_URL
$wgScriptPath = "/w"; # <--- PLEASE CHECK YOUR DOCUMENTROOT

## The protocol and server name to use in fully-qualified URLs
$wgServer = "http(s)://your-domain.ltd";

## The URL path to static resources (images, scripts, etc.)
$wgResourceBasePath = $wgScriptPath;

## The URL paths to the logo. Make sure you change this from the default,
## or else you'll overwrite your logo when you upgrade!
$wgLogos = [ '1x' => "$wgResourceBasePath/resources/assets/wiki.png" ];

## UPO means: this is also a user preference option

$wgEnableEmail = true;
$wgEnableUserEmail = true; # UPO

$wgEmergencyContact = "nomail@localhost.localdomain";
$wgPasswordSender = "nomail@localhost.localdomain";

$wgEnotifUserTalk = false; # UPO
$wgEnotifWatchlist = false; # UPO
$wgEmailAuthentication = true;

## Database settings
$wgDBtype = "mysql";
$wgDBserver = "YOUR_DATABASE_SERVER";
$wgDBname = "bluespice";
$wgDBuser = "bluespice";
$wgDBpassword = "PleaseChooseAComplexPassword";

# MySQL specific settings
$wgDBprefix = "";

# MySQL table options to use during installation or update
$wgDBTableOptions = "ENGINE=InnoDB, DEFAULT CHARSET=binary";

# Shared database table
# This has no effect unless $wgSharedDB is also set.
$wgSharedTables[] = "actor";

## Shared memory settings
$wgMainCacheType = CACHE_NONE;
$wgMemCachedServers = [];

## To enable image uploads, make sure the 'images' directory
## is writable, then set this to true:
$wgEnableUploads = false;
$wgUseImageMagick = true;
$wgImageMagickConvertCommand = "/usr/bin/convert";

# InstantCommons allows wiki to use images from https://commons.wikimedia.org
$wgUseInstantCommons = false;

# Periodically send a pingback to https://www.mediawiki.org/ with basic data
# about this MediaWiki instance. The Wikimedia Foundation shares this data
# with MediaWiki developers to help guide future development efforts.
$wgPingback = false;

## If you use ImageMagick (or any other shell command) on a
## Linux server, this will need to be set to the name of an
## available UTF-8 locale. This should ideally be set to an English
## language locale so that the behaviour of C library functions will
## be consistent with typical installations. Use $wgLanguageCode to
## localise the wiki.
$wgShellLocale = "C.UTF-8";

## Set $wgCacheDirectory to a writable directory on the web server
## to make your wiki go slightly faster. The directory should not
## be publicly accessible from the web.
#$wgCacheDirectory = "$IP/cache";

# Site language code, should be one of the list in ./languages/data/Names.php
$wgLanguageCode = "en";

$wgSecretKey = "68a265061a4101d0d3dee2a06eeb734abaa6710a7dbe103838f2a26a50fc7835";

# Changing this will log out all existing sessions.
$wgAuthenticationTokenVersion = "1";

# Site upgrade key. Must be set to a string (default provided) to turn on the
# web installer while LocalSettings.php is in place
$wgUpgradeKey = "8775d57b99d672b8";

## For attaching licensing metadata to pages, and displaying an
## appropriate copyright notice / icon. GNU Free Documentation
## License and Creative Commons licenses are supported so far.
$wgRightsPage = ""; # Set to the title of a wiki page that describes your license/copyright
$wgRightsUrl = "";
$wgRightsText = "";
$wgRightsIcon = "";

# Path to the GNU diff3 utility. Used for conflict resolution.
$wgDiff3 = "/usr/bin/diff3";

## Default skin: you can change the default skin. Use the internal symbolic
## names, ie 'vector', 'monobook':
$wgDefaultSkin = "bluespicediscovery";

# End of automatically generated settings.
# Add more configuration options below.

# This is the main settings file for all BlueSpice extensions and settings
# It will include all files in "$IP/settings.d/" directory
require_once "$IP/LocalSettings.BlueSpice.php";

$wgUserMergeProtectedGroups = array();
$wgUserMergeUnmergeable = array();
$wgMetaNamespace = 'Project';
$bsgGroupRoles['*']['reader'] = false;

# Convenience for debugging
# $wgShowSQLErrors = true;
# $wgDebugDumpSql = true;
# $wgShowExceptionDetails = true;
# $wgShowDBErrorBacktrace = true;
</syntaxhighlight>
#Edit this ''<code>LocalSettings.php</code>'' and set the correct values to fit your installation. This current ''<code>LocalSettings.php</code>'' might look like different from your MediaWiki installation, because BlueSpice comes with a separate folder for custom settings (''<code>settings.d</code>''). 

==Migrating the system==
The system is ready to migrate.

#Run the following script to start the migration:<syntaxhighlight lang="text">
php /PATH/TO/MEDIAWIKI/FOLDER/maintenance/update.php --quick
</syntaxhighlight>Now BlueSpice should be reachable.
#Execute the following additional scripts:<syntaxhighlight lang="text">
php /PATH/TO/MEDIAWIKI/FOLDER/maintenance/rebuildall.php
#Finally for the search index (ElasticSearch 6.x and ingest-attachment plugins must be installed) php /PATH/TO/MEDIAWIKI/FOLDER/extensions/BlueSpiceExtendedSearch/maintenance/initBackends.php --quick
php /PATH/TO/MEDIAWIKI/FOLDER/extensions/BlueSpiceExtendedSearch/maintenance/rebuildIndex.php --quick
php /PATH/TO/MEDIAWIKI/FOLDER/maintenance/runJobs.php --memory-limit=max
</syntaxhighlight> 

Your migration is complete and your BlueSpice is ready to use!

You can use your old credentials to login.

==After the migration==
Please check and clean up your <code>MediaWiki:Common.js</code> and <code>MediaWiki:Common.css</code> pages, and inspect if you have any legacy script pieces and style rules that might incompatible with the BlueSpice interface. By default BlueSpice does not have working content in these two pages.

'''Questions?''' Seek help from the [https://community.bluespice.com BlueSpice help forum]

 
[[en:{{FULLPAGENAME}}]]
[[de:Setup:Installationsanleitung/Migration_von_MediaWiki_auf_BlueSpice]]

User blog:Hjing

2025-04-04T13:19:12Z

Hjing: Root blog page created

Setup:Installation Guide/Docker

2025-02-24T07:25:31Z

Hjing: Correct typo of certificate directory

{{Textbox
|boxtype=important
|header=Migration from 4.4
|text=With BlueSpice 4.5 there were some important changes to the container portfolio:
# There are no "all-in-one" containers anymore. Neither for FREE, nor for PRO and FARM editions
# 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 [[{{FULLPAGENAME}}/Migration_4.4 to 4.5|migration guide]]
|icon=yes
}}

__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=important|header=PRO and FARM editions|text=All services configurations for PRO and FARM edition are already included, but access to private <code>docker.bluespice.com</code> is required to obtain the images.|icon=yes}}

The directory contains the following files:
{| class="wikitable"
|+
! style="width:350px;" |Filename
!Type
!Mandatory
!Comment
|-
| style="width:350px;" |<code>bluespice-deploy</code>
|bash-script
|false
|Wrapper for general start-up of needed containers
|-
| style="width:350px;" |<code>bluespice-prepare</code>
|bash-script
|false
|Prepare Folder and Permissions before first start also registers the service at the operating system
|-
| style="width:350px;" |<code>bluespice.service</code>
|service-script
|false
|Proper handling of the containers on reboot
|-
| style="width:350px;" |<code>docker-compose.main.yml</code>
|yml
|true
|Main application services/ run by <code>bluespice-deploy</code>
|-
| style="width:350px;" |<code>docker-compose.persistent-data-services.yml</code>
|yml
|false
|Database and search/ run by <code>bluespice-deploy</code>
|-
| style="width:350px;" |<code>docker-compose.stateless-services.yml</code>
|yml
|true
|PDF-Renderer/Cache/Formula/Diagram-Service
|-
| style="width:350px;" |<code>docker-compose.proxy.yml</code>
|yml
|false, but recommended
|Proxy Service
|-
| style="width:350px;" |<code>docker-compose.proxy-letsencrypt.yml</code>
|yml
|false
|Additional auto-renewal service for "Let's Encrypt" certificates
|-
| style="width:350px;" |<code>docker-compose.kerberos-proxy.yml</code>
|yml
|false
|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=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=...
{{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:
ExecStart=<WORKDIR>/bluespice-deploy -f docker-compose.proxy-letsencrypt.yml up -f -d --remove-orphans
|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]]

Setup:Installation Guide/Docker

2025-01-07T07:34:43Z

Hjing: Correct typo of command in /* Step 1: Get the stack */

{{Textbox
|boxtype=important
|header=Migration from 4.4
|text=With BlueSpice 4.5 there were some important changes to the container portfolio:
# There are no "all-in-one" containers anymore. Neither for FREE, nor for PRO and FARM editions
# 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 [[{{FULLPAGENAME}}/Migration_4.4 to 4.5|migration guide]]
|icon=yes
}}

__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 port in use, based on the setup. Some examples:
** When using LDAP based authentication an LDAPS connection (port 636) is used from the <code>bluespice/wiki</code> containers to the LDAP-Server
** When using Kerberos authentication, a connection (port 88) is used from the <code>bluespice/kerberos-proxy</code> containers to the Kerberos-Server
** When using DeepL or OpenAI services, a HTTPS connection (port 443) is used from the <code>bluespice/wiki</code> containers to to the respective service
** When using OpenIDConnect authentication, a HTTPS connection (port 443) 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 443) 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://bluespice.com/de/download/
wget <nowiki>https://bluespice.com/filebase/docker-deployment-script</nowiki> \
&& unzip docker-deployment-script \
&& cd bluespice-deploy-main/compose

The directory contains the following files:
{| class="wikitable"
|+
! style="width:350px;" |Filename
!Type
!Mandatory
!Comment
|-
| style="width:350px;" |<code>bluespice-deploy</code>
|bash-script
|false
|Wrapper for general start-up of needed containers
|-
| style="width:350px;" |<code>bluespice-prepare</code>
|bash-script
|false
|Prepare Folder and Permissions before first start also registers the service at the operating system
|-
| style="width:350px;" |<code>bluespice.service</code>
|service-script
|false
|Proper handling of the containers on reboot
|-
| style="width:350px;" |<code>docker-compose.main.yml</code>
|yml
|true
|Main application services/ run by <code>bluespice-deploy</code>
|-
| style="width:350px;" |<code>docker-compose.persistent-data-services.yml</code>
|yml
|false
|Database and search/ run by <code>bluespice-deploy</code>
|-
| style="width:350px;" |<code>docker-compose.stateless-services.yml</code>
|yml
|true
|PDF-Renderer/Cache/Formula/Diagram-Service
|-
| style="width:350px;" |<code>docker-compose.proxy.yml</code>
|yml
|false, but recommended
|Proxy Service
|-
| style="width:350px;" |<code>docker-compose.proxy-letsencrypt.yml</code>
|yml
|false
|Additional auto-renewal service for "Let's Encrypt" certificates
|-
| style="width:350px;" |<code>docker-compose.kerberos-proxy.yml</code>
|yml
|false
|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>.

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| SSL certificates]].

===Step 2: Set up environment variables===
Create <code>.env</code> 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=...
{{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.bluspice.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/adminPasssword</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 add <code>docker-compose.proxy-letsencrypt.yml</code> in your <code>bluespice-deploy</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>${VOLUMES_DIR}/nginx/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:
ExecStart=<WORKDIR>/bluespice-deploy -f docker-compose.proxy-letsencrypt.yml up -f -d --remove-orphans
|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]]

Reference:NumberHeadings

2024-10-29T15:13:20Z

Hjing:

{{BSExtensionInfo
|status=stable
|developer=HalloWelt
|type=MediaWiki
|edition=BlueSpice pro, BlueSpice farm, BlueSpice cloud
|compatible=MediaWiki
|category=Content Structuring
|bsvFrom=4.5
|features=This extension provides a configuration settings that shows the TOC numbers with each section heading
|desc=allows to edit text with ChatGPT.
BlueSpice can support users with an AI editing assistant. It allows to highlight text and have ChatPT make improvement suggestions based on pre-defined prompts. This feature requires a ChatGPT API-key to be activated.
}}
{{wcagCheck}}

Reference:NumberHeadings

2024-10-29T14:35:56Z

Hjing:

{{BSExtensionInfo
|status=stable
|developer=HalloWelt
|type=MediaWiki
|edition=BlueSpice pro, BlueSpice farm, BlueSpice cloud
|compatible=BlueSpice
|category=Content Structuring
|bsvFrom=4.5
|features=This extension provides a configuration settings that shows the TOC numbers with each section heading
|desc=allows to edit text with ChatGPT.
BlueSpice can support users with an AI editing assistant. It allows to highlight text and have ChatPT make improvement suggestions based on pre-defined prompts. This feature requires a ChatGPT API-key to be activated.
}}
{{wcagCheck}}

Reference:NumberHeadings

2024-10-29T14:33:09Z

Hjing:

{{BSExtensionInfo
|status=stable
|developer=HalloWelt
|type=MediaWiki
|edition=BlueSpice pro, BlueSpice farm, BlueSpice cloud
|compatible=BlueSpice
|category=Communication
|bsvFrom=4.5
|features=This extension provides a configuration settings that shows the TOC numbers with each section heading
|desc=allows to edit text with ChatGPT.
BlueSpice can support users with an AI editing assistant. It allows to highlight text and have ChatPT make improvement suggestions based on pre-defined prompts. This feature requires a ChatGPT API-key to be activated.
}}
{{wcagCheck}}

Reference:NumberHeadings

2024-10-29T14:32:50Z

Hjing:

{{BSExtensionInfo
|status=stable
|developer=HalloWelt
|type=BlueSpice
|edition=BlueSpice pro, BlueSpice farm, BlueSpice cloud
|compatible=MediaWiki
|category=Communication
|bsvFrom=4.5
|features=This extension provides a configuration settings that shows the TOC numbers with each section heading
|desc=allows to edit text with ChatGPT.
BlueSpice can support users with an AI editing assistant. It allows to highlight text and have ChatPT make improvement suggestions based on pre-defined prompts. This feature requires a ChatGPT API-key to be activated.
}}
{{wcagCheck}}

Manual:Extension/ContentDroplets

2024-09-06T10:19:17Z

Hjing: Fixing link to Progress subpage

{{DISPLAYTITLE:Content Droplets}}
{{BSVersion|bsvFrom=4.3.2|bsvFeature=ContentDroplets}}
{{TOClimit|limit=1}}
To insert additional functionality in a wiki page, you can use Content droplets. Content droplets include tags that were previously accessed from ''Insert > Magic word'' in the editor toolbar. They also provide access to some templates that are preconfigured in the wiki, such as message boxes.

== Adding a droplet to a page ==
To add a droplet to a page:

# '''Click''' the Content droplets icon in the editor toolbar or type <code><nowiki><<</nowiki></code>.
#'''Search''' for a droplet name in the search bar of the droplets menu or browse the droplets by category.[[File:droplet menu.png|none|thumb|550x550px]]
#'''Select''' a droplet
#'''Click''' ''Insert''.
{{Messagebox|boxtype=note|icon=|Note text=Some droplets open an inspector menu which contains another ''Insert'' button. Be sure to confirm that button as well.|bgcolor=}}
Based on the type of droplet, you can continue with configuring the droplet as needed.

==List of droplets==
{{Icon|bi bi-arrow-right-circle|||}} [[Manual:Extension/ContentDroplets/Examples|View examples of droplets outputs.]]

<containerfilter selector=".wikitable tr">

</containerfilter>
{| class="wikitable" style="width: 100%;"
! style="background-color:rgb(234, 236, 240);text-align:center;box-sizing:border-box;border:1px solid rgb(162, 169, 177);padding:8px;" class="" |'''Droplet'''
! style="background-color:rgb(234, 236, 240);text-align:center;box-sizing:border-box;border:1px solid rgb(162, 169, 177);padding:8px;" class="" |'''Description'''
!Inserts the following in the page source:
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |[[Attachments]] {{PopImg|file=attachments.png|alt=Screenshot of the attachments area|caption=Attachments output|width=600}}
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |Area for organising attachments
|<code><nowiki><attachments title="Attachments area"></nowiki></code>

<code>* <nowiki>[[Media:Financial_Sample.xlsx]]</nowiki></code>

<code><nowiki></attachments></nowiki></code>
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |Booklist
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |List of books based on a filter value. The value needs to be defined as a metadata value in the book settings
|<code><nowiki><bs:booklist filter="Author:WikiSysop" /></nowiki></code>
|-
|Book PDF link{{Bsvs|bsvFrom=4.4}}
|PDF-download link to a book
|<code><nowiki>{{BookPDFLink|book=Testbook|template=BlueSpice%20Book|label=Book PDF Link}}</nowiki></code>
|-
|Book table of contents{{PopImg|file=droplet-BookTOC.png|alt=First chapter of the book "Admin manual"|caption=Book table of contents|width=600}}{{Bsvs|bsvFrom=4.4}}
|Inserts the ToC of any book in a wiki page
|<code><nowiki><booknav book="Admin_manual" chapter="1" /></nowiki></code>
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |[[mediawikiwiki:Extension:Cognitive_Process_Designer#Usage|BPMN diagram]] {{PopImg|file=Manual:bpmn-UserFeedback.svg|alt=Screenshot of a BPMN diagram|caption=BPMN diagram|width=600}}
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |Editable BPMN diagram
|<code><nowiki><bpmn name="Test:Erm31642" /></nowiki></code>
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |[[Templates download/ButtonLink|Button]]{{PopImg|file=HW-ButtonLink.png|alt=Screenshot of three colored button links|caption=Links styled as buttons|width=400}}
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |Link that is styled as a button
|<code><nowiki>{{ButtonLink|target=Main Page|label=click me!|format=blue}}</nowiki></code>
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |[[mediawikiwiki:Extension:CategoryTree|Categorytree]]
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |Selected categories are shown in a tree structure
|<code><nowiki><categorytree>TestCat</categorytree></nowiki></code>
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |[[Manual:Extension/BlueSpiceChecklist#Creating a checkbox|Checkbox]]{{Bsvs|bsvTo=4.3}}
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |Checkbox that can be checked in view mode
|<code><nowiki><bs:checkbox checked="true" /></nowiki></code>
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |[[Manual:Extension/BlueSpiceChecklist|Checklist]]
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |List that allows to set a value in view mode
|<code><nowiki><bs:checklist type="list" checked="true" list="Template:Status" value="Select status" /></nowiki></code>
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |[[wikipedia:Help:Displaying_a_formula#Chemistry|Chemical formula]] {{PopImg|file=chem.png|alt=screenshot of the chemical formula|caption=Chemical formula|width=300}}
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |Display of chemical formulas
|<code><nowiki><chem>H2O</chem></nowiki></code>
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |Circled number
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |Number in a circle with customizable color
|<code><nowiki>{{CircledNumber|bgColor=black|fgColor=yellow|number=180}}</nowiki></code>
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |[[Reference:SyntaxHighlight|Code]]{{PopImg|file=syntaxhighlight.png|alt=Screenshot of a code area with css syntax|caption=Code area for a css example}}
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |Highlighted section for code examples
|<code><nowiki><syntaxhighlight lang="css"></nowiki></code>

<code>.hi {background:blue;}</code>

<code><nowiki></syntaxhighlight></nowiki></code>
|-
| style="width:190px;" |[[Manual:Extension/InputBox|Create page]]
| style="width:380px;" |Form field for predefined page creation
|<code><nowiki>{{CreateInput|alignment=left|buttonlabel=Create}}</nowiki></code>
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |[[SMW queries#Content droplet .22Data query.22 v4.3.2B|Data query]]
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |Enables queries on content in the wiki
|<code><nowiki><dataquery modified="+" format="ul" count="6" namespaces="Main" /></nowiki></code>
|-
|Date{{Bsvs|bsvFrom=4.4}}{{PopImg|file=ContentDroplets date.png|alt=Screenshot of a date|caption=Date display}}
|Inserts a date. This can be used in combination with the content droplet ''Task list''
|<code><datetime>2023-11-23</datetime></code>
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |[[Manual:Extension/ContentDroplets#Decision|Decision]]{{PopImg|file=droplet decision.png|alt=Example of a decision|caption=Decision output|width=600}}
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |Highlights a decision as a page property
|<code><nowiki>{{Decision|decision=Eat more veggies}}{{Decision|decision=Buy new car}}</nowiki></code>
|-
|Decision overview{{PopImg|file=ContentDroplets Decision report.png|alt=Decision report table|caption=Decision report output|width=600}}{{Bsvs|bsvTo=|bsvFrom=4.4}}
|Table with a list of decisions that were created by the ''Decision'' content droplet 
|<code><nowiki><decisionoverview namespaces=""></decisionoverview></nowiki></code>
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |[[Manual:Extension/DrawioEditor|Diagram]] {{PopImg|file=BlueSpice_system_architecture_high_level.drawio.png|alt=Example of a server structure diagram|caption=Drawio diagram|width=600}}
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |Editable draw.io diagram
|<code><nowiki><drawio filename="Mydiagram"></nowiki></code>
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |[[mediawikiwiki:Help:Images#Gallery_syntax|Gallery]]{{PopImg|file=droplet gallery.png|alt=Example of a gallery with three fish|caption=Gallery|width=}}
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" | Displays an image gallery
|<code><nowiki><gallery></nowiki></code>

<code>File:test1.png</code>

<code>File:test.pdf</code>

<code><nowiki></gallery></nowiki></code>
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |[[Manual:Extension/ContentDroplets/Icon|Icon]]{{PopImg|file=icon.png|alt=Example of a bootstrap icon|caption=Icons template}}
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |Inserts an icon
|<code><nowiki>{{Icon|bi bi-arrow-left-circle}}</nowiki></code>
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |[[Templates download/Messagebox|Important Message]]{{PopImg|file=message-important.png|alt=Screenshot of important message|caption=Message of type "important"}}
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |Adds colored panel for a important note
|<code><nowiki>{{Textbox|boxtype=important|header=OMG|text=Important|icon=yes}}</nowiki></code>
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |[[Manual:Extension/BlueSpiceSmartList|Links to this page]]
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |List of pages that link to this page
|<code><nowiki><whatlinkshere period="-" sort="time" showns="0" /></nowiki></code>
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |[[Reference:BlueSpiceWhoIsOnline|List of users logged in]]
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |Pop-up with a list of all users that are currently logged in
|<code><nowiki><bs:whoisonlinepopup /></nowiki></code>
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |[[Manual:Extension/Maps|Map]]{{PopImg|file=map.png|alt=Screenshot of the map output|caption=Map output with text marker}}
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |Locations can be marked on the map
|<code><nowiki>{{Map|Munich ~ Hello there!|Munich, Germany}}</nowiki></code>
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |[[mediawikiwiki:Help:VisualEditor/User_guide#Editing_mathematical_formulae|Mathematical formula]]{{PopImg|file=math.png|alt=Math formula|caption=Screenshot of a math formula}}
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |Display of mathematical formulas
|<code><nowiki><math>\tfrac{2}{4}</math></nowiki></code>
|-
| style="width:190px;" |Member list
|List of members of a wiki group
|<code><nowiki><bs:userlist groups="sysop" count="6" /></nowiki></code>
|-
| style="background-color:rgb(248, 249, 250);text-align:start;box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;color:rgb(32, 33, 34);font-family:Lato, "sans-serif";font-size:13.9995px;font-style:normal;font-variant-ligatures:normal;font-variant-caps:normal;font-weight:400;letter-spacing:normal;orphans:2;text-indent:0px;text-transform:none;white-space:normal;widows:2;word-spacing:0px;-webkit-text-stroke-width:0px;text-decoration-thickness:initial;text-decoration-style:initial;text-decoration-color:initial;" class="" |[[Templates download/Messagebox|Message]]{{PopImg|file=message.png|alt=Screenshot of a plain message|caption=A plain message}}
| style="background-color:rgb(248, 249, 250);text-align:start;box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;color:rgb(32, 33, 34);font-family:Lato, "sans-serif";font-size:13.9995px;font-style:normal;font-variant-ligatures:normal;font-variant-caps:normal;font-weight:400;letter-spacing:normal;orphans:2;text-indent:0px;text-transform:none;white-space:normal;widows:2;word-spacing:0px;-webkit-text-stroke-width:0px;text-decoration-thickness:initial;text-decoration-style:initial;text-decoration-color:initial;" class="" |Adds text panel
|<code><nowiki>{{Textbox|boxtype=neutral|header=|text=SDadad|icon=no}}</nowiki></code>
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |[[Manual:Extension/ContentDroplets#Modal button|Modal button]]
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |Configurable button which opens a customizable modal dialogue
|<code><nowiki>{{ModalDialog|title=I am a dialog|btnLabel=click me!|body=This is the text|footer=hello world}}</nowiki></code>
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |[[Manual:Extension/BlueSpiceSmartList#Toplist|Most visited pages]]
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |List of the most visited wiki pages
|<code><nowiki><bs:toplist count="3" period="-" /></nowiki></code>
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |[[Manual:Extension/BlueSpiceSmartList|New users]]
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" | List of new users in the wiki
|<code><nowiki><bs:newbies count="4" /></nowiki></code>
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |[[Templates download/Messagebox|Note Message]] {{PopImg|file=message-note.png|alt=Screenshot of a note message|caption=Message of type "Note"}}
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" | Adds colored panel for a note
|<code><nowiki>{{Textbox|boxtype=note|header=|text=sfsadfasfdsdaf|icon=yes}}</nowiki></code>
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |[[Manual:Extension/BlueSpiceCountThings|Number of characters]]
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |Shows the number of characters or words in a wiki page
|<code><nowiki><bs:countcharacters /></nowiki></code>
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |[[Manual:Extension/BlueSpiceCountThings|Number of files]]
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |Shows the number of all uploaded files
|<code><nowiki><bs:countfiles /></nowiki></code>
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |[[Manual:Extension/BlueSpiceCountThings|Number of pages]]
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |Shows the number of pages
|<code><nowiki><bs:countarticles /></nowiki></code>
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |[[Manual:Extension/BlueSpiceCountThings|Number of users]]
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" | Shows the number of all users
|<code><nowiki><bs:countusers /></nowiki></code>
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |[[Reference:BlueSpiceWhoIsOnline|Number of users logged in]]
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |Number of currently logged in users
|<code><nowiki><bs:whoisonlinecount /></nowiki></code>
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |[[Reference:BlueSpicePageAccess|Page access]]{{PopImg|file=pageaccess.png|alt=Screenshot of the page access notification banner|caption=Page access notification banner}}
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |Restricts access to the page to the specified groups
|<code><nowiki><bs:pageaccess groups="sysop" /></nowiki></code>
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |PDF link
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |Link that downloads another wiki page as PDF
|<code><nowiki>{{PDFLink|page=Main Page|template=BlueSpice|label=PDF Link}}</nowiki></code>
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |PDF page break
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |Forces a page break at the set position during PDF export
|<code><nowiki><bs:uepagebreak /></nowiki></code>
|-
|[[Manual:Extension/ContentDroplets#PDF preview|PDF preview]]
|Embed preview of a PDF file
|<code><nowiki><pdf height="800">File:Raspberry_pi.pdf</pdf></code></nowiki>
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |[[Manual:Extension/BlueSpiceUniversalExport#Exclude content from PDF export|PDF no export]]
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |Content within this section is excluded from the PDF export
|<code><nowiki><bs:uenoexport>Don't export this text</bs:uenoexport></nowiki></code>
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |[[Manual:Extension/ContentDroplets/Progress|Progress]]
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |Visualizes progress against given measurement variables
|<code><nowiki><bs:statistics:progress basecount="2" progressitem="OK" width="150" baseitem="Status:" /></nowiki></code>
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |[[Manual:Extension/ContentDroplets#Pros and cons|Pros and cons]]{{PopImg|file=pros and cons.png|alt=Screenshot of the pros and cons template|caption=Pros and cons}}
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |Table for comparing pros and cons
|<code><nowiki>{{ProConList|title-advantages=Advantages|title-disadvantages=Disadvantages|advantages=* It is cheap|disadvantages=* It is sold out}}</nowiki></code>
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |[[Manual:Extension/BlueSpiceSmartList|Recent changes]]
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |List of recently changed pages
|<code><nowiki><recentchanges count="6" period="-" sort="time" showns="0" /></nowiki></code>
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |[[Manual:Extension/BlueSpiceSignHere|Signature]]{{PopImg|file=signatures.png|alt=Screenshot of the signatures button with a signature already added|caption=Signatures button}}
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |A button to add signatures in view mode
|<code><nowiki><bs:signhere /></nowiki></code>
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |[[Manual:Extension/BlueSpiceTagSearch|Search field]] {{PopImg|file=Suchfeld standard.png|alt=Screenshot of a search field with suggested results|caption=Search field|width=}}
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |Adds a search field to the page content
|<code><nowiki><bs:tagsearch type="wikipage" namespace="QM" /></nowiki></code>
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |[[Reference:SubPageList|Subpages]]
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |List of the subpages of a wiki page
|<code><nowiki>{{Subpages|parentpage=Mypage}}</nowiki></code>
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |[[Templates download/Messagebox|Success Message]] {{PopImg|file=message-success.png|alt=Screenshot of a success message|caption=Message of type "success"}}
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |Adds colored panel for a success note
|<code><nowiki>{{Textbox|boxtype=success|header=Example|text=Message text|icon=yes}}</nowiki></code>
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |[[Manual:Extension/BlueSpiceTagCloud|Tag cloud]]
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |Tag cloud based on categories or search queries
|<code><nowiki><bs:tagcloud renderer="list" store="category" /></nowiki></code>
|-
|Task list{{PopImg|file=droplet-task-item.png|alt=Checkbox with label|caption=Task list output}}{{Bsvs|bsvFrom=4.4}}
|Adds a checklist item
|[]

[] Checkbox text
[] (2)
|-
|Task report {{PopImg|file=Content_Droplets_Task_report.png|alt=Filterable task report with 4 entries|caption=Task report}}{{Bsvs|bsvFrom=4.4}}
|Filterable list of existing tasks
|<code><nowiki><taskreport user="" namespaces="" status=""></taskreport></nowiki></code>
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |[[Templates download/Messagebox|Tip Message]]{{PopImg|file=message-tip.png|alt=Screenshot of a tip message|caption=Message of type "tip"}}
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |Adds colored panel for a tip
|<code><nowiki>{{Textbox|boxtype=tip|header=Tip|text=sfsadf|icon=yes}}</nowiki></code>
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |[[Manual:Extension/BlueSpiceAvatars#Using the .3Cprofileimage.3E tag|User profile]] {{PopImg|file=userprofile.png|alt=Screenshot of the user profile|caption=User profile of type "Short"|width=300}}
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |A user profile will be included on this page
|<code><nowiki><bs:socialentityprofile username="WikiSysop" rendertype="Short" /></nowiki></code>
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |[[Manual:Extension/EmbedVideo|Video]]
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |Embeds video from different external platforms (YouTube)
|<code><nowiki><embedvideo service="youtube">JILEkPu61Ao</embedvideo></nowiki></code>
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |[[Manual:Extension/BlueSpicePagesVisited|Visited pages]]
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |List with visited pages
|<code><nowiki><bs:pagesvisited count="7" maxtitlelength="40" order="time" /></nowiki></code>
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |[[Templates download/Messagebox|Warning Message]]{{PopImg|file=message-warning.png|alt=Screenshot of a warning message|caption=Message of type "warning"}}
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |Adds a colored box for a warning note
|<code><nowiki>{{Textbox|boxtype=warning|header=Hello|text=|icon=yes}}</nowiki></code>
|-
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |[[Manual:Extension/ContentDroplets#Watchlist|Watchlist]]
| style="box-sizing:border-box;border:1px solid rgb(162, 169, 177);break-inside:avoid;padding:8px;" |Latest changes to pages included in your watch list
|<code><nowiki><bs:watchlist count="5" maxtitlelength="20" order="time" /></nowiki></code>
|} 

==More info==
{{#subpages:Manual:Extension/ContentDroplets}}
{{translation}}

User:Hjing

2024-09-06T07:58:54Z

Hjing: create user page