Setup:BlueSpice Operating Manual and Template:Messagebox/styles.css: Difference between pages

(Difference between pages)
mNo edit summary
 
No edit summary
 
Line 1: Line 1:
{{DISPLAYTITLE:BlueSpice Operating Manual}}
/* Infoboxes */
<bs:ueparams template="BlueSpice Book" />
.hw-messagebox {
==Objective==
padding: 14px;
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:  
margin: 2em 0 1em 0;
display: block;
position:relative;
clear:both;
}
.hw-messagebox.icon {
padding-left: 35px;
}
.hw-messagebox.icon:before {
position: absolute;
font-size: 1.6em;
top: 8px;
font-family: "fontawesome";
left:8px;
}
.hw-messagebox p {
margin:0
}
.notification-note, .notification-Hinweis {
border-left: solid 4px #3498db;
background:#d9edf7;
}


*Where do I get information about BlueSpice and its development?
.notification-bsversion {
*What do I have to consider when operating BlueSpice?
border-left: solid 4px #f8c57f;
*How do I backup and monitor BlueSpice?
background:#fdeed9
}


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.
.notification-bsversion.icon::before{
content: "\f069";
color: #f8c57f
}


The structure of this manual is based on the recommendations of the German [https://www.bsi.bund.de/EN/TheBSI/thebsi_node.html Federal Office for Information Security], which  [https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Grundschutz/Download/IT-GS-Bausteine/Cloud_Speicher/Betriebshandbuch.html can be found here].
.boxlabel {
 
font-weight:bold;
==Overview==
padding-right:0.5em;
 
}
===System overview===
.notification-note.icon::before, .notification-Hinweis.icon::before{
BlueSpice is a webbased client-server application. On the server side, it uses a web server (Apache, IIS, Nginx), the script language PHP, a database (MySQL or MariaDB), a JAVA application server (Tomcat or Jetty), and Elasticsearch. There are several binaries required on the server, such as phantomJS and Imagemagick. Until version BlueSpice ≤ 3.2.x, a NodeJS service (Parsoid) is used as well.
content: "\f05a ";
 
color: #3498db;
BlueSpice can be run in a distributed environment. All services can be put on individual servers (web server + PHP, database, application server, Elasticsearch). A common scenario is to scale the web server and PHP horizontally.
}
 
.notification-tip,.notification-Tipp {
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.
border-left: solid 4px #f2c412;
 
background:#FFF5C9;
===Owners, responsible persons and contacts===
}
BlueSpice is developed and maintained by
.notification-tip.icon::before, .notification-Tipp.icon::before{
 
content: "\f0eb";
:Hallo Welt! GmbH
color: #dbb213;
:Bruderwöhrdstraße 29
font-size: 1.7em;
:93055 Regensburg
margin-left: 5px;
:Germany
}
:https://www.hallowelt.com
.notification-warning, .notification-Warnung  {
 
border-left: solid 4px #c23c2b;
For technical questions, please contact Hallo Welt! GmbH support at [mailto:support@hallowelt.com support@hallowelt.com].
background: #f2dede
 
}
For questions about your contract, please contact the Hallo Welt! GmbH sales team at [mailto:sales@hallowelt.com sales@hallowelt.com] .
.notification-warning.icon::before, .notification-Warnung.icon::before{
 
content: "\f071";
===Operating times===
color: #c23c2b;
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).
}
 
.notification-important, .notification-Wichtig {
===System and version history===
border-left: solid 4px #ffa406;
All BlueSpice versions are documented in the BlueSpice helpdesk: https://en.wiki.bluespice.com/wiki/Setup:Release_History
background: #fedb9c;
 
margin-left: 2px;
All changes can be retraced in our current and archived release notes: https://en.wiki.bluespice.com/wiki/Setup:Release_Notes
}
 
