Mediawiki installation

The educational technology and digital learning wiki
Jump to navigation Jump to search

Some installation tips, in particular for an educational context. This documentation should be extended/completed - Daniel K. Schneider (talk) 16:18, 16 January 2014 (CET)

Also consider buying Yaron Koren's book

See also:

Installation tips are for Ubuntu. The old version runs under Solaris (IMHO a superior but much more difficult environment, this is why we decided to switch).

First time installation and upgrading

(To do, I will make this short, since it's not difficult...)

If you want to work with a bleeding edge alpha version (sometimes this is recommended, sometimes not), the simplest way is using GIT (formerly SVN was used). The reason not to use the latest version is that extensions can break and that very early versions may have bugs.

Type something like: 

git clone https://gerrit.wikimedia.org/r/p/mediawiki/core.git

Updating the same version: 

git pull
php maintenance/update.php

Changing versions: 

git checkout <new version>
for example
git checkout REL1_23

Tips:

  • Upgrade to a different directory, then copy the files
  • Backup the database (dump it)

See ManageMediaWiki for some rather chaotic additional tips.

Configuration

The main configuration file

Unless you use some configuration extension, all the configuration (except for styles and user messages) is done in file LocalSettings.php (in the top-level directory of the distribution)

Reading:

LocalSettings.php will read first the file includes/DefaultSettings.php and then override with your own settings. Below are a few settings (also read "nice URLs" below). 

// also used as namespace for certain pages, so select with care
$wgSitename   = "EduTech Wiki";
 
// Use the file cache and gzip the files
$wgUseFileCache = true;
$wgFileCacheDirectory = "$IP/cache";
$wgShowIPinHeader = false; 
$wgDisableOutputCompression = true; // in case you have some leftover code that will gzip any output (not compatible)
$wgUseGzip = true;

// Rights
$wgEnableCreativeCommonsRdf = true;
$wgRightsPage = "EduTech_Wiki:Copyrights"; # Set to the title of a wiki page that describes your license/copyright
$wgRightsUrl = "http://creativecommons.org/licenses/by-nc-sa/3.0/";
$wgRightsText = "CC BY-NC-SA Licence";
$wgRightsIcon = "$wgStylePath/monobook/tecfa/somerights.png";

// Permissions - editing users need to have a login
$wgGroupPermissions['*']['edit']            = false;
$wgGroupPermissions['*']['createaccount']   = true;
# $wgGroupPermissions['*']['createaccount']   = false;
$wgGroupPermissions['*']['read']            = true;

// Strongly suggest to keep this (enabled by default). Puts all the messages in the database
// (easier to edit and edits will survive upgrades
$wgUseDatabaseMessages = true;

// What file uploads to you accept, e.g.
$wgFileExtensions = array( 'png', 'gif', 'jpg', 'jpeg', 'ogg', 'pdf', 'mp3', 'svg', 'doc', 'xls', 'ppt', 'pub', 'txt', 'ps', 'zip' );

Permission

In some wikis you may want to set permissions, e.g. only allow people in an author group to edit or only allow registered users to read. Since Mediawikis are designed to support either open sites like Wikipedia or closed sites or read-only sites, the permissions system is fairly simple. In our opinion it's good enough for most educational scenarios:

Example (from EduTechWiki): Only registered users can edit 

$wgGroupPermissions['*']['edit']            = false;
$wgGroupPermissions['*']['createaccount']   = true;
$wgGroupPermissions['*']['read']            = true;

In addition, we actually use a confirm edit and captcha extensions. Only folks in the author group can edit hassle free: 

$wgGroupPermissions['authors']['skipcaptcha'] = true;

Note: As soon as you use a user group in a $wgGroupPermissions statement, the group is created and you can add users to it through the Special:UserRights page.

Example (from a biology teaching wiki): Only current students can edit, all others can read 

$wgGroupPermissions['*']['createaccount']   = true;
$wgGroupPermissions['*']['read']            = true;
$wgGroupPermissions['*']['edit']            = false;
$wgGroupPermissions['*']['createpage']      = false;
$wgGroupPermissions['*']['move']            = false;
$wgGroupPermissions['*']['createtalk']      = false;
$wgGroupPermissions['*']['upload']          = false;
$wgGroupPermissions['*']['reupload']        = false;
$wgGroupPermissions['*']['reupload-shared'] = false;
$wgGroupPermissions['*']['minoredit']       = false;
$wgGroupPermissions['user' ]['read']            = true;
$wgGroupPermissions['user' ]['move']            = false;
$wgGroupPermissions['user' ]['edit']            = false;
$wgGroupPermissions['user' ]['createpage']      = false;
$wgGroupPermissions['user' ]['createtalk']      = false;
$wgGroupPermissions['user' ]['upload']          = false;
$wgGroupPermissions['user' ]['reupload']        = false;
$wgGroupPermissions['user' ]['reupload-shared'] = false;
$wgGroupPermissions['user' ]['minoredit']       = false;
$wgGroupPermissions['eleve7']['read']            = true;
$wgGroupPermissions['eleve7']['edit']            = true;
$wgGroupPermissions['eleve7']['move']            = true;
$wgGroupPermissions['eleve7']['createpage']      = true;
$wgGroupPermissions['eleve7']['createtalk']      = true;
$wgGroupPermissions['eleve7']['upload']          = true;
$wgGroupPermissions['eleve7']['reupload']        = true;
$wgGroupPermissions['eleve7']['reupload-shared'] = true;
$wgGroupPermissions['eleve7']['minoredit']       = true;

Restrict permissions in name spaces

The Lockdown extension allows to restrict permission for both special pages and namespaces. This extension did install and work with MW 1.22 (Jan 2014).

Example from a project-oriented learning wiki, that only allows some users to read the discussion pages (these pages may contain confidential discussion/data) 

// Lockdown Permissions:
require_once "$IP/extensions/Lockdown/Lockdown.php";
$wgNamespacePermissionLockdown[NS_TALK]['read'] = array('author');
$wgNamespacePermissionLockdown[NS_TALK]['read'] = array('sysop');

Messages

Configuring interface messages is quite easy. Use the following procedure, if you can't recall the names of the appropriate Mediawiki pages (each message is defined in its own page).

  1. List all messages with the special page Special:Allmessages
  2. You then can customize each Mediawiki message, by clicking on a message and edit

Notice:

  • Works by default, i.e. $wgUseDatabaseMessages = true;
  • If you are not using database messages, you can edit the languages/Language.php file (for English) or languages/LanguageXX.php for non-English languages, where XX is the two-letter language code for your language
  • Be careful: entering wrong data may disable some messages ....

Each of the Mediawiki:XXX pages you may configure are listed in Special:Allmessages as we said above. The ones you did redefine will be in green. Below are two examples:

A slogan message

The page MediaWiki:Sitesubtitle will allow you to add some sort of slogan (you also can kill this default page). Has the same effect as setting the $wgExtraSubtitle variable.

Sitenotices (e.g. to annonce an important event)

Read: http://www.mediawiki.org/wiki/Manual:Interface/Sitenotice

Another way way of using it is to define $wgSiteNotice = " ........ "; in LocalSettings.php

Nice URLs

You don't want ugly default URLs (e.g. http://edutechwiki.unige.ch/en/Mediawiki_installation instead of http://edutechwiki.unige.ch/mediawiki/index.php?title=Mediawiki_installation).

Reading: http://www.mediawiki.org/wiki/Manual:Short_URL

Here is an easy way to do achieve this for the content pages. The method described below is probably not exactly the one that is now being suggested by the manual, but we have to stick to our old solution since we believe in stable URLS !

In httpd.conf: 

  Redirect /portails/mediawiki  "http://edutechwiki.unige.ch/en"
  Redirect /mediawiki  "http://edutechwiki.unige.ch/en"
  Redirect /portails/fmediawiki "http://edutechwiki.unige.ch/fr"

<VirtualHost *:80>
       ServerName edutechwiki.unige.ch
       DocumentRoot "/data/portails/edutechwiki"
   # ALIASES for edutechwiki: THREE alias for each WIKI
   Alias /mediawiki "/data/portails/mediawiki"
   Alias /en "/data/portails/mediawiki/index.php"
   Alias /en/index.php "/data/portails/mediawiki/index.php"
   Alias /fmediawiki "/data/portails/fmediawiki"
   Alias /fr "/data/portails/fmediawiki/index.php"
   Alias /fr/index.php "/data/portails/fmediawiki/index.php"
< /VirtualHost >

Then in LocalSettings.php: 

$wgSitename         = "EduTech Wiki";

$wgScriptPath	    = "/mediawiki";
$wgScript           = "$wgScriptPath/index.php";
$wgRedirectScript   = "$wgScriptPath/redirect.php";

## If using PHP as a CGI module, use the ugly URLs
#   $wgArticlePath      = "$wgScript/$1";
# DKS 3/2006
$wgArticlePath      = "/en/$1";

Therefore only "normal" pages look nice. Special pages remain ugly, but this doesn't matter IMHO.

Also consider excluding all or most special pages in robots.txt. No reason that these should be indexed and they really eat away CPU cycles if you need another argument. 

User-agent: *
Disallow: /mediawiki/
Disallow: /en/Special:Search
Disallow: /en/Special:Random

etc ....

Skins and CSS

Unless you have time to spend, I suggest to use the standard Vector or Monobook skin. Other skins are not as well supported. E.g. some extensions just won't work with other skins.

You should define CSS (in particular class or id selectors for extensions) in MediaWiki:Common.css. Do not edit CSS files in the server if you can avoid. This strategy makes maintenance much easier.

Using Skins with Git download

Important: If you download the mediawiki code via Git, the skin is not included starting version 1.24 (read this, summer/fall 2014)

Do the following: 

cd <install-dir>
cd skins
git clone https://gerrit.wikimedia.org/r/p/mediawiki/skins/Vector.git

In Localsettings, load it: 

require_once "$IP/skins/Vector/Vector.php";
$wgDefaultSkin = 'vector';

Changes to the navigation bar to the left

Reading: Navigation bar help

Configuration: Edit MediaWiki:Sidebar in your wiki

Since version 1.14 (or earlier) you may use keywords to change the order of portlets (boxes with menu items). E.g. 

* SEARCH

* navigation and help
** mainpage|Mainpage
** EduTech_Wiki:About|about
<!-- ** portal-url|portal -->
<!-- ** currentevents-url|currentevents --> 
** randompage-url|randompage
** helppage|Help
** Help:Editing rules|Editing rules
** Blog:DKS|Blog (D.K.S.)

* categorytree-portlet

* TOOLBOX

* LANGUAGES

* big brother
** Special:Newpages|New Pages
** recentchanges-url|recentchanges
** Special:Guestbook|Guestbook
** Special:Popularpages|Popular Pages
** Special:WhosOnline|Who is online ?

* TECFA links
** http://tecfa.unige.ch/ |TECFA
** http://tecfaseed.unige.ch/door/ |TECFA Portal

In addition one also could add more sophisticated custom items (instead of hand editing the skin files, to do ....)

Subpages

According to the MediaWiki help pages Subpages can be useful for three major purposes.

  • to create archives of old discussions under a talk page
  • to create scratchpad editing spaces under a user page
  • to create other language versions of a document in multilingual wikis

Slashes (/) within a page name break the page into parent and subpages, recursively

Avoid subpages for regular pages and for two reasons: It's against the wiki/hypertext philosophy and some crucial extensions (like the book creator) can't find them !

Read:

It you plan to enable supages everywhere, use: 

# Enable subpages in all namespaces
$wgNamespacesWithSubpages = array_fill(0, 200, true);

Else use something like: 

$wgNamespacesWithSubpages =
     array(
	NS_TALK           => true,
	NS_USER           => true,
	NS_USER_TALK      => true,
	NS_PROJECT_TALK   => true,
	NS_IMAGE_TALK     => true,
	NS_MEDIAWIKI_TALK => true,
       NS_TEMPLATE       => true,
	NS_TEMPLATE_TALK  => true,
	NS_HELP_TALK      => true,
	NS_CATEGORY_TALK  => true,
       102  => true,
       103  => true
)

Adding extra namespaces

Some extensions, e.g. wikilog or semantic mediawiki use additional namespaces. It is difficult to know what namespaces are used and more so what index number they are.

  • To list the prefixes in use the pull-down menu: Special:PrefixIndex
  • To figure out the index number look at the source of the above page.

E.g. you will see something like this: 

<option value="100">Admin</option>
<option value="101">Admin Discussion</option>
<option value="102">STIC</option>
<option value="103">STIC Discussion</option>
<option value="104">Blog</option>
<option value="105">Blog talk</option>
<option value="106">COAP</option>
<option value="107">COAP Discussion</option>
<option value="110">Property</option>
<option value="111">Property talk</option>
<option value="114">Form</option>
<option value="115">Form talk</option>
<option value="116">Concept</option>
<option value="117">Concept talk</option>
<option value="118">Filter</option>
<option value="119">Filter talk</option>

Default user preferences

In a wiki with long pages like this one, you could make numbered titles the default: 

$wgDefaultUserOptions['numberheadings'] = 1;

Insert pages edited by a user on their watchlist 

$wgDefaultUserOptions['watchdefault'] = 1;

Send email if a watched page is changed (only do this in a small "organizational" wiki ....) 

$wgDefaultUserOptions['enotifwatchlistpages'] = 1;

If you change user preferences, you maybe should plan to update the old users. To do so, use a maintenance script:

Number headings
  • In the terminal, type
cd your_mediawiki_directory
php maintenance/userOptions.php numberheadings --old 0 --new 1

Ubuntu

(taking notes for a fresh installation Daniel K. Schneider (talk) 13:42, 9 April 2015 (CEST) - should be ok in a few days)

  • Starting point: Ubuntu 14.04.2 LTS with PHP/Apache/MySQL and curl installed

This section summaries software that must be installed if you plan to use all sorts of interesting extensions. Otherwise

Git

Git is Revision control system and is needed to download MW and extension software and to manage versions. You could do it the traditional way (e.g. download file archives), but using git can save time. 

apt-get install git

Composer

Composer is a PHP package management system and it is needed to manage some important Mediawiki extensions

  • You can download it to any directory (here I used "/src"), but then the composer.phar file should be copied to /usr/local/composer
mkdir /src
cd /src
curl -sS https://getcomposer.org/installer | php
# testing
./composer.phar
# installing
mv composer.phar /usr/local/bin/composer

Extensions

Notice: This section should be moved to a different page and be merged with some contents of the Mediawiki page - Daniel K. Schneider (talk) 17:04, 21 August 2013 (CEST)

See also the Mediawiki article where we list extensions we find useful to have. Here, we only document installation and/or configuration of the more difficult ones.

Download and documentation: You will find most extensions on MediaWiki.org. The Extensions category page will provide several entry points. I sort of like the Extension_Matrix page.

The easy method

If you use a bleeding Mediawiki server then you simply can cut/past git commands into a terminal

General extension installation principles

Most extensions are well documented, just read the instructions and follow them. However, since some are badly maintained you sometimes will have to read the discussion page for finding appropriate patches...

Installaing extensions the traditional way

A checklist of things to look at and to do:

(1) Check if the extension is compatible with your MW version (this is not always obvious, therefore you also should look for hints in its dicussion page).

(2) Read the discussion page that will tell you something about the quality of an extension.

(3) Download the extension either as archive (zip etc.) or via GIT. Some simple extensions are just available as code section from the wiki page that you must copy to a file.

  • Make sure that the files sit in a directory unless its a simple single file extension
  • Move the extension directory to the extensions folder of your installation
  • Add all the extra stuff an extension may need. This can sometimes be a lot (e.g. a days work!), sometimes nothing). Most extensions are simple and don't need other server-side programs.
  • If the extension needs a cache, you may have to change write permissions in some subdirectory.

