Migration from MediaWiki to BlueSpice

Before you start

It is important to check the compatibility of your current MediaWiki installation and the BlueSpice version to which you want to migrate:

BlueSpice version 3.x is based on MediaWiki 1.31.x
BlueSpice version 4.x until 4.2.7 is based on MediaWiki 1.35.x
BlueSpice version 4.x starting from 4.3 is based on MediaWiki 1.39.x
BlueSpice version 5.x is based on MediaWiki 1.43.x

Backup

Create a full backup of your current installation. Commands may differ depending on your operating system.

Create a directory to store the backup:

mkdir -p /opt/mediawiki-migration-backup/{db,web}

Create the database dump:

mysqldump -u DB_USER_OR_ROOT -p MEDIAWIKI_DATABASE_NAME > /opt/mediawiki-migration-backup/db/database.sql

Copy everything in the web root to the backup folder:

cp -Rvf /PATH/TO/MEDIAWIKI/FOLDER/* /opt/mediawiki-migration-backup/web/

We will use this backup later for the migration process as well.

Preparing the migration

You can create a separate user account and database for BlueSpice. This step is optional but recommended. The following steps are based on such a separately created user and database.

If you choose not to create a separate user account and database, replace the following commands accordingly.

Create a MySQL/MariaDB user via MySQL CLI:

CREATE USER 'bluespice'@'localhost' IDENFITIED BY 'PleaseChooseAComplexPassword';

Create a database for BlueSpice via MySQL CLI:
```
CREATE DATABASE bluespice;
```
Grant the required privileges for the bluespice user to the bluespice database via MySQL CLI:
```
GRANT ALL PRIVILEGES ON bluespice.* TO 'bluespice'@'localhost';
FLUSH PRIVILEGES;
```
Now we have an empty SQL database and are ready to import.

Importing the data

Import the SQL dump from the backup you created earlier:
```
mysql -u bluespice -p bluespice < /opt/mediawiki-migration-backup/db/database.sql
```
After this command, enter the password you chose for the bluespice database user.

Next, clean up the old installation folder and create an empty one.

rm -Rf /PATH/TO/MEDIAWIKI/FOLDER/

and

mkdir -p /PATH/TO/MEDIAWIKI/FOLDER/

Next, extract the BlueSpice package and place it into the /PATH/TO/MEDIAWIKI/FOLDER/
```
cd /PATH/TO/MEDIAWIKI/FOLDER/
```
Copy the images folder from the backup to the /PATH/TO/MEDIAWIKI/FOLDER/ :
```
cp -Rf /opt/mediawiki-migration-backup/images .
```
Set the correct permissions based on your operating system to the folder /PATH/TO/MEDIAWIKI/FOLDER/ .

Configuration settings

If you are migrating to a Docker installation using bluespice-deploy, your new installation does not provide a concrete LocalSettings.php.

Instead, you can add your customized settings to pre-init-settings.php or post-init-settings.php.

Please check Setup:Installation_Guide/Docker#Custom_wiki_application_configuration for details.

In /PATH/TO/MEDIAWIKI/FOLDER/, create a new file named LocalSettings.php and copy the following content into the file:

<?php
# This file was automatically generated by the MediaWiki 1.35.3
# installer. If you make manual changes, please keep track in case you
# need to recreate them later.
#
# See includes/DefaultSettings.php for all configurable settings
# and their default values, but don't forget to make changes in _this_
# file, not there.
#
# Further documentation for configuration settings may be found at:
# https://www.mediawiki.org/wiki/Manual:Configuration_settings

# Protect against web entry
if ( !defined( 'MEDIAWIKI' ) ) {
	exit;
}


## Uncomment this to disable output compression
# $wgDisableOutputCompression = true;

$wgSitename = "YOUR_WIKI_NAME";

## The URL base path to the directory containing the wiki;
## defaults for all runtime URL paths are based off of this.
## For more information on customizing the URLs
## (like /w/index.php/Page_title to /wiki/Page_title) please see:
## https://www.mediawiki.org/wiki/Manual:Short_URL
$wgScriptPath = "/w"; # <--- PLEASE CHECK YOUR DOCUMENTROOT

## The protocol and server name to use in fully-qualified URLs
$wgServer = "http(s)://your-domain.ltd";

## The URL path to static resources (images, scripts, etc.)
$wgResourceBasePath = $wgScriptPath;

## The URL paths to the logo.  Make sure you change this from the default,
## or else you'll overwrite your logo when you upgrade!
$wgLogos = [ '1x' => "$wgResourceBasePath/resources/assets/wiki.png" ];

## UPO means: this is also a user preference option

$wgEnableEmail = true;
$wgEnableUserEmail = true; # UPO

$wgEmergencyContact = "nomail@localhost.localdomain";
$wgPasswordSender = "nomail@localhost.localdomain";

$wgEnotifUserTalk = false; # UPO
$wgEnotifWatchlist = false; # UPO
$wgEmailAuthentication = true;

## Database settings
$wgDBtype = "mysql";
$wgDBserver = "YOUR_DATABASE_SERVER";
$wgDBname = "bluespice";
$wgDBuser = "bluespice";
$wgDBpassword = "PleaseChooseAComplexPassword";

# MySQL specific settings
$wgDBprefix = "";

# MySQL table options to use during installation or update
$wgDBTableOptions = "ENGINE=InnoDB, DEFAULT CHARSET=binary";

# Shared database table
# This has no effect unless $wgSharedDB is also set.
$wgSharedTables[] = "actor";

## Shared memory settings
$wgMainCacheType = CACHE_NONE;
$wgMemCachedServers = [];

## To enable image uploads, make sure the 'images' directory
## is writable, then set this to true:
$wgEnableUploads = false;
$wgUseImageMagick = true;
$wgImageMagickConvertCommand = "/usr/bin/convert";

# InstantCommons allows wiki to use images from https://commons.wikimedia.org
$wgUseInstantCommons = false;

# Periodically send a pingback to https://www.mediawiki.org/ with basic data
# about this MediaWiki instance. The Wikimedia Foundation shares this data
# with MediaWiki developers to help guide future development efforts.
$wgPingback = false;

## If you use ImageMagick (or any other shell command) on a
## Linux server, this will need to be set to the name of an
## available UTF-8 locale. This should ideally be set to an English
## language locale so that the behaviour of C library functions will
## be consistent with typical installations. Use $wgLanguageCode to
## localise the wiki.
$wgShellLocale = "C.UTF-8";

## Set $wgCacheDirectory to a writable directory on the web server
## to make your wiki go slightly faster. The directory should not
## be publicly accessible from the web.
#$wgCacheDirectory = "$IP/cache";

# Site language code, should be one of the list in ./languages/data/Names.php
$wgLanguageCode = "en";

$wgSecretKey = "68a265061a4101d0d3dee2a06eeb734abaa6710a7dbe103838f2a26a50fc7835";

# Changing this will log out all existing sessions.
$wgAuthenticationTokenVersion = "1";

# Site upgrade key. Must be set to a string (default provided) to turn on the
# web installer while LocalSettings.php is in place
$wgUpgradeKey = "8775d57b99d672b8";

## For attaching licensing metadata to pages, and displaying an
## appropriate copyright notice / icon. GNU Free Documentation
## License and Creative Commons licenses are supported so far.
$wgRightsPage = ""; # Set to the title of a wiki page that describes your license/copyright
$wgRightsUrl = "";
$wgRightsText = "";
$wgRightsIcon = "";

# Path to the GNU diff3 utility. Used for conflict resolution.
$wgDiff3 = "/usr/bin/diff3";

## Default skin: you can change the default skin. Use the internal symbolic
## names, ie 'vector', 'monobook':
$wgDefaultSkin = "bluespicediscovery";

# End of automatically generated settings.
# Add more configuration options below.


# This is the main settings file for all BlueSpice extensions and settings
# It will include all files in "$IP/settings.d/" directory
require_once "$IP/LocalSettings.BlueSpice.php";


$wgUserMergeProtectedGroups = array();
$wgUserMergeUnmergeable = array();
$wgMetaNamespace = 'Project';
$bsgGroupRoles['*']['reader'] = false;

# Convenience for debugging
# $wgShowSQLErrors = true;
# $wgDebugDumpSql  = true;
# $wgShowExceptionDetails = true;
# $wgShowDBErrorBacktrace = true;

Edit this LocalSettings.php and set the correct values to fit your installation. This current LocalSettings.php might look like different from your MediaWiki installation, because BlueSpice comes with a separate folder for custom settings (settings.d).

Migrating the system

The system is ready to migrate.

Run the following script to start the migration:
```
php /PATH/TO/MEDIAWIKI/FOLDER/maintenance/update.php --quick
```
Now BlueSpice should be reachable.

Execute the following additional scripts:

php /PATH/TO/MEDIAWIKI/FOLDER/maintenance/rebuildall.php 
#Finally for the search index (ElasticSearch 6.x and ingest-attachment plugins must be installed) php /PATH/TO/MEDIAWIKI/FOLDER/extensions/BlueSpiceExtendedSearch/maintenance/initBackends.php --quick
php /PATH/TO/MEDIAWIKI/FOLDER/extensions/BlueSpiceExtendedSearch/maintenance/rebuildIndex.php --quick
php /PATH/TO/MEDIAWIKI/FOLDER/maintenance/runJobs.php --memory-limit=max

Your migration is complete and your BlueSpice is ready to use!

You can use your old credentials to login.

After the migration

Please check and clean up your MediaWiki:Common.js and MediaWiki:Common.css pages, and inspect if you have any legacy script pieces and style rules that might incompatible with the BlueSpice interface. By default BlueSpice does not have working content in these two pages.

Questions? Seek help from the BlueSpice help forum

PDF exclude - start

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

PDF exclude - end