.notification-important.icon::before, .notification-Wichtig.icon::before{
===Documentation===
content: "\f06a";
BlueSpice maintains an online documentation which is continuously kept up to date: [https://en.wiki.bluespice.com/wiki/Setup:System_requirements https://en.wiki.bluespice.com]
color: #ffa406;
 
}
There is also a user manual: https://en.wiki.bluespice.com/wiki/UserManual:User_Manual_Introduction
.notification-example, .notification-Beispiel {
 
border-left: solid 4px #00b241;
Administration is documented here: https://en.wiki.bluespice.com/wiki/UserManual:Admin_Manual_Introduction
background: #dff0d8;
 
}
In addition, there is a community forum: https://sourceforge.net/p/bluespice/_list/tickets
.notification-example.icon::before, .notification-Beispiel.icon::before{
 
content: "\f0a4";
News about the product can be found in our blog: https://bluespice.com/category/news-know-how/
color: #00b241;
 
}
Also, BlueSpice maintains a newsletter. Sign up here: https://bluespice.com/
.notification-neutral, .notification-Neutral {
 
background:#eaeaea;
For more information, follow us on Twitter: https://twitter.com/BlueSpiceTweets
padding:14px;
 
}
===Installation manual Windows/Linux (including upgrade instructions)===
.notification-neutral.icon, .notification-Neutral.icon {
BlueSpice maintains an online installation manual: https://en.wiki.bluespice.com/wiki/Setup:Installation_Guide
text-indent:0;
 
}
==System architecture and interfaces==
.notification-neutral.icon::before, .notification-Neutral.icon::before{
The following section gives an overview of the components of BlueSpice and how they interact with each other and the environment.
content: "\f0a9 ";
 
color: #555;
===System integration===
left: 10px;
BlueSpice is a web application which can be integrated with your IT environment, most notably LDAP and email.
top: 8px;
 
}
<div style="text-align:center"><bs:drawio filename="BlueSpice system architecture high level" /></div>
.notification-neutral .boxlabel, .notification-Neutral .boxlabel {
 
display:none;
===Server architecture===
}
Internally, BlueSpice has several components which are responsible for parts of the functionality.
 
<div style="text-align:center"><bs:drawio filename="BlueSpice system architecture server" /></div>
 
===Vertically distributed architecture===
For simple scaling, some services can be externalized to other physical or virtual servers.
 
<div style="text-align:center"><bs:drawio filename="BlueSpice system architecture server distributed simple" /></div>
 
===Horizontally distributed architecture===
For high traffic or high availability demands, BlueSpice can be set up to scale horizontally.
 
<div style="text-align:center"><bs:drawio filename="BlueSpice system architecture server distributed horizontally" /></div>
 
===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):
 