(4) Load and configure:

  • Edit LocalSettings.php to configure and to load the extension.
  • You may have to define configuration variables in the LocalSettings.php file and/or by defining Mediawiki:XXX pages
  • You may have the option to add CSS definitions to the MediaWiki:Common.css pages
  • Some extensions will update the database. In that case it is important to run the update script
php maintenance/update.php
  • Sometimes you need to define templates, modify the CSS, etc.

Installing extensions with Composer

After mid-november 2013, you should learn how to use composer, a PHP dependency manager. It should work with the following:

Installing Composer
  • PHP 5.3.2+
  • MySQL 5.0.2+
  • CURL
  • MediaWiki 1.22 (nov 2013) or better.

If your server doesn't meet these requirements (in particular a new 1.22 MediaWiki), then use the traditional way.

If you run several wikis, it's probably best to install composer on system level: 

 cd /some/src
 curl -sS https://getcomposer.org/installer | php
 mv composer.phar /usr/local/bin/composer
Removing old extension versions
  • Remove the old files in the extensions directory
  • In LocalSettings.php remove the line that loads the extension, e.g.
require_once( "$IP/extensions/DataValues/DataValues.php" );
Install extensions using composer

Composer is run from the base directory (and not the extensions directory) !!

See the documentation for each extension. Examples: 

