Mediawiki
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:
- manually download the skins and extensions you need from the Mediawiki Skin and Extension Distributor pages and unzip them into the codebase, or
- 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';