*'''draw.io''': The diagram tool is loaded directly from draw.io. All content remains on the BlueSpice wiki.
*'''maps''': Embedded maps are collected from Google or OpenStreetMap.
*'''widgets''': The purpose of widgets is to display content from public sources like YouTube.
*'''chemical formulas''': The formula rendering uses an external service via Wikimedia's REST API.
 
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 LDAP and SAML.
*'''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==
 
===Startup===
In order to start up BlueSpice, all the required services need to be running. Please make sure you start the services in the order given here:
 
'''Database'''
 
*Linux: <code>service mysql start</code> OR <code>systemctl start mysql</code>
*Windows: <code>services.msc</code>
 
'''Application server''' (Tomcat or Jetty)
 
*Linux: <code>service jetty9 start</code> OR <code>systemctl start jetty9</code>
*Windows: <code>services.msc</code>
 
'''Elasticsearch'''
 
*Linux: <code>service elasticsearch start</code> OR <code>systemctl start elasticsearch</code>
*Windows: <code>services.msc</code>
 
'''Parsoid''' (not required since BlueSpice 4.0)
 
*Linux: <code>pm2 start /opt/parsoid/bin/server.js</code> OR <code>systemctl start parsoid</code>
*Windows: <code>services.msc</code>
 
'''Web server'''
 
*Linux: <code>service apache2 start</code> OR <code>systemctl start apache2</code>
*Windows: <code>services.msc</code>
 
===Shutdown===
In order to shut down BlueSpice, all the required services need to be stopped. Please make sure you stop the services in the order given here:
 
'''Web server'''
 
*Linux: <code>service apache2 stop</code> OR <code>systemctl stop apache2</code>
*Windows: <code>services.msc</code>
 
'''Parsoid''' (not required since BlueSpice 4.0)
 
*Linux: <code>pm2 stop /opt/parsoid/bin/server.js</code>  OR <code>systemctl stop parsoid</code>
*Windows: <code>services.msc</code>
 
'''Application server''' (Tomcat or Jetty)
 
*Linux: <code>service jetty9 stop</code> OR <code>systemctl stop jetty9</code>
*Windows: <code>services.msc</code>
 
'''Elasticsearch'''
 
*Linux: <code>service elasticsearch stop</code> OR <code>systemctl stop elasticsearch</code>
*Windows: <code>services.msc</code>
 
'''Database'''
 
*Linux: <code>service mysql stop</code> OR <code>systemctl stop mysql</code>
*Windows: <code>services.msc</code>
 
===Configuration changes===
After changes to the configuration, the service with the changed configuration needs to be restarted.
 
'''Webserver'''
 
*Linux: <code>service apache2 restart</code>
*Windows: <code>[https://en.wikipedia.org/wiki/Service_Control_Manager services.mmc]</code>
 
'''Parsoid''' (not required since BlueSpice 4.0)
 
*Linux: <code>pm2 restart /opt/parsoid/bin/server.js</code>
*Windows: <code>[https://en.wikipedia.org/wiki/Service_Control_Manager services.mmc]</code>
 
'''Application server''' (Tomcat or Jetty)
 
*Linux: <code>service jetty9 restart</code>
*Windows: <code>[https://en.wikipedia.org/wiki/Service_Control_Manager services.mmc]</code>
 
'''Elasticsearch'''
 
*Linux: <code>service elasticsearch restart</code>
*Windows: <code>[https://en.wikipedia.org/wiki/Service_Control_Manager services.mmc]</code>
 
'''Database'''
 
*Linux: <code>service mysql restart</code> OR <code>systemctl restart mysql</code>
*Windows: <code>[https://en.wikipedia.org/wiki/Service_Control_Manager services.mmc]</code>
 
===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
 
===Recurring background tasks===
BlueSpice is set up to conduct some tasks in the background. These are
 
*<code>maintenance/runJobs.php</code>
 
For details see: https://en.wiki.bluespice.com/wiki/Setup:Installation_Manual/Optimization/Cronjobs
 
===Backup===
Detailed backup instructions can be found here: https://en.wiki.bluespice.com/wiki/Setup:Installation_Guide/Advanced/Backup
 
===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.
*Parsoid: check port 8000 connectivity via 127.0.0.1 (not required since BlueSpice 4.0)
*Elasticsearch: check port 9200 connectivity via 127.0.0.1
 
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.
 
For a standard server sizing (4 cores, 8 GB ram), the number of average simultaneous users is optimized for 25 per server. This means, one server can handle about 125 concurrent users.
 
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===
This is now services map onto BlueSpice functionality:
 
*Web server: required for BlueSpice basic operations
*Database: required for BlueSpice basic operations
*Tomcat: required for PDF and VisualDiff
*Elasticsearch: required for ExtendedSearch and various title select boxes. Will fallback to standard MediaWiki search if not available.
*PhantomJS: required for rendering article preview images.
*Parsoid: required for VisualEditor. Note: since BlueSpice 4.0 this is no longer required.
 
All services other than web server and database are optional. If not present, the named functionality will not be available.
 
===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 (Strongly growing data)===
The following locations store variable data, which is not recoverable in case of data loss, and must be backed up regularly:
 
*The database stores most data of BlueSpice, including articles, users and action logs.
*The images folder stores all uploaded files.
 
There is some secondary data stored in Elasticsearch (for BlueSpice Social and Statistics). This data can be fully recovered from the primary data stored in the database.
 
===Master data (Slowly growing data)===
The following locations store master data, which requires considerable effort to recover in case of data loss and should be backed up regularly:
 
*Configuration:
**LocalSettings.php and LocalSettings.BlueSpice.local.php contain the basic configuration including sitename, security keys and database access.
**settings.d folder contains information about activated extensions.
**extensions/BlueSpiceFoundation/config folder holds information about namespace setup and permission configuration.
*Templates and skins
**extensions/BlueSpiceFoundation/data folder holds PDF templates.
 
===Log files and error files===
 
*Php error log: <code>/var/log/php-fpm.log</code> (Only for php-fpm service)
*Apache access log: <code>/var/log/apache2/*access.log</code>
*Apache error logs: <code>/var/log/apache2/*error.log</code> (Also includes PHP errors)
*Browser console
*Parsoid log: <code>pm2 logs</code> OR <code>/var/log/parsoid.log</code>(systemd and init.d) (not required since BlueSpice 4.0).
*Elasticsearch: <code>/var/log/elasticsearch/</code>
*Tomcat: By default logging is turned of. Depending on system, logging can be enabled via configuration XML files.
*Windows event log: MS Windows logs are not txt format. Access is possible via [https://en.wikipedia.org/wiki/Event_Viewer Event Viewer]
 
==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.
 
In our default setup, the client will access draw.io for editing diagrams. Here, only application data is loaded from the site. No content data will be passed on to draw.io. On request, Hallo Welt! can install an on-premise version of draw.io (additional charges apply).
 
===Auxiliary service data access===
Tomcat, Elasticsearch and PhantomJS will receive data from BlueSpice core components. They are agnostic to access rights and do have full access to all data stored on BlueSpice. It is therefore recommended to restrict access to these services to localhost or the web server's IP address. In case Hallo Welt! performs the installation, this is the default setup. No external access to these services shall be permitted.
 
===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/
 
 
[[en:{{FULLPAGENAME}}]]
[[de:Setup:BlueSpice Betriebshandbuch]]
[[Category:Setup]]

Revision as of 15:32, 25 July 2022

/* Infoboxes */
.hw-messagebox {
padding: 14px;
margin: 2em 0 1em 0;
display: block;
position:relative;
clear:both;
}
.hw-messagebox.icon {
padding-left: 35px;
}
.hw-messagebox.icon:before {
position: absolute;
font-size: 1.6em;
top: 8px;
font-family: "fontawesome";
left:8px;
}
.hw-messagebox p {
	margin:0
}
.notification-note, .notification-Hinweis {
border-left: solid 4px #3498db;
background:#d9edf7;
}

.notification-bsversion {
border-left: solid 4px #f8c57f;
background:#fdeed9
}

.notification-bsversion.icon::before{
content: "\f069";
color: #f8c57f
}

.boxlabel {	
font-weight:bold;
padding-right:0.5em;
}
.notification-note.icon::before, .notification-Hinweis.icon::before{
content: "\f05a ";
color: #3498db;
}
.notification-tip,.notification-Tipp {
border-left: solid 4px #f2c412;
background:#FFF5C9;
}
.notification-tip.icon::before, .notification-Tipp.icon::before{
content: "\f0eb";
color: #dbb213;
font-size: 1.7em;
margin-left: 5px;
}
.notification-warning, .notification-Warnung  {
border-left: solid 4px #c23c2b;
background: #f2dede
}
.notification-warning.icon::before, .notification-Warnung.icon::before{
content: "\f071";
color: #c23c2b;
}
.notification-important, .notification-Wichtig {
border-left: solid 4px #ffa406;
background: #fedb9c;
margin-left: 2px;
}
.notification-important.icon::before, .notification-Wichtig.icon::before{
content: "\f06a";
color: #ffa406;
}
.notification-example, .notification-Beispiel {
border-left: solid 4px #00b241;
background: #dff0d8;
}
.notification-example.icon::before, .notification-Beispiel.icon::before{
content: "\f0a4";
color: #00b241;
}
.notification-neutral, .notification-Neutral {
background:#eaeaea; 
padding:14px;
}
.notification-neutral.icon, .notification-Neutral.icon {
text-indent:0;
}
.notification-neutral.icon::before, .notification-Neutral.icon::before{
content: "\f0a9 ";
color: #555;
left: 10px;
top: 8px;
}
.notification-neutral .boxlabel, .notification-Neutral .boxlabel {
display:none;
}



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

No categories assignedEdit

Discussions