composer require mediawiki/semantic-media-wiki "1.9.*,>=1.9.0.1"
composer require mediawiki/semantic-media-wiki "~2.0"
Update all extensions using composer.
If the dependencies are right, this should work without worrying about versions.
composer update

Server modifications

Some extensions, e.g. the book creation tools need a lot of RAM and CPU. You may have to increase, e.g.

In php.ini: 

max_execution_time = 600
max_input_time = 600
memory_limit = 100M

In httpd.conf: 

Timeout 600

Collection extension

There exist two ways of using this PDF/OO/DocBook book generator. Just install the extension files and use the PediaPress server for generating the PDF or OO documents. This strategy did not work out well and we use our own server. Installation is fairly complex.

Most important documentation and download pages
Extension page Collection: http://www.mediawiki.org/wiki/Extension:Collection
Extension page PDF_Writer: http://www.mediawiki.org/wiki/Extension:PDF_Writer
MwLib/Collection server installation guide (if needed): http://code.pediapress.com/wiki/wiki/mwlib-install
See Mediawiki collection extension installation for our own installation notes

Additional software needed if you install your own MwLib (at least)

Dependencies
  • Perl => 5
  • g++
  • Latex
    • Also compile texvc in mediawiki/math directory
  • Blahtexml
The mwlib server and tools

