BlueSpice Helpdesk - User contributions [en]

Setup:System requirements

2025-05-15T07:28:55Z

Rvogel1: Align with DE

__NOTOC__

For a trouble-free installation of the current version of BlueSpice 5, we recommend the following system requirements.

==Browser==

*Microsoft Edge
*Google Chrome
*Firefox

==Server Environment==
{{Textbox|boxtype=note|header=Container images only|text=With BlueSpice 5, the main release of the software is via container images. Manual installation on is no longer supported. Please refer to out [[Setup:Installation_Guide/Docker|installation guide]] for more information.

Native installation on Windows Server is no longer supported.

If you need a different type of installation, please [https://bluespice.com/contact/ contact us].|icon=yes}}

=== Basic Hardware Requirements ===
*'''CPU:''' '''8 Cores'''
* '''Main memory: 8''' '''GB''' (16 GB recommended)
* '''Available additional hard drive space:''' > 20 GB (depends on the planned storage of data)

=== External Databases ===
Even though the [https://github.com/hallowelt/bluespice-deploy standard container stack] already has database services included, one can also configure external databases if required.

* Main application database: MySQL: >= 5.6 or MariaDB >= 10.3
* For [[Reference:CollabPads|"edit together"]] feature: MongoDB >= 4.4 ( >=8.0 recommended)

=== External Search Service ===

* OpenSearch 2.x with <code>ingest-attachments</code> plugin
{{Textbox
|boxtype=important
|header=No support for <code>ARM</code>
|text=Currently, installation is only supported on <code>x86</code>/<code>x64</code> architecture. This is especially true when using [[Setup:Installation_Guide/Docker|Docker]].
|icon=yes
}}

[[de:Setup:Systemanforderungen]]
[[Category:Setup]]

Setup:System requirements

2025-05-13T14:57:30Z

Rvogel1: Remove abandoned CentOS (see https://endoflife.software/operating-systems/linux/centos)

__NOTOC__

For a trouble-free installation of the current version of BlueSpice 4, we recommend the following system requirements.

==Browser==

*Microsoft Edge
*Google Chrome
*Firefox

==Server Environment==
*'''Operating system:'''
** We strongly recommend Linux (preferably Debian 11, Ubuntu 22.04)
** You might use Windows Server starting at 2016, but we have seen performance issues on Windows Server
*'''Webserver:'''
**Apache 2.4.x, IIS >= 10 ''or'' nginx 1.x (''nginx'' ''not possible in WikiFarm'')
*'''PHP:'''
** PHP 8.1 / PHP 8.2
* '''Database''':
** MySQL: >= 5.6 or MariaDB >= 10.3
** MongoDB >= 4.4 (for extension [[Reference:CollabPads|CollabPads]])
* '''(Virtual) hardware requirements:'''
**'''CPU:'''
*** '''Linux: 8 Cores''' (min. 4 Cores)
*** Windows: 16 Cores (min. 8 Cores)
** '''Main memory:'''
***'''Linux: 16 GB''' (min. 8GB)
*** Windows: min. 16 GB
** '''Available hard drive space:'''
*** > 20 GB (depends on the planned storage of data)
*'''Other:'''
**Apache Tomcat >= 9 oder Jetty >= 9 (for PDF export and LaTexRenderer)
**OpenSearch 2 with plugin “ingest-attachment”
**OpenJDK >= 10
**NodeJS 16

{{Textbox
|boxtype=important
|header=No support for <code>ARM</code>
|text=Currently, installation is only supported on <code>x86</code>/<code>x64</code> architecture. This is especially true when using [[Setup:Installation_Guide/Docker|Docker]].
|icon=yes
}}

[[de:Setup:Systemanforderungen]]
[[Category:Setup]]

Setup:Installation Guide/Docker

2025-02-03T15:15:37Z

Rvogel1: Undo revision 10318 by Rvogel1 (talk)

{{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>${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]]

Setup:Installation Guide/Docker

2025-02-03T15:12:33Z

Rvogel1:

{{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/4.5.x.zip \
&& unzip 4.5.x.zip \
&& cd bluespice-deploy-4.5.x/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>${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]]

Manual:Create pages

2025-02-03T10:14:30Z

Rvogel1: Fix language link

<bookshelf src="Book:User manual" />
An important aspect of the wiki principle is that content can be created, edited and shared quickly with others. Changes to wiki pages can be tracked and reversed at any time via the version history. Therefore, a wiki should limit editing rights sparingly to allow for the greatest possible collaboration.

==Creating a page==
'''To create a page:'''

#'''Click''' the New button in the [[Manual:Extension/BlueSpiceDiscovery|Header]]. A dialog window opens.
#'''Enter <nowiki/>'''a page name. If th'''''<nowiki/>'''''e page does not exist yet, you will see a red link. f you want to create the page in an existing namespace, add the namespace name as a prefix, followed by a colon. Example: <code>Manual:Visual editing</code> I[[File:Manual:Create page dialog.png|alt=Create a new page|center|thumb|350x350px|Create a new page]]
#'''Click''' done.
#'''Choose''' ''Blank Page'' or a page template if your wiki shows the page templates page as the next step. This step is omitted if no page templates are available. The page now opens in edit mode.
#'''Save''' the page. After saving the page for the first time, the page exists in the wiki. Click the edit icon of the page to switch back to edit mode.

==Changing the page name==
If you want to change the page name later (e.g., to store it in another [[Manual:The concept of namespaces|namespace]]), you need to [[Manual:Rename and move pages|move]] the page.

==Adding subpages==
To create a [[Manual:Subpage|subpage]] for the current page, select the ''New subpage'' link from the ''New'' menu.
[[File:Manual:Create a subpage.png|alt=Create a subpage|center|thumb|150x150px|Create a subpage]]

The subpage is then created as page <code>current page/subpage</code>, e.g. ''VisualEditor/Tables''. If a page has subpages, the path is displayed via the breadcrumb navigation at the top of the page. The character <code>/</code> is only used to create a subpage. This means that you cannot create a wiki page called ''When/how to take a vacation'' as this will result in a main page ''When'' with its subpage ''how to take a vacation''.

==Page name conventions==

*'''Title choice:''' In a wiki, titles are very important. In wikis with many entries, it happens that authors set links to pages that they consider important in the context of their entry. Single words work well, but short phrases like "why wikis work" can also be goood page names. In addition, meaningful page titles also make it easier for readers to find their way around and to search for an article using the title search.

*'''Namespaces:''' To create an article in another namespace, its name must be preceded by the namespace prefix, i.e. <code>namespace:articlename</code>. An article name can exist multiple times in the wiki as long as it is in different namespaces.
*'''Special characters:''' The following characters cannot be used in titles: <code>{ } & ? < > \</code> and <code>,</code> . You can find more about this at [https://www.mediawiki.org/wiki/Manual:Page_title?action=view Mediawiki].
*'''Spelling:''' When linking to an already existing page in source edit mode, you should pay attention to the exact spelling. For example, if you enter <code><nowiki>[[Hello world]]</nowiki></code> instead of <code><nowiki>[[Hello World]]</nowiki></code>, links to two different pages are created, because the page names are case sensitive. Only the first letter of a (parent) page is case-insensitive. Subpage names are completely case-sensitive.

==Alternate options==
There are other handy ways to create a page in the wiki:

*'''Search:''' Maybe a page about your topic already exists. Before you create a new page, you can use the search function to enter terms related to your topic and check existing pages. If there is no suitable page yet, click on the red link "Page ''[page name]'' create " in the search results of the quick menu. There is also a <code>+</code> button for creating a new page in the Search Center.
*'''Redlink:''' If you are currently editing a wiki page, you can directly select a text passage and set a link to a non-existent page. <span class="ve-paste
*'''Browser address bar:''' You can also create a page directly from the address bar of your web browser. To do this, simply replace the title of the current page with a new page name. If you then press Enter, the new page will open.
*'''[[Manual:Extension/InputBox|Inputbox]]''': Input field that can easily be added to any page that includes predefined parameters to ensure the page is created in a particular namespace or using a particular page template.
*'''[[Reference:Page Forms|Form]]:''' In BlueSpice pro, there is also the possibility to create pages using forms. This has the advantage that you can pass different page parameters, such as a page template or various template parameter values to a new page during page creation.

{{Box_Links-en | Topic1 =[[Manual:Rename_and_move_pages|Rename and move pages]]| Topic2 =[[Manual:Redirects|Redirects - using synonyms]] | Topic3 =[[Manual:Extension/BlueSpicePageTemplates|Page templates]] | Topic4 = }}
[[en:{{FULLPAGENAME}}]]
[[de:Handbuch:Seiten_erstellen]]

[[Category:Editing]]

2025-01-07T07:40:13Z

Rvogel1:

__NOTOC__

For a trouble-free installation of the current version of BlueSpice 4, we recommend the following system requirements.

==Browser==

*Microsoft Edge
*Google Chrome
*Firefox

==Server Environment==
*'''Operating system:'''
** We strongly recommend Linux (preferably Debian 11, Ubuntu 22.04, CentOS 7)
** You might use Windows Server starting at 2016, but we have seen performance issues on Windows Server
*'''Webserver:'''
**Apache 2.4.x, IIS >= 10 ''or'' nginx 1.x (''nginx'' ''not possible in WikiFarm'')
*'''PHP:'''
** PHP 8.1 / PHP 8.2
* '''Database''':
** MySQL: >= 5.6 or MariaDB >= 10.3
** MongoDB >= 4.4 (for extension [[Reference:CollabPads|CollabPads]])
* '''(Virtual) hardware requirements:'''
**'''CPU:'''
*** '''Linux: 8 Cores''' (min. 4 Cores)
*** Windows: 16 Cores (min. 8 Cores)
** '''Main memory:'''
***'''Linux: 16 GB''' (min. 8GB)
*** Windows: min. 16 GB
** '''Available hard drive space:'''
*** > 20 GB (depends on the planned storage of data)
*'''Other:'''
**Apache Tomcat >= 9 oder Jetty >= 9 (for PDF export and LaTexRenderer)
**OpenSearch 2 with plugin “ingest-attachment”
**OpenJDK >= 10
**NodeJS 16

{{Textbox
|boxtype=important
|header=No support for <code>ARM</code>
|text=Currently, installation is only supported on <code>x86</code>/<code>x64</code> architecture. This is especially true when using [[Setup:Installation_Guide/DockerDocker]].
|icon=yes
}}

[[de:Setup:Systemanforderungen]]
[[Category:Setup]]

File:Setup:Installation Guide Docker-Achitecture.png

2024-12-10T12:50:59Z

Rvogel1: (username removed) (log details removed)

File:Setup:Installation Guide Docker-Achitecture.png

2024-12-10T12:49:27Z

Rvogel1: (username removed) (log details removed)

Setup:Installation Guide/Docker

2024-12-10T12:47:32Z

Rvogel1: /* Architecture */

{{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 docker-deployment-script/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]]

File:Setup:Installation Guide Docker-Achitecture.png

2024-12-10T12:36:38Z

Rvogel1: (username removed) (log details removed)

File:Setup:Installation Guide Docker-Achitecture.png

2024-12-10T12:35:13Z

Rvogel1: (username removed) (log details removed)

File:Setup:Installation Guide Docker-Achitecture.png

2024-12-10T12:34:28Z

Rvogel1: (username removed) (log details removed)

File:Setup:Installation Guide Docker-Achitecture.png

2024-12-10T11:45:32Z

Rvogel1: (username removed) (log details removed)

File:Setup:Installation Guide Docker-Achitecture.png

2024-12-10T10:59:56Z

Rvogel1: (username removed) (log details removed)

File:Setup:Installation Guide Docker-Achitecture.png

2024-12-10T10:59:49Z

Rvogel1: (username removed) (log details removed)

File:Setup:Installation Guide Docker-Achitecture.png

2024-12-10T10:58:15Z

Rvogel1: (username removed) (log details removed)

File:Setup:Installation Guide Docker-Achitecture.png

2024-12-10T10:51:34Z

Rvogel1: (username removed) (log details removed)

2024-10-25T06:21:14Z

Rvogel1:

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

=== 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 docker-deployment-script/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 wrapsthe 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=...

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

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

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

to <code><nowiki>https://bluespice-wiki.com</nowiki></code>

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

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

Please restart containers after changing/adding SSL 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:
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 "Extension:Auth_remoteuser".

====SAML authentication====

[[File:Setup:SAML ConfigManager EN 01.png|thumb|300x300px]]

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

Next, the extensions "PluggableAuth" and "SimpleSAMLphp" must be enabled on the wiki. To do so, add

<syntaxhighlight lang="php">
wfLoadExtensions( [
'PluggableAuth',
'SimpleSAMLphp'
] );
</syntaxhighlight>
to the <code>${DATADIR}/wiki/bluespice/post-init-settings.php</code>

After that, the authentication plugin configuration can be applied in [[ConfigManager|Special:BlueSpiceConfigManager]] under "Authentication".

File:Setup:SAML ConfigManager EN 01.png

2024-10-25T06:15:42Z

Rvogel1:

Setup:System requirements

2024-10-11T07:54:28Z

Rvogel1:

__NOTOC__

For a trouble-free installation of the current version of BlueSpice 4, we recommend the following system requirements.

==Browser==

*Microsoft Edge
*Google Chrome
*Firefox

==Server Environment==
*'''Operating system:'''
** We strongly recommend Linux (preferably Debian 11, Ubuntu 22.04, CentOS 7)
** You might use Windows Server starting at 2016, but we have seen performance issues on Windows Server
*'''Webserver:'''
**Apache 2.4.x, IIS >= 10 ''or'' nginx 1.x (''nginx'' ''not possible in WikiFarm'')
*'''PHP:'''
** PHP 8.1 / PHP 8.2
* '''Database''':
** MySQL: >= 5.6 or MariaDB >= 10.3
** MongoDB >= 4.4 (for extension [[Reference:CollabPads|CollabPads]])
* '''(Virtual) hardware requirements:'''
**'''CPU:'''
*** '''Linux: 8 Cores''' (min. 4 Cores)
*** Windows: 16 Cores (min. 8 Cores)
** '''Main memory:'''
***'''Linux: 16 GB''' (min. 8GB)
*** Windows: min. 16 GB
** '''Available hard drive space:'''
*** > 20 GB (depends on the planned storage of data)
*'''Other:'''
**Apache Tomcat >= 9 oder Jetty >= 9 (for PDF export and LaTexRenderer)
**OpenSearch 2 with plugin “ingest-attachment”
**OpenJDK >= 10
**NodeJS 16

[[de:Setup:Systemanforderungen]]
[[Category:Setup]]

Setup:System requirements

2024-10-11T07:51:13Z

Rvogel1:

__NOTOC__

For a trouble-free installation of the current version of BlueSpice 4, we recommend the following system requirements.

==Browser==

*Microsoft Edge
*Google Chrome
*Firefox

==Server Environment==
*'''Operating system:'''
** We strongly recommend Linux (preferably Debian 11, Ubuntu 22.04, CentOS 7)
** You might use Windows Server starting at 2016, but we have seen performance issues on Windows Server
*'''Webserver:'''
**Apache 2.4.x, IIS >= 10 ''or'' nginx 1.x (''nginx'' ''not possible in WikiFarm'')
*'''PHP:'''
** PHP 8.1 / PHP 8.2
* '''Database''':
** MySQL: >= 5.6 or MariaDB >= 10.3
** MongoDB >= 4.4 (for extension [[Reference:CollabPads|CollabPads]])
* '''(Virtual) hardware requirements:'''
**'''CPU:'''
*** '''Linux: 8 Cores''' (min. 4 Cores)
*** Windows: 16 Cores (min. 8 Cores)
** '''Main memory:'''
***'''Linux: 16 GB''' (min. 8GB)
*** Windows: min. 16 GB
** '''Available hard drive space:'''
*** > 20 GB (depends on the planned storage of data)
*'''Other:'''
**Apache Tomcat >= 9 oder Jetty >= 9 (for PDF export and LaTexRenderer)
**ElasticSearch 6.8 with plugin “ingest-attachment”
**OpenJDK >= 10
**NodeJS 16

[[de:Setup:Systemanforderungen]]
[[Category:Setup]]

2024-10-04T13:07:43Z

Rvogel1:

==Help others to help you==
Sometimes things go wrong. In many cases the user is then confronted with cryptic or no error messages at all. This page provides help about getting more information about what exactly went wrong, so it can be fixed quickly. This is especially important when asking for help on locations like [https://community.bluespice.com community.bluespice.com].

Additional information can also be found at [[mediawikiwiki:Manual:How_to_debug|"Manual:How to debug" on MediaWiki.org]].

{{Textbox|boxtype=warning|header=Check for sensitive information|text=Most of the techniques described here will output very detailed information about the error, but also about the system and the context. The output may contain sensitive information like usernames, passwords, pathes, access-keys and many more. Before posting any information retrieved by this kind of debugging on a public location (like [https://community.bluespice.com community.bluespice.com]), make sure to redact all potential sensitive information!|icon=yes}}

== Generic information ==
In general it is a good idea to provide additional context information about the error. Usually this information is easily to access/gather by the one who reports an error and very valueable to anyone trying to help.

Such information can be
* Browser used (Firefox, Chrome, Edge, ...), ideally with the version
* URLs (which page the error occurs on, additional parameters that may play into the error)
* User permission level or role (admin, reader, editor, reviewer, ...)

Again: Be careful if the shared information contains sensible data and redact it if required.

== Server side debugging ==
There are various ways to get more information about errors by changing some configuration on the server side.

=== Wiki application ===

==== Enable detailed error reporting ====
Within you <code>LocalSettings.php</code> file, please add the following lines:<syntaxhighlight lang="php">
$GLOBALS['wgDebugDumpSql'] = true;
$GLOBALS['wgShowExceptionDetails'] = true;

</syntaxhighlight>This will turn error messages like <code>internal_api_error_DBQueryError</code> into a more detailed stack of program calls, including database queries and responses.

==== General debug log ====
Sometimes it can be useful to see all debugging information the application produces. To enable this general debug log please add the following lines within you <code>LocalSettings.php</code> file:<syntaxhighlight lang="php">
if ( isset( $_GET['dodebuglog'] ) ) {
$GLOBALS['wgDebugLogFile'] = "$IP/cache/debug.log";
}

</syntaxhighlight>Be aware that this configuration is set conditionally. It will only be used if the URL accessed in the browser contains some query string like <code>dodebuglog=1</code>. This is to allow a more isolated debug log file. Otherwise other requests (like calls to the <code>load.php</code> entrypoint for CSS and JS content) may also add into this file, which makes analysis more difficult.

===== Important log channels =====
{{Textbox|boxtype=important|header=Channel names must be ''exactly'' like listed here! Watch out for casing and spaces!|text=|icon=yes}}
{| class="wikitable"
!Source (Extension)
!Channel name(s)
!Use case
|-
|MW CORE
|<code>http</code>, <code>HttpError</code>
<code>JobExecutor</code>

<code>LocalFile</code>

<code>exception</code>

<code>DeferredUpdates</code>

<code>Parsoid</code>

<code>resourceloader</code>

<code>runJobs</code>

<code>session</code>, <code>login</code>

...
|
|-
|MWSTAKE COMPONENTS
|<code>ContentProvisioner</code>
<code>runjobs-trigger-runner</code>
|
|-
|Math
|<code>Math</code>
|Math
|-
|PluggableAuth
|<code>PluggableAuth</code>
|LDAP, SAML, OpenIDConnect
|-
|LDAPProvider
|<code>LDAP</code>
<code>MediaWiki\\Extension\\LDAPProvider\\Client</code>
|LDAP
|-
|LDAPAuthentication2
|<code>LDAPAuthentication2</code>
|LDAP
|-
|LDAPGroups
|<code>LDAPGroups</code>
|LDAP
|-
|LDAPUserInfo
|<code>LDAPUserInfo</code>
|LDAP
|-
|LDAPSyncAll
|<code>LDAPSyncAll</code>
|LDAP
|-
|LDAPAuthorization
|<code>LDAPAuthorization</code>
|LDAP
|-
|Auth_remoteuser
|<code>session</code>
|LDAP (SSO/Kerberos)
|-
|SimpleSAMLphp
|<code>SimpleSAMLphp</code>
|SAML
|-
|OpenIDConnect
|<code>OpenID Connect</code>
|OpenIDConnect
|-
|ImportOfficeFiles
|<code>ImportOfficeFiles</code>
<code>ImportOfficeFiles_RemoveOrphanedDirectories</code>

<code>ImportOfficeFiles_UI</code>
|
|-
|Workflows
|<code>workflows</code>
|
|-
|BlueSpiceArticlePreviewCapture
|<code>ArticlePreviewCapture</code>
|
|-
|OAuth
|<code>OAuth</code>
|
|-
|BlueSpiceUEModulePDF, BlueSpiceUEModuleBookPDF
|<code>BS::UEModulePDF</code>
|PDF
|-
|BlueSpiceExtendedSearch
|<code>BSExtendedSearch</code>
|Search
|-
|BlueSpiceWikiFarm
|<code>SimpleFarmerAPI</code>
|Farm operations
|}

===== Default exception log =====
By default, the application logs the channels <code>error</code> and <code>exception</code> into the regular PHP error log. In case <code>$wgShowExceptionDetails</code> is set to <code>false</code> , an user may just see something like this:
[[File:How to debug Internal Error No Details.png|border|center|thumb|617x617px]]
In such cases , administrators can check the PHP error log for the unique "error id".

Example:<syntaxhighlight lang="text">
> grep 48f97a8a07b0d68f245bf15d /var/logs/php_error

PHP message: [2024-10-04T15:02:47.217190+02:00] exception.ERROR: [48f97a8a07b0d68f245bf15d] /wiki/Special:Books Exception: File not found
{
"exception": "[object] (Exception(code: 0): File not found at /app/bluespice/w/extensions/BlueSpiceBookshelf/src/Special/Books.php:31)",
"exception_url": "/wiki/Special:Books",
"reqId": "48f97a8a07b0d68f245bf15d",
"caught_by": "entrypoint"
}
{
"host": "dc7af0034e3b",
"wiki": "bluespice",
"mwversion": "1.39.10",
"reqId": "48f97a8a07b0d68f245bf15d"
}
</syntaxhighlight>

=== Clientside output of serverside logs ===
Can be enabled using [[mediawikiwiki:Manual:$wgDebugToolbar|$wgDebugToolbar]]

Example:<syntaxhighlight lang="php">
$GLOBALS['wgDebugToolbar'] = isset( $_GET['dodebugtoolbar'] )
</syntaxhighlight>

With this setting you can append <code>?dodebugtoolbar=1</code> to the URL in the addressbar of your browser.

<gallery>
File:How to debug DebugToolbar1.png
File:How to debug DebugToolbar2.png
File:How to debug DebugToolbar3.png
File:How to debug DebugToolbar4.png
</gallery>

{{Textbox|boxtype=important|header=Incompatible with <code>$bsgDebugLogGroups</code>!|text=If you have any debug log channel wired via <code>$bsgDebugLogGroups</code> the clientside debug toolbar will not show all information. Some panels may be empty.|icon=yes}}

== Client side debugging ==
Many errors occur only on the client and server side debugging will not help. In such cases the webbrowser can be used to retrieve more information.

=== Browser development tools ===
Most modern browsers have sophisticated development tools. Usually they can be accessed by pressing the <code>F12</code> key on the keyboard.

==== JavaScript console ====
When some interface element (button, dialog, ...) does not behave like it should, it is usually worth checking the browsers JavaScript console.

{{Textbox|boxtype=tip|header=Nothing listed?|text=Sometimes it may be required to re-do the action that lead to the error with ''open console'' rather than opening it later.}}

'''Example:'''

[[File:How_to_debug_JS_console_01.png|center|frame]]

One can click the link on the right side of the line to see the location of where the error has emerged from.

'''Example:'''

[[File:How_to_debug_JS_console_02.png|center|frame]]

====Network panel====
Sometimes network communication in the background of the application fails. In such cases, the "Network" panel of the browsers developer tools may reveal more information.

The error is also shown in the "Console" tab.

'''Example:'''

[[File:How_to_debug_Network_panel_01.png|center|frame]]

When in the "Network" panel, one can select the faulty request from the list to get more information.

'''Example:'''

[[File:How_to_debug_Network_panel_02.png|center|frame]]

The various tabs "Header", "Payload", "Response", etc. can provide useful information. When reporting such an issue, you can just "copy" the information using the context menu.

'''Example:'''

[[File:How_to_debug_Network_panel_03.png|center|frame]]