Setup:BlueSpice Operating Manual

Objective

The objective of this operating manual is to enable you to run BlueSpice smoothly and successfully in your IT environment. It aims to answer your questions as deciders, IT auditors and server administrators, such as:

• Where do I get information about BlueSpice and its development?
• What do I have to consider when operating BlueSpice?
• How do I backup and monitor BlueSpice?

The most current version can be found at https://wiki.bluespice.com . This manual is designed to provide general information. Feel free to copy it over to your local BlueSpice and amend it according to your process and documentation requirements. Since the IT environment can change over time through updates and restructuring, it is advisable to check the information in the operating manual for being up-to-date.

The structure of this manual is based on the recommendations of the German Federal Office for Information Security, which can be found here.

Overview

System overview

BlueSpice is a webbased client-server application. On the server side, it uses a web server (Nginx), the script language PHP, two databases (MariaDB, MongoDB), a JAVA application server (Tomcat), NodeJS server and OpenSearch. All that is required on the server is the installation of a container runtime environment.

BlueSpice can be run in a distributed environment. Certain services can be put on individual servers. One possible scenario is to scale the web frontend service horizontally.

Typically, inhouse deployments of BlueSpice consist of a production environment and a corresponding test environment. In scenarios with elevated SLAs, an additional QA environment is used as an intermediary before production.

Owners, responsible persons and contacts

BlueSpice is developed and maintained by

Hallo Welt! GmbH Bruderwöhrdstraße 29 93055 Regensburg Germany https://www.hallowelt.com

For technical questions, please contact Hallo Welt! GmbH support at support@hallowelt.com.

For questions about your contract, please contact the Hallo Welt! GmbH sales team at sales@hallowelt.com .

Operating times

Typically, BlueSpice instances run 24/7. Operations are managed by the organization's IT department or their service providers. Hallo Welt! provides support and guidance during their office hours (8am - 6pm CET/CEST).

System and version history

All BlueSpice versions are documented in the BlueSpice helpdesk: https://en.wiki.bluespice.com/wiki/Setup:Release_History

All changes can be retraced in our current and archived release notes: https://en.wiki.bluespice.com/wiki/Setup:Release_Notes

Documentation

BlueSpice maintains an online documentation which is continuously kept up to date: https://en.wiki.bluespice.com

There is also a user manual: https://en.wiki.bluespice.com/wiki/UserManual:User_Manual_Introduction

Administration is documented here: https://en.wiki.bluespice.com/wiki/UserManual:Admin_Manual_Introduction

In addition, there is a community forum: https://community.bluespice.com

News about the product can be found in our blog: https://bluespice.com/category/news-know-how/

Also, BlueSpice maintains a newsletter. Sign up here: https://bluespice.com/

For more information, follow us on social media: https://bsky.app/profile/bluespice-wiki.bsky.social, https://fosstodon.org/@bluespice, https://www.youtube.com/@BlueSpiceVideo

Installation manual

BlueSpice maintains an online installation manual: https://en.wiki.bluespice.com/wiki/Setup:Installation_Guide

System architecture and interfaces

The following section gives an overview of the components of BlueSpice and how they interact with each other and the environment.

System integration

BlueSpice is a web application which can be integrated with your IT environment, most notably authentication and email.

Server architecture

Internally, BlueSpice has several components which are responsible for parts of the functionality.

BlueSpice docker architecture

Components and responsibilities

Servers, operating system, licenses and software infrastructure are typically managed by your organization's IT.

Hallo Welt! typically manages the application and required components.

There may be special contractual agreements.

External interfaces (to other organizations)

Technically, BlueSpice can be set up to operate completely self-contained (contact our support if you have questions about your instance). On the server, no external sources are queried. In the standard installation, there are content modules which draw data from external sources on the client side (browser):

• maps: Embedded maps are collected from Google or OpenStreetMap.
• widgets: The purpose of widgets is to display content from public sources like YouTube.

On the organizational side, the team of Hallo Welt! GmbH typically provides 3rd level support for subscribed BlueSpice instances. Hallo Welt! GmbH teams up with the internal IT of the organization as well as with IT infrastructure providers of our customers.

IT internal interfaces

A standard BlueSpice installation connects to the following services in order to be fully functional:

• User directory: BlueSpice can be configured to authenticate against a company user directory (typically Active Directory). The protocols used are OpenIdConnect, SAML und LDAP.
• Email: BlueSpice needs to be connected to an email server in order to send notifications.

