Migration from MediaWiki to BlueSpice

Before you start[edit | edit source]

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 is based on MediaWiki 1.35.x

Backup[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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

  1<?php
  2# This file was automatically generated by the MediaWiki 1.35.3
  3# installer. If you make manual changes, please keep track in case you
  4# need to recreate them later.
  5#
  6# See includes/DefaultSettings.php for all configurable settings
  7# and their default values, but don't forget to make changes in _this_
  8# file, not there.
  9#
 10# Further documentation for configuration settings may be found at:
 11# https://www.mediawiki.org/wiki/Manual:Configuration_settings
 12
 13# Protect against web entry
 14if ( !defined( 'MEDIAWIKI' ) ) {
 15	exit;
 16}
 17
 18
 19## Uncomment this to disable output compression
 20# $wgDisableOutputCompression = true;
 21
 22$wgSitename = "YOUR_WIKI_NAME";
 23
 24## The URL base path to the directory containing the wiki;
 25## defaults for all runtime URL paths are based off of this.
 26## For more information on customizing the URLs
 27## (like /w/index.php/Page_title to /wiki/Page_title) please see:
 28## https://www.mediawiki.org/wiki/Manual:Short_URL
 29$wgScriptPath = "/w"; # <--- PLEASE CHECK YOUR DOCUMENTROOT
 30
 31## The protocol and server name to use in fully-qualified URLs
 32$wgServer = "http(s)://your-domain.ltd";
 33
 34## The URL path to static resources (images, scripts, etc.)
 35$wgResourceBasePath = $wgScriptPath;
 36
 37## The URL paths to the logo.  Make sure you change this from the default,
 38## or else you'll overwrite your logo when you upgrade!
 39$wgLogos = [ '1x' => "$wgResourceBasePath/resources/assets/wiki.png" ];
 40
 41## UPO means: this is also a user preference option
 42
 43$wgEnableEmail = true;
 44$wgEnableUserEmail = true; # UPO
 45
 46$wgEmergencyContact = "nomail@localhost.localdomain";
 47$wgPasswordSender = "nomail@localhost.localdomain";
 48
 49$wgEnotifUserTalk = false; # UPO
 50$wgEnotifWatchlist = false; # UPO
 51$wgEmailAuthentication = true;
 52
 53## Database settings
 54$wgDBtype = "mysql";
 55$wgDBserver = "YOUR_DATABASE_SERVER";
 56$wgDBname = "bluespice";
 57$wgDBuser = "bluespice";
 58$wgDBpassword = "PleaseChooseAComplexPassword";
 59
 60# MySQL specific settings
 61$wgDBprefix = "";
 62
 63# MySQL table options to use during installation or update
 64$wgDBTableOptions = "ENGINE=InnoDB, DEFAULT CHARSET=binary";
 65
 66# Shared database table
 67# This has no effect unless $wgSharedDB is also set.
 68$wgSharedTables[] = "actor";
 69
 70## Shared memory settings
 71$wgMainCacheType = CACHE_NONE;
 72$wgMemCachedServers = [];
 73
 74## To enable image uploads, make sure the 'images' directory
 75## is writable, then set this to true:
 76$wgEnableUploads = false;
 77$wgUseImageMagick = true;
 78$wgImageMagickConvertCommand = "/usr/bin/convert";
 79
 80# InstantCommons allows wiki to use images from https://commons.wikimedia.org
 81$wgUseInstantCommons = false;
 82
 83# Periodically send a pingback to https://www.mediawiki.org/ with basic data
 84# about this MediaWiki instance. The Wikimedia Foundation shares this data
 85# with MediaWiki developers to help guide future development efforts.
 86$wgPingback = false;
 87
 88## If you use ImageMagick (or any other shell command) on a
 89## Linux server, this will need to be set to the name of an
 90## available UTF-8 locale. This should ideally be set to an English
 91## language locale so that the behaviour of C library functions will
 92## be consistent with typical installations. Use $wgLanguageCode to
 93## localise the wiki.
 94$wgShellLocale = "C.UTF-8";
 95
 96## Set $wgCacheDirectory to a writable directory on the web server
 97## to make your wiki go slightly faster. The directory should not
 98## be publicly accessible from the web.
 99#$wgCacheDirectory = "$IP/cache";
100
101# Site language code, should be one of the list in ./languages/data/Names.php
102$wgLanguageCode = "en";
103
104$wgSecretKey = "68a265061a4101d0d3dee2a06eeb734abaa6710a7dbe103838f2a26a50fc7835";
105
106# Changing this will log out all existing sessions.
107$wgAuthenticationTokenVersion = "1";
108
109# Site upgrade key. Must be set to a string (default provided) to turn on the
110# web installer while LocalSettings.php is in place
111$wgUpgradeKey = "8775d57b99d672b8";
112
113## For attaching licensing metadata to pages, and displaying an
114## appropriate copyright notice / icon. GNU Free Documentation
115## License and Creative Commons licenses are supported so far.
116$wgRightsPage = ""; # Set to the title of a wiki page that describes your license/copyright
117$wgRightsUrl = "";
118$wgRightsText = "";
119$wgRightsIcon = "";
120
121# Path to the GNU diff3 utility. Used for conflict resolution.
122$wgDiff3 = "/usr/bin/diff3";
123
124## Default skin: you can change the default skin. Use the internal symbolic
125## names, ie 'vector', 'monobook':
126$wgDefaultSkin = "bluespicediscovery";
127
128# End of automatically generated settings.
129# Add more configuration options below.
130
131
132# This is the main settings file for all BlueSpice extensions and settings
133# It will include all files in "$IP/settings.d/" directory
134require_once "$IP/LocalSettings.BlueSpice.php";
135
136
137$wgUserMergeProtectedGroups = array();
138$wgUserMergeUnmergeable = array();
139$wgMetaNamespace = 'Project';
140$bsgGroupRoles['*']['reader'] = false;
141
142# Convenience for debugging
143# $wgShowSQLErrors = true;
144# $wgDebugDumpSql  = true;
145# $wgShowExceptionDetails = true;
146# $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[edit | edit source]

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.

Questions? Visit the BlueSpice help forum on sourceforge.net.