Migrate an existing Wiki to MediaWiki 1.26wmf and Visual Editor

From Biowikifarm Metawiki
Jump to: navigation, search


MediaWiki core
This assumes a new MediaWiki version has been installed.
Parsoid and Nodejs
Make sure Parsoid is installed
Make sure Composer is installed


  • Backup the database of the wiki (e.g. using PHPMyAdmin).
  • Backup the metawiki database, as some tables, notably the user table, are shared (this is a precaution, as shared tables are not included in the update process described here).
  • Backup the entire Wiki folder to a new path (e.g. myWiki_year.month.day)

Preparing for migration

Enable Maintenance notice by uncommenting the line in LocalSettings.php:


Make Wiki read-only, add the end of LocalSettings.php, add

$wgReadOnly="Wiki is set to read-only mode because of upgrade to ...";
# $wgGroupPermissions['*']['edit'] = false;
# $wgGroupPermissions['user']['edit'] = false;
# $wgGroupPermissions['sysop']['edit'] = false;
# on MfN-Wikis additionally:
# $wgGroupPermissions['mfnUser']['edit'] = false;
# $wgGroupPermissions['mfnEditor']['edit'] = false;

Optionally: add a virtual server configuration to test the new Wiki installation as you go. You'll have to edit LocalSettings.php and chmod at least the cache folder to get this to work.

Link to the new MediaWiki core

Go to the NEW wiki and do as root:


# Main web entry point for MediaWiki
rm index.php
ln -s $MWPATH/index.php index.php
rm index.php5
ln -s $MWPATH/index.php5 index.php5
# Stub file for compatibility with older versions
rm wiki.phtml
ln -s $MWPATH/wiki.phtml wiki.phtml

# Entry point for API queries
rm api.php
ln -s $MWPATH/api.php api.php 
rm api.php5
ln -s $MWPATH/api.php5 api.php5

# PHP script to be used as 404 handler to create and stream out a
# not yet existing image thumbnail.
rm thumb_handler.php5
ln -s $MWPATH/thumb_handler.php5 thumb_handler.php5
# PHP script to stream out an image thumbnail.
rm thumb.php
ln -s $MWPATH/thumb.php thumb.php
rm thumb.php5
ln -s $MWPATH/thumb.php5 thumb.php5
# Image authorisation script
rm img_auth.php
ln -s $MWPATH/img_auth.php img_auth.php
rm img_auth.php5
ln -s $MWPATH/img_auth.php5 img_auth.php5

# Entry point for the resource loader.
rm load.php
ln -s $MWPATH/load.php load.php
rm load.php5
ln -s $MWPATH/load.php5 load.php5

# Entry point for the search API
rm opensearch_desc.php5
ln -s $MWPATH/opensearch_desc.php5 opensearch_desc.php5

# Script that redirects to the article passed in the "wpDropdown" parameter.
# This is used by the nostalgia skin for the special pages drop-down
rm redirect.php
ln -s $MWPATH/redirect.php redirect.php
rm redirect.php5
ln -s $MWPATH/redirect.php5 redirect.php5
rm redirect.phtml
ln -s $MWPATH/redirect.phtml redirect.phtml

# Directories required by Mediawiki
rm bin
ln -s $MWPATH/bin bin
rm docs
ln -s $MWPATH/docs docs
rm extensions
ln -s $MWPATH/extensions extensions
rm includes
ln -s $MWPATH/includes includes
rm languages
ln -s $MWPATH/languages languages
rm maintenance
ln -s $MWPATH/maintenance maintenance
rm resources
ln -s $MWPATH/resources resources
rm serialized
ln -s $MWPATH/serialized serialized

# Skins
rm skins
ln -s $MWPATH/skins/ skins

Additional softlinks:

rm autoload.php
ln -s $MWPATH/autoload.php autoload.php
rm Gemfile
ln -s $MWPATH/Gemfile Gemfile
rm Gemfile.lock
ln -s $MWPATH/Gemfile.lock Gemfile.lock
rm Gruntfile.js
ln -s $MWPATH/Gruntfile.js Gruntfile.js
rm package.json
ln -s $MWPATH/package.json package.json

Link to the vendor directory

ln -s $MWPATH/vendor vendor

Required for composer

Make sure composer is installed. Note that composer.json contains also a line by default to merge local composer settings (from a file named composer.local.json) with Wikipedia ’s standard settings.

rm composer.json
ln -s $MWPATH/composer.json composer.json
rm composer.lock
ln -s $MWPATH/composer.lock composer.lock

Common settings

Include the common settings in LocalSettings.php:

include_once '/var/www/MediaWikiCommonSettingsV26wmf.php';

For MfN-Wikis only: Include the new MfNMasterSettingsV26wmf instead (not both):

include_once '/var/www/MfNMasterSettingsV26wmf.php';

Run composer

Change directory to the directory containing the new wiki. Make sure the right composer.json is being used or a composer.local.json, do:

ls -l | grep composer

This should give

composer.json -> /usr/share/mediawiki26wmf/composer.json
composer.lock -> /usr/share/mediawiki26wmf/composer.lock

Then run composer:

composer update


Install the skin "naturkunde":