API

BlueSpice comes with an API interface.

• For instructions on how to handle the API, see here: https://www.mediawiki.org/wiki/API:Main_page
• For a comprehensive list of API modules, see here: https://en.wiki.bluespice.com/w/api.php

Installation and system requirements

System requirements

The current system requirements are documented here: https://en.wiki.bluespice.com/wiki/Setup:System_requirements

Software catalogue

All BlueSpice components are listed in the software catalogue: https://en.wiki.bluespice.com/wiki/Setup:Software_Catalogue

Changes in configuration

Changes in configuration can occur in minor and major releases. Please consider the upgrade information provided here: https://en.wiki.bluespice.com/wiki/Setup:Installation_Guide/Upgrade

Start and interrupt the service

Unplanned server outage

Identify which service is not running and restart this service.

Standard operations

User management

• All users are managed in the application. For details, see https://en.wiki.bluespice.com/wiki/Manual:Extension/BlueSpiceUserManager

Monitoring

Apart from the common parameters to monitor (disk space, CPU load, memory usage), the following services can be monitored for availability:

• Web server: ping the login page of the wiki: <wiki_url>/Special:Login
• Database: check database connectivity with username and password authentication.

If any of those services is not available, BlueSpice is either not operational or experiencing functional restrictions.

Diagnostics

In case of errors, please consider the error logs. These are:

• In the web browser, open the console and check for JavaScript errors
• For the web server, check the web server's error log and php error log.

Troubleshooting

If one or more services are not working:

• Check the available system resources, in particular the free disk space
• Restart all services

If the problem persists, contact BlueSpice support.

Key performance indicators

Server

Standard parameters for servers apply:

• Disk space < 80% usage
• CPU load should not peak to 100% for more than 1s
• Load average should not be more than CPU core count
• Average memory usage should not exceed 90%
• For GNU/Linux systems, try to avoid high swap space usage.

​The php error log should not report any FATAL or WARNING messages.

Client

The reference page Special:Version should load under 4s without browser cache and under 2.5s with browser cache enabled.

Known restrictions

Functional restrictions

Functionality:

• bluespice/web: Required for basic BlueSpice operations
• bluespice/task: Required for basic BlueSpice operations
• bluespice/database: Required for basic BlueSpice operations
• bluespice/pdf: Required for PDF
• bluespice/search: Required for ExtendedSearch and various title selection fields
• bluespice/diagram: Required for editing diagrams
• bluespice/collabpads: Required for simultaneous editing of wiki pages
• bluespice/collabpads-database: Required for running bluespice/collabpads
• bluespice/formula: Required for displaying mathematical and chemical formulas
• bluespice/proxy: Required for basic BlueSpice operations

Technical restrictions

Updates of major and minor level might require a system downtime due to database migration operations.

Resource related restrictions

Response times are dependent on the server resources, foremost CPU power.

The number of concurrent users a server can handle is directly related to server memory size and CPU power.

Please note: we strongly recommend having a separate testing system. This can be used for update/upgrade preparation, debugging and collecting sizing information. If no testing system is present, occasional downtimes may occur when debugging and maintenance operations are conducted.

Archiving and deletion of data

Variable data

The following locations store variable data, which is not recoverable in case of data loss, and must be backed up regularly:

• The databases store most data of BlueSpice, including articles, users and action logs.
• The volumes of the various services store additional production data.
  • Data in the <code>bluespice/search</code> volume can be restored if necessary.

Log files and error files

The various services write their logs to the standard output, which is managed by the container runtime environment used.

Security and compliance

Internet access

For standard operations, BlueSpice does not require Internet access. BlueSpice does not make any outgoing calls. See section External interfaces for details.

Auxiliary service data access

Supporting services run in containers and, unless otherwise configured, are only accessible from the main application.

Privacy

GDPR compliancy is handled by BlueSpice Privacy Center. More information can be found here: https://en.wiki.bluespice.com/wiki/Manual:Extension/BlueSpicePrivacy

Legal information

For all legal information, including the Subscription contract, GDPR information and DPA, Anti Bribery Policy and Software catalogue, please refer to the BlueSpice homepage: https://bluespice.com/legal-documents-and-guidelines/

PDF exclude - start

---

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

PDF exclude - end