Upgrade from BlueSpice 3 to 4

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
• (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

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:

mysqldump -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 );

---

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