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 is based on MediaWiki 1.35.x (BlueSpice 4 has not yet been released)

Backup

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

1. Create a directory to store the backup:

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

   
   
2. Create the database dump:

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

   
   
3. 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.

1. Create a MySQL/MariaDB user via MySQL CLI:

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

   
   
2. Create a database for BlueSpice via MySQL CLI:

   CREATE DATABASE bluespice;
   

   
   
3. 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

1. 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.
2. 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/
   

   
   
3. Next, extract the BlueSpice package and place it into the /PATH/TO/MEDIAWIKI/FOLDER/

   cd /PATH/TO/MEDIAWIKI/FOLDER/
   

   
   
4. Copy the images folder from the backup to the /PATH/TO/MEDIAWIKI/FOLDER/ :

   cp -Rf /opt/mediawiki-migration-backup/images
   

5. Set the correct permissions based on your operating system to the folder /PATH/TO/MEDIAWIKI/FOLDER/ .

Configuration settings

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

   "$wgResourceBasePath/resources/assets/wiki.png" ];
   
   ## in the following, UPO means: this setting also exists as 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 = "bluespicecalumma";
   
   # 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;
   

2. 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).
   

Migrate the system

The system is ready to migrate.

1. Run the following script to start the migration:

   php /PATH/TO/MEDIAWIKI/FOLDER/maintenance/update.php --quick
   

   Now BlueSpice should be reachable.
2. Finally 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.