cd /usr/share/mediawiki26wmf5/skins/
git clone https://github.com/MfN-Berlin/mwSkinNaturkunde.git naturkunde
cd naturkunde/
sudo git submodule update --init

Install the skin "vector", if it is not already installed in /usr/share/mediawiki26wmf5/skins/, by adding the line

"mediawiki/vector-skin": "@dev"

to the "require-dev" section in composer.json. Then re-run

composer update

For some reason, you will need to add a soft link from "Vector" to "vector"

cd  /usr/share/mediawiki26wmf/skins/
ln -s /usr/share/mediawiki26wmf/skins/vector Vector


Some extensions have to be installed from Git by hand, as they are not included in composer (yet), or some use special patched versions:

cd /usr/share/mediawiki26wmf/extensions
git clone https://github.com/MfN-Berlin/mediawiki-extensions-CategoryTree.git CategoryTree
git clone https://github.com/wikimedia/mediawiki-extensions-Lockdown.git Lockdown
git clone https://github.com/wikimedia/mediawiki-extensions-NSFileRepo.git NSFileRepo

Some extensions have been commented out:

  • ContributorList
  • CreatePage
  • IdentificationTool
  • ListAllExternalLinks
  • MassEditRegex

Some extensions are not required anymore:

  • WYSIWYG (replaced by VisualEditor)


Make sure you are using the right database: check $wgDBname in LocalSettings.php

Don't upgrade shared tables, so in LocalSettings.php, AFTER the include common settings line:

$wgSharedTables     = array("xxx");

Comment out any Login-related extensions and SemanticMediaWiki extensions in Localsettings for the time being.

In the wikis directory, do

sudo -u www-data php ./maintenance/update.php  --quick --conf ./LocalSettings.php

Grant privileges select,insert,update,delete, drop index, create temporary tables to the wiki user for the new database.

If the previous step fails, the cache directory will have the wrong permissions. Make sure cache belongs to www-data.

Visual Editor

Install dependencies:

cd extensions/
git clone https://gerrit.wikimedia.org/r/p/mediawiki/extensions/UniversalLanguageSelector.git

Install the editor:

cd extensions
git clone https://gerrit.wikimedia.org/r/p/mediawiki/extensions/VisualEditor.git
cd VisualEditor
git submodule update --init

In LocalSettings.php:

# VISUAL Editor
// If this breaks, then you likely have a version mismatch - downgrade visual editor or upgrade the wiki to alpha code

// OPTIONAL: Enable VisualEditor in other namespaces
// By default, VE is only enabled in NS_MAIN
//$wgVisualEditorNamespaces[] = NS_PROJECT;

// Enable by default for everybody
$wgDefaultUserOptions['visualeditor-enable'] = 1;

// Don't allow users to disable it
$wgHiddenPrefs[] = 'visualeditor-enable';

// OPTIONAL: Enable VisualEditor's experimental code features
//$wgVisualEditorEnableExperimentalCode = true;

// Interwiki prefix to pass to the Parsoid instance - must match what you declared in the parsoid settings
// Parsoid will be called as $url/$prefix/$pagename
$wgVisualEditorParsoidPrefix = 'YOUR-PREFIX-HERE';

// Declare the Parsoid - Make sure to get the right port
$wgVisualEditorParsoidURL = 'http://localhost:8142';

Add the skin you are using to the Visual Editor skins, e.g.

$wgVisualEditorSupportedSkins[] = "naturkunde";

If you created extra namespaces for which the Visualeditor should be used, enable the editor in the extra namespaces, e.g.

$wgVisualEditorNamespaces[] = NS_PROJECT;

Private Wikis

If the Wikis are private, i.e. some pages require additional group permissions to be READ, then add the following lines to LocalSettings.php. These will allow the Parsoid to read private pages, as long as Parsoid and Wiki are on the same server:

# Allow localhost (and all the loopback IPs) and the host IPs to use the api.
# See: http://www.mediawiki.org/wiki/Talk:Parsoid#Running_Parsoid_on_a_.22private.22_wiki_-_AccessDeniedError
$local_ips[] = '';
$local_ips[] = 'xxx.xxx.xxx.xxx'; # Get this from ifconfig
if ( in_array($_SERVER['REMOTE_ADDR'], $local_ips ) ) {
  $wgGroupPermissions['*']['read'] = true;

See: Restarting Parsoid


Sematic Mediawiki

Make sure user tables are not shared. In LocalSettings.php, after including MfNMasterSettingsV26wmf5.php:

$wgSharedTables = array("xxx");

SMW is installed with composer. Run in the wiki's directory:

php /usr/local/bin/composer require mediawiki/semantic-media-wiki:~2.1 --update-with-dependencies
php maintenance/update.php --conf /var/www/<path-to-wiki>/LocalSettings.php

Semantic Forms

Add Semantic Forms in extensions:

cd /usr/share/mediawiki26wmf5/extensions/
git clone https://git.wikimedia.org/git/mediawiki/extensions/SemanticForms.git

The last version of Semantic Forms is incompatible with the installed version of semantic mediawiki. Use the 2.8 version instead:

cd SemanticForms
git checkout tags/2.8

If the "Edit with Form"-Button does not appear, just re-save the associated category.

Re-enable the wiki

  • Comment out the maintenance notice
  • Delete the permissions which make the wiki read-only.