Graphviz

This extension can generate graphs with the dot syntax.

Most important documentation and download pages
Extension page: http://www.mediawiki.org/wiki/Extension:GraphViz
Additional installs: Graphviz from http://www.graphviz.org/Download.php plus needed libraries that you may or may not have on your server
Dependencies

Graphviz itself needs several libraries like GD, Zlib, Freetype, PNG, JPEG, EXPAT, etc. (read http://www.graphviz.org/Download_source.php Requirements).

There exist binary packages for most systems (not yet tested)

Tag cloud

There are several tag cloud extensions, we use the following one (at the time of writing)

Extension page: http://www.mediawiki.org/wiki/Extension:WikiCategoryTagCloud

Extension page (old): http://wiki-tools.com/wiki/Wiki_Category_Tag_Cloud

Additional installs: None

Hints:

  • If you want an accurate cloud, you should edit MediaWiki:Tagcloudpages and add the pages to invalidate the cache for.

UML extension

UML is an extension that allows to generate graphs from MetaUML format. This extension dates back to 2007, but still seems to work. MetaUML also was kind of sleeping, but seems to be an active project again (Aug 2009).

Update: Removed in 2013 since (1) it worked less well and (2) because it is dangerous if you got a nasty user...

Most important documentation and download pages
Extension page: http://www.mediawiki.org/wiki/Extension:UML
Additional installs
MetaUML from http://metauml.sourceforge.net/
Dependencies
ImageMagick and Ghostscript

SVG visualization

See: Mediawiki SvGViz extension

Other extensions

As we said before, many extensions are really simple to install and don't need any difficult work. See the Special:Version page for the ones we currently use. Most extensions provide an URL that will directly lead you to the extensions download and documentation page.

Retrieved from "https://edutechwiki.unige.ch/mediawiki/index.php?title=Mediawiki_installation&oldid=55366"