Intranet/Intranet Installation

This page documents installing MediaWiki, some basic customisation and an upgrade process. This process builds upon Intranet Reference Build Ubuntu

Install from Git
Use symlinks to keep code and data separate
Database backup method
Simple, safe upgrades
Auto created users matching web server authentication scheme
Visual Editor

Documentation test log
Date	OS	MW version	Notes
20 Jul 2022	Ubuntu "Focal" (20.04)	1.39.0-wmf.21	No issues
02 Jun 2023	Ubuntu "Jammy" (22.04)	1.40.0-wmf.27	No issues
24 Jul 2023	Ubuntu "Jammy" (22.04)	1.41.0-wmf.18	No issues
17 Jan 2024	Ubuntu "Jammy" (22.04)	1.42.0-wmf.14	Old code was still being referenced, rather than honouring the symlink. The homepage would not display. This needed $wgShowExceptionDetails = true; in LocalSettings.php to diagnose, which was alluded to in the error message. The problem was obvious because the paths were shown. In future, remove or move older code branches away.
06 Aug 2024	Ubuntu "Jammy" (22.04)	1.43.0-wmf-17	Work in progress. I got errors relating to a lack of an ipblocks table, which seems to have been deprecated around 1.42 but something is still looking for it. I was able to get my wiki running again by re-creating a blank ipblocks table from a definition I found in the previous version's maintenance folder. See notes below

In this article, locally maintained extensions are those that I have downloaded or checked out with git and loaded into MediaWiki myself. This is the code that I store under local-extensions<name_of_extension> in this article. The majority of extensions that I use are those that are included with the MediaWiki software itself.

Initial MediaWiki Installation

Settings

This table shows the settings I have chosen. You can pick your own but make sure you are consistent!

Setting	Meaning
hostname	Name of the host running Mediawiki - here wiki.example.co.uk
(webroot)	Directory where the web server defaults to storing pages - /var/www/html/
mediawiki	Location (under webroot) for Mediawiki code Maintained as a symlink
/wiki	Short URL for wiki articles (matches Wikipedia)
/w	Short URL for API access (matches Wikipedia)
mediawiki	Name of the database in MySQL/MariaDB
mediawiki	Username to access the database
random_string	Password for wiki database user. Generate with something like $ md5sum a_randomly_chosen_file or use a password manager to create one

Filesystem layout

The directory structure you end up with is outlined in the following table. We use symlinks to switch between versions whilst keeping the webserver configuration constant:

Base path	Directory/File	Purpose
/var/www/html	./mediawiki/ -> <version>	Symlink to code
	./local-extensions/	Checked out extensions in subdirectories of this directory
	./logo.gif	Logofile
	./LocalSettings.php	Real LocalSettings.php file
	./mediawiki/LocalSettings.php -> .LocalSettings.php	Symlink to LocalSettings file
	./<version>	Checked out copy of the code

Pre requisites

Install PHP modules

# apt install php-mbstring php-xml php-mysql php-apcu php-intl
# systemctl restart apache2

Install git

# apt install git

Imagemagick (for image thumbnails)^[1]

# apt install imagemagick

Setup database. Set a suitable password (line 4 below) 'random_string'. The password will be put in the LocalSettings.php that will be generated later in this process but keep a note of it.

# mysql -u root -p

MariaDB [(none)]> create database mediawiki;
MariaDB [(none)]> create user 'mediawiki'@'localhost' identified by 'random_string';
MariaDB [(none)]> grant all privileges on mediawiki . * to 'mediawiki'@'localhost';
MariaDB [(none)]> flush privileges;
MariaDB [(none)]> \q

Install MediaWiki software

To help you decide what version to run, check the official release status ^[2] , check what version Wikipedia is using ^[3] look at change logs for development status ^[4]

MediaWiki software

# cd /var/www/html

Find a version using git ls-remote:

# git ls-remote --heads https://gerrit.wikimedia.org/r/mediawiki/core
....
f5a748cda402d61641e6da72a3544f6005c0409f        refs/heads/wmf/1.31.0-wmf.5
433022fdf2b2b0b82fdedec5623462af739d8629        refs/heads/wmf/1.31.0-wmf.6 <---- Chosen version
cd3ceb4540f735de003a771d134ce427d230bdf5        refs/heads/wmf/1.31.0-wmf.7

Clone the chosen version

# git clone --depth=1 --single-branch --branch wmf/1.31.0-wmf.6 https://gerrit.wikimedia.org/r/mediawiki/core.git 1.31.0-wmf.6

Update the submodules and Composer managed libraries

# cd 1.31.0-wmf.6
# git submodule update --init --recursive

Web based Installer

This is just the initial install. We will change the URL to access MW later.

# cd /var/www/html
# ln -s mediawiki-1.29.2 mediawiki    .... downloaded release ....
.... or ....
# ln -s 1.31.0-wmf.6 mediawiki        .... downloaded using git ....

Browse to https://wiki.example.co.uk/mediawiki and the first run wizard will start. Keep the settings to a minimum and do not enable any modules. At the end, download the provided LocalSettings.php file and upload it to the web server's filesystem at /var/www/html. Create the symlink to it from the wiki folder.

# cd /var/www/html/mediawiki
# ln -s /var/www/html/LocalSettings.php

Disable the Minerva Neue skin in LocalSettings.php to get the wiki to load until it is no longer dependent on MobileFrontend^[5]. Edit LocalSettings.php and towards the end put a # in front of wfLoadSkin( 'MinervaNeue' );

Move images out

# mkdir /var/www/html/images
# chown www-data:www-data /var/www/html/images
# cd /var/www/html/mediawiki
# rm -Rvf images
# ln -s /var/www/html/images

Short URLs

Add two Alias statements outside of the virtual host definition. These are the final short URLs:

# /etc/apache2/sites-available/local.conf

ServerName wiki.example.co.uk

<VirtualHost _default_:443>
...
</VirtualHost>

Alias /wiki /var/www/html/mediawiki/index.php 
Alias /w    /var/www/html/mediawiki

Change $wgScriptPath and add $wgArticlePath in LocalSettings.php to match the short URL:
```
...
$wgScriptPath  = "/w";      
$wgArticlePath = '/wiki/$1';
...
```

# systemctl restart apache2

Browse to https://wiki.example.co.uk and check https://wiki.example.co.uk/wiki/Special:Version to make sure it all looks OK.

Logo

Copy a logo file into /var/www/html and rename it to logo.gif (or.png or whatever) and reference it in LocalSettings.php
```
$wgLogo = "/logo.gif";
```

Cache

This enables a simple filesystem based cache which will help speed up page load times. Create a cache directory for the wiki to use:
```
# mkdir /var/cache/mediawiki
# chown www-data:www-data /var/cache/mediawiki
```

Add this to LocalSettings.php:

$wgCacheDirectory= "/var/cache/mediawiki";

Cronjob for runJobs

Add the following to LocalSettings.php to disable runjobs^[6]
```
# Run jobs via cron
$wgJobRunRate = 0;
```

Add this to crontab (change the timings to suit - this example runs every seven minutes)

# crontab -u www-data -e
2-59/7 * * * * /usr/bin/php /var/www/html/mediawiki/maintenance/runJobs.php > /var/log/mediawiki/runJobs.log 2>&1

or for MW version 1.40+

2-59/7 * * * * /usr/bin/php /var/www/html/mediawiki/maintenance/run.php runJobs.php > /var/log/mediawiki/runJobs.log 2>&1

Create a directory for the log

# mkdir /var/log/mediawiki
# chown www-data:www-data /var/log/mediawiki

When you are happy that runJobs is working correctly then either use something like logrotate to handle the ever growing log file or disable it by removing the redirection in crontab.

Enable wikieditor^[7]

Edit LocalSettings.php and add this at the bottom:

# End of automatically generated settings.
# Add more configuration options below.

wfLoadExtension( 'WikiEditor' );

# WikiEditor
$wgDefaultUserOptions['usebetatoolbar']     = 1;
$wgDefaultUserOptions['usebetatoolbar-cgd'] = 1;
$wgDefaultUserOptions['wikieditor-preview'] = 1;
$wgDefaultUserOptions['wikieditor-publish'] = 1;
# WikiEditor

Try editing a page. if the editor does not appear then hold down shift and press the reload button in your browser to clear the cached page.

Authentication and authorisation

Auth_remoteuser^[8]

The reference build that this article is part of sets REMOTE_USER via Kerberos.

Create local-extensions area. This avoids our locally maintained extensions from being overwritten by upgrades
```
# mkdir /var/www/html/local-extensions
# cd /var/www/html/local-extensions
```

Get the latest code

# git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/Auth_remoteuser

Enable and configure the extension. This extension appears to break CirrusSearch and isn't needed when running maintenance scripts, so it is conditionally disabled. Setting $wgExtensionDirectory and then resetting it back to default enables the wfLoadExtension() call to work.

# Locally managed extensions
if ( !$wgCommandLineMode ) {
    $wgExtensionDirectory = '/var/www/html/local-extensions';
    wfLoadExtension( 'Auth_remoteuser' );
    $wgExtensionDirectory = '$IP/extensions';
}

# Auth_remoteuser
$wgGroupPermissions['*']['createaccount']     = false;
$wgGroupPermissions['*']['autocreateaccount'] = true;

# This allows switching to "Admin"
$wgAuthRemoteuserAllowUserSwitch         = true;
$wgAuthRemoteuserRemoveAuthPagesAndLinks = false;
# Auth_remoteuser

You should now be logged into an automatically created wiki account based on your AD username when you access the wiki.

Visual Editor ^[9]

The Visual Editor extension. PHP-Curl is required for VE to work at all. Installing curl itself is optional but useful for testing from the local command line.

# apt install php-curl curl

Enable the Extension and Parsoid by adding these lines towards the bottom of LocalSettings.php but before the auth_remoteuser configuration.

wfLoadExtension( 'VisualEditor' );
wfLoadExtension( 'Parsoid', 'vendor/wikimedia/parsoid/extension.json' );

# Visual Editor
$wgDefaultUserOptions['visualeditor-enable'] = 1;
# Visual Editor

Add AllowEncodedSlashes to the Apache virtualhost configuration and reload Apache. This enables editing of subpages:

# /etc/apache2/sites-available/local.conf

<VirtualHost _default_:443>
...
    AllowEncodedSlashes NoDecode
...
</VirtualHost>

Visual Editor will make a connection from the system's IP address and not its loopback address to the REST API ie /w/api.php. If authentication is in use in a <Location /> block as is documented here, then this will cause a 401 error when trying to edit. Add the additional RequireAll block, replacing 10.10.10.10 with the real IP address of the system, this will allow that IP address to connect without authentication:

# /etc/apache2/sites-available/local.conf
...
<Location />
...
    <RequireAny>

...
        <RequireAll>
            Require ip 10.10.10.10
        </RequireAll>
...

This is not a very elegant solution and I will look for a better one Gerdesj (talk) 11:00, 21 May 2021 (UTC)[reply]

Database Backups

This script is really designed for ad hoc use because you will be backing up the entire system anyway
```
# mkdir /var/lib/mediawiki-backups
```
Create backup script in /usr/local/bin/mediawiki-backup.sh

#!/bin/sh

L="/var/www/html/LocalSettings.php"
B="/var/lib/mediawiki-backups"

D="`cat ${L} | grep DBname     | cut -d '"' -f 2`"
U="`cat ${L} | grep DBuser     | cut -d '"' -f 2`"
P="`cat ${L} | grep DBpassword | cut -d '"' -f 2`"
F="${D}-`date +%F-%T`"

mysqldump --databases ${D} -u${U} -p${P} --add-drop-table > ${B}/${F}.sql

Make the script executable

# chmod +x /usr/local/bin/mediawiki-backup.sh

Run it and verify that you have a database backup file. There should be a file named wiki-<datestamp>.sql - check its contents to verify that it really is a backup

# mediawiki-backup.sh
# ls -l /var/lib/mediawiki-backups/
-rw-r--r-- 1 root root 1981071 Nov 16 11:40 wiki-2017-11-16.sql
# less /var/lib/mediawiki-backups/wiki-2017-11-16.sql
-- MySQL dump 10.15  Distrib 10.0.31-MariaDB, for debian-linux-gnu (x86_64)
--
-- Host: localhost    Database: wiki
-- ------------------------------------------------------
-- Server version       10.0.31-MariaDB-0ubuntu0.16.04.2

/*!40101 SET @OLD_CHARACTER_SET_CLIENT=@@CHARACTER_SET_CLIENT */;
/*!40101 SET @OLD_CHARACTER_SET_RESULTS=@@CHARACTER_SET_RESULTS */;
/*!40101 SET @OLD_COLLATION_CONNECTION=@@COLLATION_CONNECTION */;
/*!40101 SET NAMES utf8mb4 */
....

Updating

It is possible to avoid the downtime associated with snapshots and waiting for the code to download but this process is designed to be as safe as possible.

Before updating

Perform pre-upgrade change control process
Check backups
Shutdown the system and take a snapshot
Start the system

Update the code

Do the MediaWiki installation section of this article to get the new code, for example:

# cd /var/www/html
# git ls-remote --heads https://gerrit.wikimedia.org/r/mediawiki/core

... pick a version ...

# git clone --depth=1 --single-branch --branch wmf/1.43.0-wmf.22 https://gerrit.wikimedia.org/r/mediawiki/core.git 1.43.0-wmf.22
# cd 1.43.0-wmf.22
# git submodule update --init --recursive

Create symlinks

# cd /var/www/html/1.43.0-wmf.22   .... check the version carefully
# rm -Rv ./images
# ln -s /var/www/html/images
# ln -s /var/www/html/LocalSettings.php

Switch to the new code

Stop the web server (systemctl stop apache2)
Make the wiki read-only. Put this at the bottom of LocalSettings.php:

$wgReadOnly = 'This wiki is currently being upgraded.';

Start Apache (systemctl start apache2)
Remove and re-point the symlink.

# cd /var/www/html
# rm mediawiki
# ln -s 1.43.0-wmf.22 mediawiki

Make the wiki read/write. Delete or comment out $wgReadOnly in LocalSettings.php

# $wgReadOnly = 'This wiki is currently being upgraded.';

Update local extensions. In general, cd into each directory and run git pull

Run update.php

# cd /var/www/html/mediawiki
# /usr/bin/php /var/www/html/mediawiki/maintenance/run.php update

Sometimes you will get an error when running update.php that points to one or more lines in LocalSettings.php. If that line relates to module loading with the old style, then try converting it to the newer wfLoadExtension(); format.

Test the new code
Notify users that the wiki is available again
Perform post-upgrade change control process

Notes

Upgrading from 1.34.4 to 1.35.1 required upgrading the ExternalData extension on my wiki. I use ED (#get_web_data) to show the versions of the live MW and WP websites to compare against the locally running version. After upgrading, my homepage generated an error, which needed $wgShowExceptionDetails = true; in LocalSettings.php to provide a clue to the real fault.
Keep an eye on which of your locally maintained extensions have been ported to the newer loading format using wfLoadExtension. For me, recently on updating them from git, I had to move GraphViz and MyVariables over to the newer load format
Removing the Parsoid package caused a generic error when invoking VE. I had to add a wfLoadExtension for Parsoid. I've included it above. See Extension:VisualEditor#Troubleshooting for additional help if you are still in trouble
My test MW had an extra Skin/theme from the wizard that needed removing from LocalSettings before update.php could run
update.php should not be run directly and instead called via run.php

ipblocks table

I upgraded to 1.43 and got errors regarding a missing ipblocks table. That table is deprecated ^[10] but something needs it and creating an empty table with the following definition got my wiki working again. The definition was taken from 1.42.0-wmf.14/maintenance/tables-generated.sql. I have not got to the bottom of this yet, so I won't update this page to 1.43 Gerdesj (talk) 23:02, 6 August 2024 (UTC)[reply]

SHOW databases;
USE mediawiki;
CREATE TABLE ipblocks (
  ipb_id INT UNSIGNED AUTO_INCREMENT NOT NULL,
  ipb_address TINYBLOB NOT NULL,
  ipb_user INT UNSIGNED DEFAULT 0 NOT NULL,
  ipb_by_actor BIGINT UNSIGNED NOT NULL,
  ipb_reason_id BIGINT UNSIGNED NOT NULL,
  ipb_timestamp BINARY(14) NOT NULL,
  ipb_auto TINYINT(1) DEFAULT 0 NOT NULL,
  ipb_anon_only TINYINT(1) DEFAULT 0 NOT NULL,
  ipb_create_account TINYINT(1) DEFAULT 1 NOT NULL,
  ipb_enable_autoblock TINYINT(1) DEFAULT 1 NOT NULL,
  ipb_expiry VARBINARY(14) NOT NULL,
  ipb_range_start TINYBLOB NOT NULL,
  ipb_range_end TINYBLOB NOT NULL,
  ipb_deleted TINYINT(1) DEFAULT 0 NOT NULL,
  ipb_block_email TINYINT(1) DEFAULT 0 NOT NULL,
  ipb_allow_usertalk TINYINT(1) DEFAULT 0 NOT NULL,
  ipb_parent_block_id INT UNSIGNED DEFAULT NULL,
  ipb_sitewide TINYINT(1) DEFAULT 1 NOT NULL,
  UNIQUE INDEX ipb_address_unique (
    ipb_address(255),
    ipb_user,
    ipb_auto
  ),
  INDEX ipb_user (ipb_user),
  INDEX ipb_range (
    ipb_range_start(8),
    ipb_range_end(8)
  ),
  INDEX ipb_timestamp (ipb_timestamp),
  INDEX ipb_expiry (ipb_expiry),
  INDEX ipb_parent_block_id (ipb_parent_block_id),
  PRIMARY KEY(ipb_id)
) /*$wgDBTableOptions*/;

References

↑ Manual:Image administration - Installing third party tool in the MW Manual
↑ https://www.mediawiki.org/wiki/MediaWiki - MW website
↑ https://en.wikipedia.org/wiki/Special:Version - WP version page
↑ phab:source/mediawiki/branches/ - Development branches
↑ https://www.mediawiki.org/wiki/Skin:Minerva_Neue - Documentation on the Minerva Neue skin
↑ https://www.mediawiki.org/wiki/Manual:Job_queue Job Queue documentation
↑ https://www.mediawiki.org/wiki/Extension:WikiEditor - Wikieditor extension documentation
↑ https://www.mediawiki.org/wiki/Extension:Auth_remoteuser - Auth_remoteuser extension documentation
↑ https://www.mediawiki.org/wiki/VisualEditor - Visual Editor
↑ Manual:Ipblocks table - ipblocks table documentation

[1] Manual:Image administration - Installing third party tool in the MW Manual

[2] ttps://www.mediawiki.org/wiki/MediaWiki - MW website

[3] ttps://en.wikipedia.org/wiki/Special:Version - WP version page

[4] :source/mediawiki/branches/ - Development branches

[5] ttps://www.mediawiki.org/wiki/Skin:Minerva_Neue - Documentation on the Minerva Neue skin

[6] ttps://www.mediawiki.org/wiki/Manual:Job_queue Job Queue documentation

[7] ttps://www.mediawiki.org/wiki/Extension:WikiEditor - Wikieditor extension documentation

[8] ttps://www.mediawiki.org/wiki/Extension:Auth_remoteuser - Auth_remoteuser extension documentation

[9] ttps://www.mediawiki.org/wiki/VisualEditor - Visual Editor

[10] Manual:Ipblocks table - ipblocks table documentation

[1]

[2]

[3]

[4]

[5]

[6]

[7]

[8]

[9]

[10]