BlueSpice 5 is deployed as a container-based web application stack. The architecture separates user-facing web traffic, background processing, persistent data services and supporting services so that installations can run as a compact all-in-one setup or as a distributed, horizontally scalable environment. BlueSpice 5 is delivered via container images; manual installation is possible, but no longer supported as installation method.
High-level architecture
Users / Browsers
|
v
Load Balancer / Reverse Proxy
|
+-----------------------------+
| |
v v
Frontend Container Frontend Container
Node 1 Node 2 ... n
API / BlueSpice app / API / BlueSpice app /
Resources Resources
| |
+-------------+---------------+
|
v
Shared Backend Services
|
+----------------+----------------+
| | |
Database Storage Search
MariaDB / Shared wiki OpenSearch
MySQL files / data index
MongoDB* directory
|
v
Common Services
Cache, PDF rendering, formula rendering,
diagram editing, Tomcat / Java services,
NodeJS services and other auxiliary services
|
v
Taskrunner Container
Regular tasks / Notifications / Maintenance
* MongoDB is used where features such as collaborative editing require it. The main application database is MySQL or MariaDB; BlueSpice 5 also supports external database services if required.
Load balancer / Reverse proxy
The Load balancer is the central entry point for users. It accepts HTTPS requests and routes them to one or more frontend containers. In a single-node setup, this can be the proxy container shipped with the BlueSpice stack. In enterprise or high-availability environments, the proxy layer can be replaced by an existing customer load balancer or reverse proxy infrastructure. The Docker installation guide explicitly supports a custom load balancer / proxy scenario.
The load balancer is responsible for TLS termination, routing, health checks and distribution of traffic across Node 1, Node 2 and additional frontend nodes. Only the frontend containers should receive external web traffic; databases, storage, search and task services remain internal backend services.
Frontend container: API, BlueSpice app and resources
The frontend container is the user-facing application container. It serves the BlueSpice web interface, MediaWiki and BlueSpice APIs, static resources, skins, JavaScript, CSS and user interactions. In the Docker stack this corresponds to the main wiki web service, commonly referred to as wiki-web. The BlueSpice Docker stack defines the main wiki containers as wiki-web and wiki-task.
Frontend containers should be treated as stateless application nodes as much as possible. Persistent data such as wiki content, uploaded files, search indexes and database records must be stored in the shared backend services. This allows additional frontend nodes, shown as Node 2 ... n, to be added behind the load balancer for horizontal scaling.
Taskrunner container: Regular tasks, notifications and maintenance
The taskrunner container handles background work that should not be executed directly in the user request path. This includes regular scheduled jobs, notification processing, maintenance scripts, update tasks, queue processing and other recurring application tasks. In the Docker stack this corresponds to the wiki-task container. During the first startup, the wiki-task container also performs the initial installation and database setup.
Separating the taskrunner from the frontend improves operational stability. User traffic remains focused on web requests, while maintenance and asynchronous workloads are handled independently. In distributed setups, the taskrunner must use the same database, storage and service configuration as the frontend containers.
Database
The database stores the structured application data of the wiki, including pages, revisions, users, permissions, configuration data and extension data. BlueSpice 5 uses MySQL or MariaDB for the main application database. The standard container stack includes database services, but external database services can also be configured.
For installations with higher availability or stricter operational requirements, the database should be operated as a managed or clustered service according to the customer’s infrastructure standards. All frontend and taskrunner containers connect to the same database backend.
Storage
Storage contains persistent file-based data such as uploaded files, generated files, configuration-related data and other wiki data that must survive container restarts or replacement. In a multi-node architecture, storage must be shared between all frontend and taskrunner containers so that every node sees the same files and application state.
The Docker deployment uses a configurable data directory, for example DATADIR=/data/bluespice, to store persistent data outside the containers.
Search
Search is provided by OpenSearch. BlueSpice 5 supports OpenSearch 2.x with the ingest-attachments plugin, which enables indexing of wiki content and attached files.
The search service is a shared backend component. All frontend nodes and the taskrunner use the same search service so that users receive consistent search results regardless of which frontend node handles their request.
Common services
Common services provide supporting functionality used by the BlueSpice application. Depending on the deployment, these services can include caching, PDF rendering, formula rendering, diagram editing, Java/Tomcat services, NodeJS services and other auxiliary services. The Docker stack separates these into stateless service containers and persistent data service containers.
The BlueSpice operating manual describes the server-side stack as using Nginx, PHP, MariaDB, MongoDB, Tomcat, NodeJS and OpenSearch, all operated through a container runtime environment.
Node 2 ... n: Horizontal scaling
Additional nodes can be added by running further frontend containers behind the load balancer. This is the primary horizontal scaling model for BlueSpice web traffic. The operating manual explicitly notes that BlueSpice can run in a distributed environment and that one possible scenario is horizontal scaling of the web frontend service.
In this model, Node 1, Node 2 and all further nodes are equivalent application nodes. They do not store authoritative application data locally. Instead, they rely on the shared database, shared storage, shared search service and shared common services. This makes it possible to scale user-facing traffic while keeping the application data consistent.
Request and processing flow
A typical user request flows through the load balancer to one of the available frontend containers. The frontend container serves the BlueSpice interface, processes API calls and retrieves or writes data through the database, storage and search services. Static resources are delivered by the frontend container, while backend functions such as search indexing, notifications, maintenance and scheduled jobs are handled by the taskrunner.
This separation allows BlueSpice 5 to support both simple deployments and larger distributed environments. The same architectural model can start with a single node and later be extended with additional frontend nodes, external database services, external search services or an existing enterprise load balancer.
