Upgrade from BlueSpice 3 to 4

Archived! This documentation is obsolete and no longer applies to the current BlueSpice version.

System requirements

Browser

• Microsoft Edge
• Google Chrome
• Firefox

Server environment

Container images only

With BlueSpice 5, the main release of the software is via container images. Manual installation on is no longer supported. Please refer to out installation guide for more information.

Native installation on Windows Server is no longer supported.

If you need a different type of installation, please contact us.

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 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 "edit together" feature: MongoDB >= 4.4 ( >=8.0 recommended)

External Search Service

• OpenSearch 2.x with ingest-attachments plugin

No support for ARM Currently, installation is only supported on x86/x64 architecture. This is especially true when using Docker.

Note:You might need to add external repos to get the correct php on your server! Please check your package manager for the available php versions on your system.

Back up the old wiki

In BlueSpice 3, create a temporary migration folder and copy all necessary data:

mkdir /tmp/migration
cd /tmp/migration
wikifolder=/path/to/wikifolder
cp -r $wikifolder/images .
cp -r $wikifolder/extensions/BlueSpiceFoundation/config .
cp -r $wikifolder/LocalSettings.* .
#check for for locals in settings.d
find $wikifolder/settings.d/ -iname '*.local.php' -exec cp --parent {} /tmp/migration \;

Also search for specialized php files in settings.d (normally 090- or 099- ).

Upgrade step 1

This step has to be completed before the Upgrade step 2 further below.

Warning!BlueSpice 4.x cannot process wiki pages and files that were uploaded and edited by deleted users. To prevent data loss, don't skip any upgrade steps!

Create a "substitute user" for deleted users

In BlueSpice 3.x, create a user with a random password:

php maintenance/createAndPromote.php --force DeletedUser someR4ndomPass

Note:You may need to temporarily disable authentication plugins like LDAP-Stack, SAML or OpenIDConnect extensions.

Get the user_id of the substitute user by running the following command in the database:

SELECT user_id FROM user WHERE user_name = "DeletedUser";

Sql dump

Create the backup of your data:

mysql -u root -p bluespice > migrationdump.sql

Optional files for migration

If any of the following features apply to your installation, check if migration steps are necessary. In that case, add everything to your tar file and send it to the new server.

Examples of files that you might have to consider:

• ssl-certs
• apache.conf
• ldapprovider.json
• kerberos files (krb5.conf/keyfile)

Migrate to the new wiki

Grep LocalSettings.php for wgDB

grep wgDB LocalSettings.*
LocalSettings.local.php:$wgDBserver = "Your-IP";
LocalSettings.local.php:$wgDBname = "Your-datbase-name";
LocalSettings.local.php:$wgDBuser = "Your-database-user";
LocalSettings.local.php:$wgDBpassword = "Your-password";

and create the database and DBuser with the DBpassword. Grant all on database to the DBuser in mysql. Migrate the data:

mysql -u root -p bluespice < migration.sql 
cp -r images $wikifolder
cp -r extensions $wikifolder
cp -r LocalSettings.php $wikifolder
setWikiPerm $wikifolder

Modify LocalSettings.php

Replace:

$wgLogo = "$wgResourceBasePath/resources/assets/wiki.png";

with:

$wgLogos = [ '1x' => "$wgResourceBasePath/resources/assets/wiki.png" ];

• Check other LocalSettings.* for individual configurations from the old BlueSpice installation.
• Compare the migrated settings.d/*.local.php with the new settings.d/*.php and check for individual (probably deprecated) configurations. Do the same with 09*-xx.php.
• Copy to $wikifolder/settings.d/ what is needed.

Upgrade step 2

Assign all pages and files without a valid editor user to your newly created substitute user:

cd $wikifolder
 php extensions/BlueSpiceFoundation/maintenance/PrepareActorMigration.php --unknownUserId=<user-id-from-step I. > --unknownUserName=DeletedUser

Optional

• Copy the following files (if applicable in your case):apache.conf, krb5.conf, Kerberos-key, ldapprovider.json
• Add to VirtualHost in Apache.conf after rewrite rules:

AllowEncodedSlashes NoDecode

Last steps

Run the following maintenance scripts:

cd $wikifolder
php maintenance/update.php --quick
php extensions/BlueSpiceExtendedSearch/maintenance/initBackends.php --quick
php extensions/BlueSpiceExtendedSearch/maintenance/rebuildIndex.php --quick

screen 
    while  [ "$(php maintenance/showJobs.php)" != "0" ]; do php maintenance/runJobs.php --maxjobs 100; done

The last step will take a while.

Known possible issues after the update

Problems with VisualEditor

Add in includes/libs/http/MultiHttpClient.php after line 327:

curl_setopt( $ch, CURLOPT_SSL_VERIFYHOST, 0 );
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, 0 );