BlueSpice - User contributions [en]

Development

2026-02-24T09:34:32Z

Fspinar:

This page contains information about how to set up a local development environment for BlueSpice.

== Local development environment based on <code>bluespice-deploy</code> ==
A developer can use the [[Setup:Installation Guide/Docker|default deployment stack]] and alter is to quickly set up a development environment. To do so, first clone the stack to your local machine and navigate into it:
<syntaxhighlight lang="text">
git clone -b 5.2.x git@github.com:hallowelt/bluespice-deploy.git
cd bluespice-deploy/compose
</syntaxhighlight>

Create a proper <code>.env</code> file from the <code>.env.sample</code> and alter/add the following lines:
<syntaxhighlight lang="text">
DATADIR=~/workspace/REL1_43-5.2.x/data
CODEDIR=~/workspace/REL1_43-5.2.x/code
SMTP_HOST=mailhog
SMTP_PORT=1025
</syntaxhighlight>

Create a <code>docker-compose.overrides.yml</code> file with the following content:
<syntaxhighlight lang="yaml">
services:

wiki-installer:
image: docker.bluespice.com/bluespice-qa/wiki:latest
volumes:
- ${CODEDIR}:/app/bluespice/w/

wiki-web:
image: docker.bluespice.com/bluespice-qa/wiki:latest
volumes:
- ${CODEDIR}:/app/bluespice/w/

wiki-task:
image: docker.bluespice.com/bluespice-qa/wiki:latest
volumes:
- ${CODEDIR}:/app/bluespice/w/

mailhog:
image: mailhog/mailhog
container_name: mailhog
environment:
VIRTUAL_HOST: ${WIKI_HOST}
VIRTUAL_PATH: /_mailhog
VIRTUAL_PORT: 8025
VIRTUAL_DEST: /
</syntaxhighlight>

This will make the stack use your local codebase from <code>$CODEDIR</code> and also expose a Mailhog web interface on <code>$Wiki_HOST/_mailhog</code>.

In addition, if you want to work with a custom build of the <code>bluespice/wiki</code> container, you can add an <code>image:</code> entry to the respective services. Example
<syntaxhighlight lang="yaml">
wiki-installer:
image: bluespice/wiki:dev
...
wiki-web:
image: bluespice/wiki:dev
...

wiki-task:
image: bluespice/wiki:dev
...
</syntaxhighlight>or you set<blockquote>BLUESPICE_WIKI_IMAGE=bluespice/wiki:dev</blockquote>in your <code>.env</code>-File

Development

2026-02-24T09:33:59Z

Fspinar:

Security:Security Advisories/BSSA-2026-01

2026-01-29T08:33:27Z

Fspinar:

