Difference between revisions of "Mediawiki"

From Jon's Wiki
 
(15 intermediate revisions by the same user not shown)
Line 1: Line 1:
__NOTOC__
 
 
== Installation ==
 
== Installation ==
  
This assumes Ubuntu 14.04 LTS, the new Mediawiki LTS version 1.27 and a passing familiarity with [[Git]]. First, some prerequisites:
+
This assumes Ubuntu 20.04 LTS, the new Mediawiki LTS version 1.35 and a passing familiarity with [[Git]]. First, some prerequisites (see the [[PHP]] page for more about how to set up PHP so it sucks less):
  
  apt-get install git apache2 libapache2-mod-php5 php5-curl php5-mysql curl
+
  apt-get install git apache2 libapache2-mod-fcgid php7.4-curl php7.4-fpm php7.4-mysql curl
  
Now clone the core code into the target directory:
+
;NOTE: MediaWiki does not (yet) work properly with PHP 8 so we use PHP 7.4 for now.
  
git clone <nowiki>http://gerrit.wikimedia.org/r/p/mediawiki/core.git</nowiki> mediawiki
+
Now clone Mediawiki with git:
  
Next, we need to pull in the dependencies with [https://getcomposer.org/download/ PHP composer]. First install composer from the download page, then use it to pull dependencies into MediaWiki:
+
git clone <nowiki>https://phabricator.wikimedia.org/source/mediawiki.git</nowiki>
 +
 
 +
Next, we need to pull in PHP library dependencies with [https://getcomposer.org/download/ PHP composer]. First install composer from the download page, then use it to pull dependencies into MediaWiki:
  
 
  cd mediawiki
 
  cd mediawiki
  composer install
+
  composer install --no-dev
 +
 
 +
This assumes a production instance; if this is a developer instance and you need debugging tools, leave off the no-dev option.
  
 
=== Managing skins and extensions ===
 
=== Managing skins and extensions ===
  
MediaWiki has two directories for these: <tt>skins</tt> and <tt>extensions</tt>. There are several ways to manage them, listed here with increasing complexity:
+
MediaWiki has two directories for these: <tt>skins</tt> and <tt>extensions</tt>. There are several ways to manage them, but to keep things simple either:
  
# manually download the skins and extensions you need from the Mediawiki [https://www.mediawiki.org/wiki/Special:SkinDistributor Skin] and [https://www.mediawiki.org/wiki/Special:ExtensionDistributor Extension] Distributor pages and unzip them into the codebase,
+
# manually download the skins and extensions you need from the Mediawiki [https://www.mediawiki.org/wiki/Special:SkinDistributor Skin] and [https://www.mediawiki.org/wiki/Special:ExtensionDistributor Extension] Distributor pages and unzip them into the codebase, or
# manage each skin and extension using a git clone in the appropriate place in the codebase, or
+
# manage skins and extensions using git submodules, sourced from the upstream git repositories.
# manage the git repositories of all skins and extensions externally, and use git submodule update to fetch the ones you need, and create symbolic links to the directories in the codebase to enable them.
 
  
Let's do things the hard way. Clone the extensions and skins root repositories, and set up the git submodules:
+
Let's do the second way because it's easier to automate later, and some formerly built-in skins and extensions are now set up this way. Of these, you'll need the default Vector skin right off the bat, and you might like to switch to the Timeless skin, which is responsive and a lot more mobile-friendly:
  
  git clone <nowiki>https://gerrit.wikimedia.org/r/mediawiki/skins</nowiki> skins-available
+
  git submodule update --init --recursive skins/Vector skins/Timeless
cd skins-available
 
git submodule init
 
cd ..
 
git clone <nowiki>https://gerrit.wikimedia.org/r/mediawiki/extensions</nowiki> extensions-available
 
cd extensions-available
 
git submodule init
 
cd ..
 
  
You'll need the Vector skin right off the bat:
+
Now when we want an extension, say the ''Cite'' extension, we add the git submodule:
  
cd skins-available
+
  git submodule add -b REL1_35 <nowiki>https://gerrit.wikimedia.org/r/mediawiki/extensions/Cite</nowiki> extensions/Cite
  git submodule update --recursive Vector
+
  git submodule update --init --recursive extensions/Cite
cd ../mediawiki/skins
 
  ln -s ../../skins-available/Vector
 
  
Now when we want an extension, say the ''Cite'' extension, we can:
+
Enabling the skins and extensions requires editing the <tt>LocalSettings.php</tt> file, for example:
  
  cd extensions-available
+
  $wgDefaultSkin = 'Timeless';
  git submodule update --recursive Cite
+
  wfLoadSkin('Timeless');
cd ../mediawiki/extensions
+
  wfLoadExtension('Cite');
  ln -s ../../extensions-available/Cite
 
  
You should now be able to point Apache or nginx at the <tt>mediawiki</tt> directory and install it using the browser (you may need to set up a MySQL database and/or user).
+
You should now be able to point Apache at the <tt>mediawiki</tt> directory and install it using the browser; you will probably need to set up a [[PostgreSQL]] or MySQL database and user first.
  
 
== Visual Editor ==
 
== Visual Editor ==
  
=== Install Parsoid ===
+
This relies on Parsoid, which used to be a separate Node.js REST service you had to install; in 2019 it was rewritten in PHP and is now bundled since version 1.35 of MediaWiki.
 
 
[https://www.mediawiki.org/wiki/Parsoid/Setup Parsoid] is a small Node.js REST service that parses between MediaWiki syntax and HTML DOM. Add the apt repository:
 
 
 
apt-key advanced --keyserver keys.gnupg.net --recv-keys 90E9F83F22250DD7
 
<nowiki>apt-add-repository 'deb https://releases.wikimedia.org/debian jessie-mediawiki main'</nowiki>
 
apt-get update
 
 
 
Then install and configure Parsoid:
 
 
 
apt-get install parsoid
 
vi /etc/mediawiki/parsoid/config.yaml  ''# change URL to point to installed api.php''
 
 
 
Example config.yaml looks like:
 
 
 
worker_heartbeat_timeout: 300000
 
logging:
 
  level: info
 
services:
 
  - module: ../src/lib/index.js
 
    entrypoint: apiServiceWorker
 
    conf:
 
      useSelser: true
 
      mwApis:
 
      -
 
        uri: <nowiki>'https://your.wiki.nz/w/api.php'</nowiki>
 
        domain: 'your.wiki.nz'
 
  
 
=== Install the required MediaWiki extensions ===
 
=== Install the required MediaWiki extensions ===
  
Install Visual Editor and its dependent extension (UniversalLanguageSelector) into the Mediawiki <tt>extensions</tt> directory:
+
Install the Visual Editor extension and its dependent extension (UniversalLanguageSelector):
  
cd extensions-available
+
  git submodule add -b REL1_35 <nowiki>https://gerrit.wikimedia.org/r/mediawiki/extensions/VisualEditor</nowiki> extensions/VisualEditor
  git submodule update --recursive VisualEditor UniversalLanguageSelector
+
  git submodule add -b REL1_35 <nowiki>https://gerrit.wikimedia.org/r/mediawiki/extensions/UniversalLanguageSelector</nowiki> extensions/UniversalLanguageSelector
cd ../mediawiki/extensions
+
  git submodule update --init --recursive extensions/VisualEditor extensions/UniversalLanguageSelector
  ln -s ../../extensions-available/VisualEditor
 
  ln -s ../../extensions-available/UniversalLanguageSelector
 
  
 
Then edit <tt>LocalSettings.php</tt> and add this at the bottom:
 
Then edit <tt>LocalSettings.php</tt> and add this at the bottom:
Line 97: Line 61:
 
  # VisualEditor extension configuration
 
  # VisualEditor extension configuration
 
  $wgDefaultUserOptions['visualeditor-enable'] = 1;
 
  $wgDefaultUserOptions['visualeditor-enable'] = 1;
  $wgDefaultUserOptions['visualeditor-editor'] = "visualeditor";
+
  $wgDefaultUserOptions['visualeditor-editor'] = 'visualeditor';
 
  $wgSessionsInObjectCache = true;
 
  $wgSessionsInObjectCache = true;
 
  $wgVisualEditorAvailableNamespaces = [
 
  $wgVisualEditorAvailableNamespaces = [
Line 103: Line 67:
 
   NS_USER => true,
 
   NS_USER => true,
 
   NS_TEMPLATE => false,
 
   NS_TEMPLATE => false,
   "_merge_strategy" => "array_plus",
+
   '_merge_strategy' => 'array_plus',
];
 
 
# VisualEditor connection to the parsoid service
 
$wgVirtualRestConfig['modules']['parsoid'] = [
 
  'url' => <nowiki>'http://localhost:8142',</nowiki>
 
  'domain' => 'your.wiki.nz',
 
  'forwardCookies' => true,
 
 
  ];
 
  ];
  
Line 117: Line 74:
 
=== PHP opcache ===
 
=== PHP opcache ===
  
Like any PHP application, use the opcache. If your PHP version is < 5.5 install <tt>php5-xcache</tt>, otherwise enable the built-in [http://php.net/manual/en/opcache.installation.php opcache] by adding this in <tt>php.ini</tt>:
+
Like any PHP application, use the opcache. If not already enabled, enable the built-in [http://php.net/manual/en/opcache.installation.php opcache] by adding something like this in <tt>php.ini</tt>:
  
 
  [opcache]
 
  [opcache]
Line 129: Line 86:
 
  opcache.revalidate_freq=0
 
  opcache.revalidate_freq=0
 
  opcache.fast_shutdown=0
 
  opcache.fast_shutdown=0
 +
 +
=== APCu ===
 +
 +
This is simpler than using Memcache and just as effective.
 +
 +
apt install php-apcu
 +
 +
Then add this to LocalSettings.php:
 +
 +
$wgMainCacheType = CACHE_ACCEL;
 +
$wgSessionCacheType = CACHE_DB;
  
 
=== MediaWiki file cache ===
 
=== MediaWiki file cache ===
  
Use the [https://www.mediawiki.org/wiki/Manual:File_cache#Operation_and_usage file cache], Luke. It's simple but effective. In LocalSettings.php:
+
Use the [https://www.mediawiki.org/wiki/Manual:File_cache#Operation_and_usage file cache], Luke. It's simple but effective for anonymous users. In <tt>LocalSettings.php</tt>:
  
 
  $wgUseFileCache = true;
 
  $wgUseFileCache = true;
Line 142: Line 110:
 
  sudo mkdir -p /var/cache/mediawiki
 
  sudo mkdir -p /var/cache/mediawiki
 
  sudo chown www-data:www-data /var/cache/mediawiki
 
  sudo chown www-data:www-data /var/cache/mediawiki
 +
 +
== Upgrading ==
 +
 +
Check the [https://www.mediawiki.org/wiki/Version_lifecycle Version lifecycle] page to see which versions are current, inspect your wiki's [[Special:Version]] page for version and dependency details. See also the documentation for [https://www.mediawiki.org/wiki/Manual:Upgrading/en Upgrading MediaWiki].
 +
 +
Whenever the base code is updated, we need to make sure that PHP dependencies, skins, extensions and the database schema are all updated too. It looks a bit like this:
 +
 +
composer update --no-dev
 +
git submodule update --init --recursive
 +
sudo -u www-data /usr/bin/php maintenance/update.php
 +
# (look for any new updateXXX.php commands in the maintenance directory)
 +
 +
At present, <tt>npm install</tt> is only required to install grunt-based JavaScript dependencies for developers and testers, and is not required in production.
 +
 +
Given that Wikipedia itself runs on this code, you can bet upgrades have been tested up the waazoo, so this runs very reliably. I recently upgraded a wiki from 1.19 to latest 1.35 LTS by repeating this procedure after merging each LTS branch in turn—that's 1.23, 1.27 and 1.31—as intermediate steps. It's prudent to do each LTS bump separately like this  because configuration details and deployment steps can change. For instance, 1.23 introduced PHP composer and 1.27 moved extensions and skins to git submodules.
 +
 +
== Troubleshooting ==
 +
 +
Having 'file:' in your $wgUrlProtocols is not just bad, it will clobber all your <tt><nowiki>[[File:whatever.jpg]]</nowiki></tt> images.
 +
 +
If you're using or have moved to MySQL or MariaDB, remove any PostgreSQL schema settings from <tt>LocalSettings.php</tt> otherwise the update scripts get terribly confused:
 +
 +
# remove this:
 +
$wgDBmwschema = 'mediawiki';

Latest revision as of 22:42, 7 September 2021

Installation

This assumes Ubuntu 20.04 LTS, the new Mediawiki LTS version 1.35 and a passing familiarity with Git. First, some prerequisites (see the PHP page for more about how to set up PHP so it sucks less):

apt-get install git apache2 libapache2-mod-fcgid php7.4-curl php7.4-fpm php7.4-mysql curl
NOTE
MediaWiki does not (yet) work properly with PHP 8 so we use PHP 7.4 for now.

Now clone Mediawiki with git:

git clone https://phabricator.wikimedia.org/source/mediawiki.git

Next, we need to pull in PHP library dependencies with PHP composer. First install composer from the download page, then use it to pull dependencies into MediaWiki:

cd mediawiki
composer install --no-dev

This assumes a production instance; if this is a developer instance and you need debugging tools, leave off the no-dev option.

Managing skins and extensions

MediaWiki has two directories for these: skins and extensions. There are several ways to manage them, but to keep things simple either:

  1. manually download the skins and extensions you need from the Mediawiki Skin and Extension Distributor pages and unzip them into the codebase, or
  2. manage skins and extensions using git submodules, sourced from the upstream git repositories.

Let's do the second way because it's easier to automate later, and some formerly built-in skins and extensions are now set up this way. Of these, you'll need the default Vector skin right off the bat, and you might like to switch to the Timeless skin, which is responsive and a lot more mobile-friendly:

git submodule update --init --recursive skins/Vector skins/Timeless

Now when we want an extension, say the Cite extension, we add the git submodule:

git submodule add -b REL1_35 https://gerrit.wikimedia.org/r/mediawiki/extensions/Cite extensions/Cite
git submodule update --init --recursive extensions/Cite

Enabling the skins and extensions requires editing the LocalSettings.php file, for example:

$wgDefaultSkin = 'Timeless';
wfLoadSkin('Timeless');
wfLoadExtension('Cite');

You should now be able to point Apache at the mediawiki directory and install it using the browser; you will probably need to set up a PostgreSQL or MySQL database and user first.

Visual Editor

This relies on Parsoid, which used to be a separate Node.js REST service you had to install; in 2019 it was rewritten in PHP and is now bundled since version 1.35 of MediaWiki.

Install the required MediaWiki extensions

Install the Visual Editor extension and its dependent extension (UniversalLanguageSelector):

git submodule add -b REL1_35 https://gerrit.wikimedia.org/r/mediawiki/extensions/VisualEditor extensions/VisualEditor
git submodule add -b REL1_35 https://gerrit.wikimedia.org/r/mediawiki/extensions/UniversalLanguageSelector extensions/UniversalLanguageSelector
git submodule update --init --recursive extensions/VisualEditor extensions/UniversalLanguageSelector

Then edit LocalSettings.php and add this at the bottom:

wfLoadExtension('UniversalLanguageSelector');
wfLoadExtension('VisualEditor.php');

# VisualEditor extension configuration
$wgDefaultUserOptions['visualeditor-enable'] = 1;
$wgDefaultUserOptions['visualeditor-editor'] = 'visualeditor';
$wgSessionsInObjectCache = true;
$wgVisualEditorAvailableNamespaces = [
  NS_MAIN => true,
  NS_USER => true,
  NS_TEMPLATE => false,
  '_merge_strategy' => 'array_plus',
];

Caching

PHP opcache

Like any PHP application, use the opcache. If not already enabled, enable the built-in opcache by adding something like this in php.ini:

[opcache]
opcache.enable=1
opcache.enable_cli=1
opcache.memory_consumption=128
opcache.interned_strings_buffer=8
opcache.max_accelerated_files=4000
opcache.use_cwd=1
opcache.validate_timestamps=1
opcache.revalidate_freq=0
opcache.fast_shutdown=0

APCu

This is simpler than using Memcache and just as effective.

apt install php-apcu

Then add this to LocalSettings.php:

$wgMainCacheType = CACHE_ACCEL;
$wgSessionCacheType = CACHE_DB;

MediaWiki file cache

Use the file cache, Luke. It's simple but effective for anonymous users. In LocalSettings.php:

$wgUseFileCache = true;
$wgFileCacheDirectory = "/var/cache/mediawiki";
$wgShowIPinHeader = false; 

And create the appropriate cache directory:

sudo mkdir -p /var/cache/mediawiki
sudo chown www-data:www-data /var/cache/mediawiki

Upgrading

Check the Version lifecycle page to see which versions are current, inspect your wiki's Special:Version page for version and dependency details. See also the documentation for Upgrading MediaWiki.

Whenever the base code is updated, we need to make sure that PHP dependencies, skins, extensions and the database schema are all updated too. It looks a bit like this:

composer update --no-dev
git submodule update --init --recursive
sudo -u www-data /usr/bin/php maintenance/update.php
# (look for any new updateXXX.php commands in the maintenance directory)

At present, npm install is only required to install grunt-based JavaScript dependencies for developers and testers, and is not required in production.

Given that Wikipedia itself runs on this code, you can bet upgrades have been tested up the waazoo, so this runs very reliably. I recently upgraded a wiki from 1.19 to latest 1.35 LTS by repeating this procedure after merging each LTS branch in turn—that's 1.23, 1.27 and 1.31—as intermediate steps. It's prudent to do each LTS bump separately like this because configuration details and deployment steps can change. For instance, 1.23 introduced PHP composer and 1.27 moved extensions and skins to git submodules.

Troubleshooting

Having 'file:' in your $wgUrlProtocols is not just bad, it will clobber all your [[File:whatever.jpg]] images.

If you're using or have moved to MySQL or MariaDB, remove any PostgreSQL schema settings from LocalSettings.php otherwise the update scripts get terribly confused:

# remove this:
$wgDBmwschema = 'mediawiki';