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


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';
    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.

  3. Next, extract the BlueSpice package and place it into the /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:
      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.
      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.
     10# Further documentation for configuration settings may be found at:
     13# Protect against web entry
     14if ( !defined( 'MEDIAWIKI' ) ) {
     15	exit;
     19## Uncomment this to disable output compression
     20# $wgDisableOutputCompression = true;
     22$wgSitename = "YOUR_WIKI_NAME";
     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:
     29$wgScriptPath = "/w"; # <--- PLEASE CHECK YOUR DOCUMENTROOT
     31## The protocol and server name to use in fully-qualified URLs
     32$wgServer = "http(s)://";
     34## The URL path to static resources (images, scripts, etc.)
     35$wgResourceBasePath = $wgScriptPath;
     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" ];
     41## UPO means: this is also a user preference option
     43$wgEnableEmail = true;
     44$wgEnableUserEmail = true; # UPO
     46$wgEmergencyContact = "nomail@localhost.localdomain";
     47$wgPasswordSender = "nomail@localhost.localdomain";
     49$wgEnotifUserTalk = false; # UPO
     50$wgEnotifWatchlist = false; # UPO
     51$wgEmailAuthentication = true;
     53## Database settings
     54$wgDBtype = "mysql";
     55$wgDBserver = "YOUR_DATABASE_SERVER";
     56$wgDBname = "bluespice";
     57$wgDBuser = "bluespice";
     58$wgDBpassword = "PleaseChooseAComplexPassword";
     60# MySQL specific settings
     61$wgDBprefix = "";
     63# MySQL table options to use during installation or update
     64$wgDBTableOptions = "ENGINE=InnoDB, DEFAULT CHARSET=binary";
     66# Shared database table
     67# This has no effect unless $wgSharedDB is also set.
     68$wgSharedTables[] = "actor";
     70## Shared memory settings
     71$wgMainCacheType = CACHE_NONE;
     72$wgMemCachedServers = [];
     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";
     80# InstantCommons allows wiki to use images from
     81$wgUseInstantCommons = false;
     83# Periodically send a pingback to 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;
     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";
     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";
    101# Site language code, should be one of the list in ./languages/data/Names.php
    102$wgLanguageCode = "en";
    104$wgSecretKey = "68a265061a4101d0d3dee2a06eeb734abaa6710a7dbe103838f2a26a50fc7835";
    106# Changing this will log out all existing sessions.
    107$wgAuthenticationTokenVersion = "1";
    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";
    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 = "";
    121# Path to the GNU diff3 utility. Used for conflict resolution.
    122$wgDiff3 = "/usr/bin/diff3";
    124## Default skin: you can change the default skin. Use the internal symbolic
    125## names, ie 'vector', 'monobook':
    126$wgDefaultSkin = "bluespicediscovery";
    128# End of automatically generated settings.
    129# Add more configuration options below.
    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";
    137$wgUserMergeProtectedGroups = array();
    138$wgUserMergeUnmergeable = array();
    139$wgMetaNamespace = 'Project';
    140$bsgGroupRoles['*']['reader'] = false;
    142# Convenience for debugging
    143# $wgShowSQLErrors = true;
    144# $wgDebugDumpSql  = true;
    145# $wgShowExceptionDetails = true;
    146# $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).

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