{| class="wikitable"
|+
!
!
|-
|Date
|2026-01-29
|-
|Severity
|reported "high", BlueSpice assessment: '''low'''
|-
|Affected
| Services in current LTS version < 5.1.4
|-
|Fixed in
|
|-
|CVE
|
* [https://avd.aquasec.com/nvd/2025/cve-2025-14847 CVE-2025-14847]
* [https://avd.aquasec.com/nvd/2025/cve-2025-15467/ CVE-2025-15467]
|}

==Problem==
{| class="wikitable"
!'''CVE'''
!'''Component'''
!'''Type of vulnerability'''
!'''BlueSpice 5'''
!'''BlueSpice 4'''
|-
|CVE-2025-14847
|<code>container collabpads-database(image:mongo:8.0)</code>
|Information Disclosure
| style="" class="col-purple-bg" |affected
| style="" class="col-purple-bg" |affected
|-
|CVE-2025-15467
|Container <code>bluespice/database</code>
|Buffer Overflow
| style="" class="col-purple-bg" |affected
| style="" class="col-purple-bg" |affected
|}

==Impact assessment==
* Service <code>collabpads-database</code> (image name: <code>mongo</code> )
** A unauthenticated MongoDB client can attack the service if reachable. By default BlueSpice setup, the service runs only in the background and can not be accessed from outside the virtual network. So not even unauthenticated access is possible from any external location.
{| class="wikitable" style="width: 100%;"
!CVE
!Assessment
!Mitigation without update
|-
| style="vertical-align:middle;text-align:left;" |CVE-2025-14847
| style="vertical-align:middle;text-align:left;" class="col-orange-bg" |Low
| style="vertical-align:middle;text-align:left;" |Make sure the service has no access to the internet. This is the default configuration of BlueSpice setups
|-
|CVE-2025-15467
| style="" class="col-orange-bg" |Low
|Make sure the service has no access to the internet. This is the default configuration of BlueSpice setups
|}

== Solution ==
To mitigate <code>CVE-2025-14847</code> use one of the following options:

# Make sure the service has no access to the internet. This is the default configuration of BlueSpice setups.
# Update the <code>mongo</code> docker image via BlueSpice's deploy tool: <code>bluespice-deploy pull collabpads-database && bluespice-deploy up -d</code>

Security:Security Advisories/BSSA-2026-01

2026-01-29T07:52:54Z

Fspinar:

Security:Security Advisories/BSSA-2025-07

2025-12-09T16:19:04Z

Fspinar:

{| class="wikitable"
|+
!
!
|-
|Date
|2025-12-09
|-
|Severity
|reported "critical", BlueSpice assessment: '''low'''
|-
|Affected
| Services in current LTS version < 5.1.4
|-
|Fixed in
|5.1.4
|-
|CVE
| [https://avd.aquasec.com/nvd/2025/cve-2025-66516 CVE-2025-66516]
|}

==Problem==

* Service <code>bluespice/search</code>- [https://nvd.nist.gov/vuln/detail/CVE-2025-66516 CVE-2025-66516]

==Impact assessment==

* Service <code>bluespice/search</code>
** The issues has already been fixed in the upstream repository, but there was no official release yet
** A manipulated PDF file needs to be uploaded to the wiki, which usually requires an authenticated user context. The service runs only in the background and can not be accessed from outside the virtual network. It has limited access to the host system.

== Solution ==
To mitigate <code>CVE-2025-66516</code> one can make sure the service has no access to the internet.
Update a soon as possible to Version 5.1.4 of the BlueSpice images

Security:Security Advisories/BSSA-2025-07

2025-12-09T16:17:16Z

Fspinar:

{| class="wikitable"
|+
!
!
|-
|Date
|2025-12-09
|-
|Severity
|reported "critical", BlueSpice assessment: '''low'''
|-
|Affected
| Services in current LTS version < 5.1.4
|-
|Fixed in
|fix not yet available
|-
|CVE
| [https://avd.aquasec.com/nvd/2025/cve-2025-66516 CVE-2025-66516]
|}

==Problem==

* Service <code>bluespice/search</code>- [https://nvd.nist.gov/vuln/detail/CVE-2025-66516 CVE-2025-66516]

==Impact assessment==

* Service <code>bluespice/search</code>
** The issues has already been fixed in the upstream repository, but there was no official release yet
** A manipulated PDF file needs to be uploaded to the wiki, which usually requires an authenticated user context. The service runs only in the background and can not be accessed from outside the virtual network. It has limited access to the host system.

== Solution ==
To mitigate <code>CVE-2025-66516</code> one can make sure the service has no access to the internet.
Update a soon as possible to Version 5.1.4 of the BlueSpice images

Security:Security Advisories/BSSA-2025-07

2025-12-09T16:16:54Z

Fspinar:

Security:Security Advisories/BSSA-2025-07

2025-12-09T16:13:46Z

Fspinar:

{| class="wikitable"
|+
!
!
|-
|Date
|2025-09-18
|-
|Severity
|reported "critical", BlueSpice assessment: '''low'''
|-
|Affected
| Services in current LTS version < 5.1.4
|-
|Fixed in
|fix not yet available
|-
|CVE
| [https://avd.aquasec.com/nvd/2025/cve-2025-66516 CVE-2025-66516]
|}

==Problem==

* Service <code>bluespice/search</code>- [https://nvd.nist.gov/vuln/detail/CVE-2025-54988 CVE-2025-54988]
* Service <code>bluespice/formula</code> - [https://avd.aquasec.com/nvd/2025/cve-2025-7783/ CVE-2025-7783/]
* Service <code>bluespice/wiki</code>
** PCRE: [https://avd.aquasec.com/nvd/cve-2025-58050 CVE-2025-58050]
** libxml: [https://avd.aquasec.com/nvd/cve-2025-49794 CVE-2025-49794] and [https://avd.aquasec.com/nvd/cve-2025-49796 CVE-2025-49796]

==Impact assessment==

* Service <code>bluespice/search</code>
** The issues has already been fixed in the upstream repository, but there was no official release yet
** A manipulated PDF file needs to be uploaded to the wiki, which usually requires an authenticated user context. The service runs only in the background and can not be accessed from outside the virtual network. It has limited access to the host system.
* Service <code>bluespice/formula</code>
** Caused by a dependency of [https://www.npmjs.com/package/coveralls coveralls]
** Not used production code
* Service <code>bluespice/wiki</code>
** No direct usage of those libraries
** Only accessed via PHP
** Main impacts are potential information disclose and denial-of-service
*** No critical information can be disclosed

== Solution ==
To mitigate <code>CVE-2025-54988</code> one can make sure the service has no access to the internet.

Besides this, there is currently no solution to those issues. Once the upstream vendors release fixed packages, the next patchlevel release of BlueSpice will contain them.

Security:Security Advisories/BSSA-2025-07

2025-12-09T16:10:39Z

Fspinar: Created page with "{| class="wikitable" |+ ! ! |- |Date |2025-09-18 |- |Severity |reported "critical", BlueSpice assessment: '''low''' |- |Affected | Services in current LTS version 5.1 |- |Fixed in |fix not yet available |- |CVE | [https://nvd.nist.gov/vuln/detail/CVE-2025-54988 CVE-2025-54988], [https://avd.aquasec.com/nvd/2025/cve-2025-7783 CVE-2025-7783], [https://avd.aquasec.com/nvd/cve-2025-58050 CVE-2025-58050], [https://avd.aquasec.com/nvd/cve-2025-49794 CVE-2025-49794], [https://a..."

{| class="wikitable"
|+
!
!
|-
|Date
|2025-09-18
|-
|Severity
|reported "critical", BlueSpice assessment: '''low'''
|-
|Affected
| Services in current LTS version 5.1
|-
|Fixed in
|fix not yet available
|-
|CVE
| [https://nvd.nist.gov/vuln/detail/CVE-2025-54988 CVE-2025-54988], [https://avd.aquasec.com/nvd/2025/cve-2025-7783 CVE-2025-7783], [https://avd.aquasec.com/nvd/cve-2025-58050 CVE-2025-58050], [https://avd.aquasec.com/nvd/cve-2025-49794 CVE-2025-49794], [https://avd.aquasec.com/nvd/cve-2025-49796 CVE-2025-49796]
|}

==Problem==

* Service <code>bluespice/search</code>- [https://nvd.nist.gov/vuln/detail/CVE-2025-54988 CVE-2025-54988]
* Service <code>bluespice/formula</code> - [https://avd.aquasec.com/nvd/2025/cve-2025-7783/ CVE-2025-7783/]
* Service <code>bluespice/wiki</code>
** PCRE: [https://avd.aquasec.com/nvd/cve-2025-58050 CVE-2025-58050]
** libxml: [https://avd.aquasec.com/nvd/cve-2025-49794 CVE-2025-49794] and [https://avd.aquasec.com/nvd/cve-2025-49796 CVE-2025-49796]

==Impact assessment==

* Service <code>bluespice/search</code>
** The issues has already been fixed in the upstream repository, but there was no official release yet
** A manipulated PDF file needs to be uploaded to the wiki, which usually requires an authenticated user context. The service runs only in the background and can not be accessed from outside the virtual network. It has limited access to the host system.
* Service <code>bluespice/formula</code>
** Caused by a dependency of [https://www.npmjs.com/package/coveralls coveralls]
** Not used production code
* Service <code>bluespice/wiki</code>
** No direct usage of those libraries
** Only accessed via PHP
** Main impacts are potential information disclose and denial-of-service
*** No critical information can be disclosed

== Solution ==
To mitigate <code>CVE-2025-54988</code> one can make sure the service has no access to the internet.

Besides this, there is currently no solution to those issues. Once the upstream vendors release fixed packages, the next patchlevel release of BlueSpice will contain them.

Setup:Installation Guide/Docker

2025-11-17T09:25:25Z

Fspinar: /* Additional options */

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

=== Add Customizations to containers ===
Starting with bluespice-deploy 5.1.4 and 5.2.0 Branches, we allow to edit and maintan 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 docker-compose.*.ymls and run ./bluespice-deploy up -d

Example:<syntaxhighlight lang="yaml">
services:
wiki-web:
volumes:
- /code/extensions/X:/app/bluespice/w/extensions/X
- /backup/:/data/backup
wiki-task:
volumes:
- /backup/:/data/backup
- /code/extensions/X:/app/bluespice/w/extensions/X
</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/Docker

2025-07-16T08:51:43Z

Fspinar: /* 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

Example:
wget https://github.com/hallowelt/bluespice-deploy/archive/refs/heads/main.zip \
&& unzip main.zip \
&& cd bluespice-deploy-main/compose

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

The directory contains the following files:
{| class="wikitable"
|+
! style="width:350px;" |Filename
! style="" |Type
! style="" |Mandatory
! style="" |Comment
|-
| style="width:350px;" |<code>bluespice-deploy</code>
| style="" |bash-script
| style="" |false
| style="" |Wrapper for general start-up of needed containers
|-
| style="width:350px;" |<code>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]]

File:Draft:Setup Draft Setup Azure-OIDC-Connection configManager.png

2025-06-05T14:40:44Z

Fspinar:

File:Draft:Setup Draft Setup Azure-OIDC-Connection setup.png

2025-06-05T14:28:07Z

Fspinar:

File:Draft:Setup Draft Setup Azure-OIDC-Connection manifest.png

2025-06-05T14:24:52Z

Fspinar:

File:Draft:Setup Draft Setup Azure-OIDC-Connection secret3.png

2025-06-05T14:21:57Z

Fspinar:

File:Draft:Setup Draft Setup Azure-OIDC-Connection secret2.png

2025-06-05T14:18:31Z

Fspinar:

File:Draft:Setup Draft Setup Azure-OIDC-Connection secret1.png

2025-06-05T12:28:10Z

Fspinar:

File:Draft:Setup Draft Setup Azure-OIDC-Connection uri4.png

2025-06-05T12:24:35Z

Fspinar:

File:Draft:Setup Draft Setup Azure-OIDC-Connection uri3.png

2025-06-05T12:20:26Z

Fspinar:

File:Draft:Setup Draft Setup Azure-OIDC-Connection uri2.png

2025-06-05T12:17:54Z

Fspinar:

File:Draft:Setup Draft Setup Azure-OIDC-Connection uri1.png

2025-06-05T12:16:10Z

Fspinar:

File:Draft:Setup Draft Setup Azure-OIDC-Connection setup4.png

2025-06-05T12:14:23Z

Fspinar:

File:Draft:Setup Draft Setup Azure-OIDC-Connection name claim.png

2025-06-05T12:12:34Z

Fspinar:

File:Draft:Setup Draft Setup Azure-OIDC-Connection setup2.png

2025-06-05T12:05:28Z

Fspinar:

File:Draft:Setup Draft Setup Azure-OIDC-Connection setup1.png

2025-06-05T12:03:44Z

Fspinar:

File:Draft:Setup Draft Setup Azure-OIDC-Connection create2.png

2025-06-05T12:00:34Z

Fspinar:

File:Draft:Setup Draft Setup Azure-OIDC-Connection create.png

2025-06-05T11:54:58Z

Fspinar:

File:Draft:Setup Draft Setup Azure-SAML-Connection Attribute.png

2025-06-05T11:37:11Z

Fspinar: (username removed) (log details removed)

File:Draft:Setup Draft Setup Azure-SAML-Connection group4.png

2025-06-05T11:28:08Z

Fspinar:

File:Draft:Setup Draft Setup Azure-SAML-Connection group 3.png

2025-06-05T11:24:12Z

Fspinar:

File:Draft:Setup Draft Setup Azure-SAML-Connection GroupClaim 2.png

2025-06-05T10:15:03Z

Fspinar:

File:Draft:Setup Draft Setup Azure-SAML-Connection GroupClaim.png

2025-06-05T10:13:14Z

Fspinar:

File:Draft:Setup Draft Setup Azure-SAML-Connection Attribute.png

2025-06-05T10:11:06Z

Fspinar:

File:Draft:Setup Draft Setup PluggableAuth-Login-Page.png

2025-06-05T07:24:04Z

Fspinar:

File:Draft:Setup Draft Setup Azure-SAML-Connection metadata.png

2025-06-05T07:13:00Z

Fspinar: (username removed) (log details removed)

File:Draft:Setup Draft Setup Azure-SAML-Connection 1749107448504.png

2025-06-05T07:10:52Z

Fspinar:

File:Draft:Setup Draft Setup Azure-SAML-Connection metadata2.png

2025-06-05T07:08:43Z

Fspinar:

File:SetUpEnterpriseApplication.png

2025-06-05T07:04:44Z

Fspinar:

Setup:Installation Guide/Docker/Pro and Farm edition

2025-06-03T12:33:45Z

Fspinar:

Almost all container images used by the stack are freely available via hub.docker.com. The only exception is <code>bluespice/wiki</code> with the PRO / FARM codebase. There are two options to obtain this image:

# Manual download from [https://bluespice.com/download/ bluespice.com] and local import
# Load from private <code>docker.bluespice.com</code> image registry

== Manual download and import ==
Before running <code>bluespice-deploy</code> you will need to download the <code>docker.bluespice.com/bluespice/wiki</code> image from https://bluespice.com/download/ and store the file to the server (e.g. in <code>/tmp/docker.bluespice.com-bluespice-wiki_5.1.tar.gz</code> ).

Then you can use the standard <code>docker load</code> command to make it available to the docker runtime.

Example:
docker load < /tmp/docker.bluespice.com-bluespice-wiki_5.1.tar.gz
# Loaded image: docker.bluespice.com/bluespice/wiki:5.1
bluespice-deyploy up -d
# Image found locally.

== Load from <code>docker.bluespice.com</code> ==

If you have credentials to <code>docker.bluespice.com</code> you can just run `bluespice-deyploy up -d`. It will prompt you for username and password in case you haven't configured it already.

Example:

bluespice-deyploy up -d
# In order to access our PRO-Image please login to docker.bluespice.com
username: myuser
password: