Intranet/Intranet Installation

From MediaWiki.org
Jump to: navigation, search

This page documents installing MediaWiki, some basic customisation and an upgrade process. This process builds upon the Reference OS and supporting software installation covered at Intranet

  • 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
16 Nov 2017 Ubuntu "Xenial" 1.31.0-wmf.6 (Git) Everything appears to work OK up to and including DB backups

23 Nov 2017

Ubuntu "Xenial"

1.31.0-wmf.7 (Git)

Update process tested and slightly amended. VE included

8 Dec 2017

Ubuntu "Xenial"

1.31.0-wmf.11 (Git)

Removed tarball "stable" bits from this article to avoid confusion and complexity. Works rather well.

17 Jan 2018 Ubuntu "Xenial" 1.31.0-wmf.16 OK (clarification update to this article - no process change)

Initial MW Installation[edit]

Settings[edit]

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[edit]

By following this procedure, the directory structure you end up with is like this:

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[edit]

  • 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. Be sure to set a suitable password (line 4 below)
1 # mysql -u root -p
2 
3 MariaDB [(none)]> create database mediawiki;
4 MariaDB [(none)]> create user 'mediawiki'@'localhost' identified by 'random_string';
5 MariaDB [(none)]> grant all privileges on mediawiki . * to 'mediawiki'@'localhost';
6 MariaDB [(none)]> flush privileges;
7 MariaDB [(none)]> \q

Install MediaWiki software[edit]

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[edit]

# cd /var/www/html
  • Find a version using git ls-remote:
# git ls-remote --heads https://gerrit.wikimedia.org/r/p/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/p/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[edit]

  • 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 don't enable any modules. All of this can be changed later. At the end, download the provided LocalSettings.php file and upload it to the web server's filesystem at /var/www/html. Finally 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[edit]

# 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[edit]

  • Add a couple of Aliases outside of the virtual host definition. These are for the final desired 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

[edit]

  • 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[edit]

  • 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[edit]

  • 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
    
  • 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]

  • 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[edit]

Auth_remoteuser[8][edit]

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[edit]

Parsoid[9][edit]

The default port for Parsoid is 8000 but this package sets port 8142

# apt install software-properties-common
# apt-key advanced --keyserver keys.gnupg.net --recv-keys 90E9F83F22250DD7
# apt-add-repository "deb https://releases.wikimedia.org/debian jessie-mediawiki main"
# apt update
# apt install parsoid
# systemctl status parsoid
... Parsoid shown as running ...

Visual Editor Extension[10][edit]

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 link it to Parsoid by adding these lines towards the bottom of LocalSettings.php

wfLoadExtension( 'VisualEditor' );

# Visual Editor
$wgDefaultUserOptions['visualeditor-enable'] = 1;
$wgVirtualRestConfig['modules']['parsoid'] = array(
        'url' => 'http://localhost:8142',
        'domain' => 'localhost',
);
# Visual Editor

Database Backups[edit]

  • 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[edit]

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[edit]

  • Perform pre-upgrade change control process
  • Check backups
  • Run database backup script
  • Shutdown the system and take a snapshot
  • Start the system
  • Stop the web server (systemctl stop apache2)

Update the code[edit]

  • 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/p/mediawiki/core

... pick a version ...

# git clone --depth=1 --single-branch --branch wmf/1.31.0-wmf.16 https://gerrit.wikimedia.org/r/p/mediawiki/core.git 1.31.0-wmf.16
# cd 1.31.0-wmf.16
# git submodule update --init --recursive
  • Create symlinks
# cd /var/www/html/1.31.0-wmf.16    .... 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[edit]

  • Make the wiki readonly. Put this at the bottom of LocalSettings.php:
$wgReadOnly = 'This wiki is currently being upgraded.';
  • Start Apache
  • Remove and re-point the symlink.
# cd /var/www/html
# rm mediawiki
# ln -s 1.31.0-wmf.16 mediawiki
  • Run update.php
# /usr/bin/php /var/www/html/mediawiki/maintenance/update.php
  • Make the wiki read/write. Delete or comment out $wgReadOnly in LocalSettings.php
# $wgReadOnly = 'This wiki is currently being upgraded.';
  • Run the database backup script again
  • Test the new code[11]
  • Notify users that the wiki is available again
  • Perform post-upgrade change control process

References[edit]