User:Al Maghi/Industrialization guide/Archive

Guidebook to industrialize production of wikis running on MediaWiki engine. It describes the whole process, in 3 major steps: Installation, Configuration & Importation of basic-content.

This is a draft version. Be bold and improve it!

This is not a technical reference manual, it is a guidebook to industrialize wiki production.

Overview

To get wiki-web-sites running on MediaWiki you need to distinguish two separate technical roles:

Network administration:

The first role is to be responsible for the MediaWiki server; you need someone at ease with web server administration.
- As a network administrator, he is responsible for back-up, upgrade, accessibility and security of the web server.
- All he has to be furthermore responsible for is to install and set up MediaWiki to serve the chosen URL, to accept file upload and to render LaTeX formula; and then to open up an ftp access for the second role.

MediaWiki configuration:

The second role is to be responsible for the MediaWiki configuration; you need someone to be responsible for the wiki functionalities. Let’s call him super-user.
- He needs an ftp access to LocalSettings.php file, /extensions and /skins folders.
- He has to be available for wiki users to set up the desired functionalities.

Management:

Other roles are about wiki administration and edition:
- Bureaucrats: they manage user rights
- Administrators: they edit MediaWiki interface and skin, through MediaWiki namespace. They delete unused content. They categorize, write templates, do maintenance.
- Users: they read and edit the wiki.

Processing a MediaWiki production

Installation of Mediawiki server (Linux, Apache, MySQL, PHP): creation of databases, configuration of user authentication, installation of server tools. → Server administrator.
Configuration of MediaWiki wiki-web-site: extensions, user rights definition, browser interface and skin. → MediaWiki expert.
Management of usage: architecture of content & user management. → Knowledge Manager.

Installing MediaWiki web server, with a network administrator

All the network admin needs to know is:

Name of the wiki
Language of the wiki
E-mail contact of the super-user
Username of the super-user
Chosen URL of the wiki
For user registration,
- is the LDAP authentication wanted?
- By default managers create accounts for users. Is it preferred that a potential user ask for an account then managers confirm account creation? Then a ConfirmAccount extension would be installed.

Once he has finished he shall give an ftp access to LocalSettings.php, to /extensions, and to /skins. Back-up, upgrade, accessibility and security of the web server is under his responsibility.

Manuals: http://www.mediawiki.org/wiki/Installation http://www.mediawiki.org/wiki/Category:Installation

Install a MySQL-PHP web server on the desired network

Install an AMP server with latest versions of Apache, MySQL and PHP. You can choose to create a virtual server. You can if you prefer use an IIS server and/or a PostgreSQL database.

In php.ini change post_max_size and upload_max_filesize parameters so that wiki users will be able to upload large files, such as 1Go. (Manual:Configuring file uploads)
Install ImageMagick on the server. Note the command path.

Create a database and its associated user

Create a MySQL database called wikidb and a MySQL user called wikiuser, with a password of your choice that you will afterward indicate in LocalSettings.php.

Create a MediaWiki directory in web directory

In web directory, create folder /mediawiki_version and sub-folder /w

/mediawiki_version
       /w

In directory /w put MediaWiki files downloaded from: http://www.mediawiki.org/wiki/Download
In directory /w/extensions put extensions files downloaded from: http://toolserver.org/~vvv/mw-nightly/

Create four directories in /images as shown below:

/mediawiki_version
      /w
           …
           /images
                /archive
                /thumb
                /temp
                /math
           …

Configure MediaWiki through browser

Go to http://yourServerPath/w and fill-in the wiki name, the e-mail contact, the wiki language, the super-user username with a temporary password, and the DB password you’ve chosen at step 2. You may disable “E-mail address authentication” as the e-mail addresses of users are not subject of authentication issue.

Figure 1 - installation successful - LocalSettings.php has been created

Read: Manual:Config script

Set up LocalSettings.php and move it to its parent directory

Short URL

Open-up LocalSettings.php and httpd.conf to set-up configuration of URL

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

A basic solution is described below, in two steps:

In LocalSettings.php: Replace these two lines

$wgScriptPath  = "/w";
$wgScriptExtension  = ".php";

With:

$wgScriptPath  = "/w";
$wgScript      = "$wgScriptPath/index.php";
$wgArticlePath = "/wiki/$1";
$wgUsePathInfo = true;
$wgScriptExtension  = ".php";

In httpd.conf add the following alias:

Alias /wiki ${path}/w/index.php //adapt it with your server path.

Tip: You may use a rewrite rule in a .htaccess instead of a mod_alias.

Move LocalSettings.php to its parent directory. The wiki web site is set up and redirects to URL looking like http://localhost/wiki/Main_Page on reading and http://localhost/w/index.php?title=Main_Page&action=edit on editing.

Figure 2 - the wiki is serving to the short URL /wiki/Main_Page

Other settings: Images, TeX, etc.

Before handing over to super-user we will add some lines to LocalSettings.php, to configure PHP’s memory, image upload and LaTeX render:

A. First, raise PHP's memory limit in LocalSettings.php

ini_set( 'memory_limit', '1000M' );

B. Then set up image upload: Manual:Image Administration

$wgEnableUploads       = true;
$wgUseImageResize      = true;
$wgUseImageMagick 	= true;
$wgImageMagickConvertCommand = "/usr/bin/convert";
 
## If you use ImageMagick (or any other shell command) on a
## Linux server, this will need to be set to the name of an
## available UTF-8 locale
$wgShellLocale = "en_US.UTF-8";
 
## If you want to use image uploads under safe mode,
## create the directories images/archive, images/thumb and
## images/temp, and make them all writable. Then uncomment
## this, if it's not already uncommented:
$wgHashedUploadDirectory = false;
 
## You trust your users
$wgAllowExternalImages = "true";
$wgStrictFileExtensions = false;
$wgFileExtensions = array( 'svg', 'doc', 'gif', 'xls', 'avi', 'mpg', 'mpp', 'pdf', 'zip', 'mm');
$wgUploadSizeWarning = false;
$wgMaxUploadSize = 1024*1024*1000; // 1Go upload permission
$wgCheckFileExtensions = false;
$wgVerifyMimeType = false;     // Disable mime type detection 
 
$wgAllowImageMoving = true; 

$wgUploadDirectory = "images";
$wgMathPath = "{$wgUploadPath}/math";
$wgMathDirectory = "{$wgUploadDirectory}/math";
$wgTmpDirectory = "{$wgUploadDirectory}/tmp";

You can test the image upload through the [[Special:Upload]] page by logging in with super-user account.

LaTeX setting: Manual:Enable TeX

Install OCaml on the server then configure LocalSettings.php with $wgUseTex = true;

You can test LaTeX by writing a basic formula on main page: <math>x=\frac{-b\pm\sqrt{b^2-4ac}}{2a}</math>

Tip: A simple alternative is to use Mimetex extension.

D. Add also the following lines

$wgAllowSlowParserFunctions = true;
$wgUseAjax = true;
###--- End of Network Administration settings ---###
#
###--- Start of Wiki Administration settings ---###

Hand over to super-user

Create an ftp access for wiki super-user and send him its username and its temporary password.

He has the necessary tools to get the functionalities he would like on the wiki web site. Some further optional tools may need a network admin intervention, they are described below.

Optional tools:

See: Manual:Installing third-party tools

GNUplot and GraphViz to render graphs

Plotters as alternative to GNUplot to render graphs

The gnuplot and ploticus extensions have fairly major security risks. An alternative is using the Plotters extension with Plotkit (or another javascript graphing library of your choice). This is a javascript-only solution, but most corporate environments require javascript.

Setting up wiki configuration, with a ftp access and a sysop account

The MediaWiki web site is empty, available to the given URL. A super-user is necessary to configure how the wiki looks, what functionalities are installed and how the user rights are managed.

Required competences are:

browsing MediaWiki directory,
reading and editing LocalSettings.php file,
browsing and using the Special Pages of the wiki,
browsing and editing the MediaWiki namespace of the wiki.

Change your password

First of all go to the wiki web site URL, log in with the given super-username and then change your password through your [[Special:Preferences]] page.

Logo and favicon images

Use your ftp access to open the file LocalSettings.php. It is located in mediawiki root directory named /w.

Create a 155x135 logo and a 32x32 favicon and upload them using [[Special:Upload]] page or directly through ftp.

Add at bottom of LocalSettings.php the following lines, adapted with the correct images’ paths:

# Here is the location of the small 155x135 logo that go at the upper left corner of every page
$wgLogo = "$wgScriptPath/images/8/80/wikiLogo.png";
# Here is the favicon in reader's browser
$wgFavicon = "$wgScriptPath/images/3/50/favicon.ico";

Save, upload those changes to server, and reload a wiki page in a browser to see if changes are correct.

Footer links

a. Remove the “Powered by MediaWiki” icon. You can hide the “Powered by MediaWiki” image by adding the following to your wiki's MediaWiki:Common.css:

#f-poweredbyico { display: none; }

(Note: MediaWiki:Common.css is a page in MediaWiki namespace that applies cascading style sheet to every user.)

b. Change footer links Look at the wiki footer links (privacy policy, disclaimers, etc.) and if you want to change those, go into /Skins/MonoBook.php where you will find the following code:

$footerlinks = array(
	'lastmod', 'viewcount', 'numberofwatchingusers', 'credits', 'copyright', 'privacy', 'about', 'disclaimer', 'tagline',
);

In the above you can simply add and remove items from the array that you wish to appear in your footer. For example we’ve changed it this way:

$footerlinks = array(
	'lastmod', 'viewcount', 'numberofwatchingusers', 'about', 'tagline',
);

Choose user default options

In LocalSettings.php is defined what are the default user option preferences, applying to new user accounts. You probably want something like those options:

### See http://www.mediawiki.org/wiki/Manual:$wgDefaultUserOptions
$wgDefaultUserOptions = array( 
	'math'			=> 2, // Sets math render preference
	'rcdays'			=> 14,
	'rclimit'			=> 50,
	'imagesize'		=> 2,
	'thumbsize'		=> 5, //large thumbnail
	'rememberpassword' 		=> 0, //No, for security reason
	'enotifwatchlistpages'	=> 1, //email if watchlist change
	'enotifusertalkpages'	=> 1, //email if user talk page
	'enotifminoredits'		=> 0,
	'watchlistdays'	=> 21.0,
	'watchlisthideown'	=> 1, //hide my own edits on watchlist
	'watchlisthidebots'	=> 1, //hide bot edits
	'watchlisthideminor'=> 1, //hide minor edits
	'watchcreations'	=> 1, //add pages I create to watchlist
	'watchdefault'		=> 1, //add pages I edit
	'watchmoves'		=> 1, //add pages I move
	'watchdeletion'	=> 1, //add pages I delete
);

You’ll be able to change registered user options by running the UserOptions.php maintenance script in [[Special:MaintenanceShell]] extension page.

User rights

In LocalSettings.php is defined what right is needed to do what operation. You probably want to add those permissions:

# Disable reading by anonymous users
$wgGroupPermissions['*']['read'] = false;
 
# But allow them to read these pages:
$wgWhitelistRead =  array ( "Main Page", "Special:Userlogin", "Help:Contents");

# Prevent new user registrations except by sysops
$wgGroupPermissions['*']['createaccount'] = false;

Basically there are 4 groups: anonymous users (cannot read), registered users (cannot delete content nor protect pages), sysops (cannot change user rights) and bureaucrats (those who manage users’ rights).

You could add some extra groups and define new group permissions and new content restrictions. The page [[Special:ListGroupRights]] lists every group with its associated rights.

For example if you want to restrict some categorized pages and a whole namespace, you will write something like below:

## Extension:SimpleSecurity
$wgSecurityUseDBHook = true; # Add this to enable the experimental DB hook for stronger security
include("$IP/extensions/SimpleSecurity/SimpleSecurity.php");
$wgSecurityRenderInfo = true; 
$wgSecurityAllowUnreadableLinks = false;
$wgSecurityExtraGroups = array(
     'groupA' => 'Top Managers group',
     'groupB' => 'Marketers group'	
);
$wgPageRestrictions['Category:Market']['read'] = array('groupA', 'groupB');  //Pages that are categorized into Market pages
$wgPageRestrictions['Category:Market']['edit'] = array('groupA', 'groupB');  //are restricted to group A and B, 
$wgPageRestrictions['Category:Market']['move'] = array('groupA', 'groupB');  //users not belonging to any group cannot read them.
$wgPageRestrictions['Namespace:Private']['read'] = 'groupA'; //Pages in Private namespace (Private:Pagename)
$wgPageRestrictions['Namespace:Private']['edit'] = 'groupA'; //are restricted 
$wgPageRestrictions['Namespace:Private']['move'] = 'groupA'; //to users belonging to group A.

Create user accounts

Once you’ve defined the default user options you can create accounts to register wiki-users. You should start to register users that will have some administration rights, so that they could manage other users by themselves. Go to [[Special:UserLogin]], click on “create an account”, fill in username and email and use the “by e-mail” button. User will receive a temporary password and will be asked to change it at their first connection.

Figure 4 - registration form accessible through [[Special:UserLogin]]

Notice that if the network administrator has installed an LDAP authentication or a confirm account creation by bureaucrat, user registration will be managed differently. In the second case it is up to users to ask for their account creation; and to bureaucrats to confirm or not. Check Special:Version to see if those extensions are installed or not.

Figure 5 - Bureaucrat report to confirm account requests; using a database extension

Assign user rights

Go to [[Special:UserRights]], to give extra rights to users, such as bureaucrat rights for managers and sysop rights for pro-active users.

Figure 6 - assignment of Bureaucrat rights to managers through [[Special:UserRights]]

Extensions

See Category:Corporate Must-have extensions

Look at the /extensions directory. Those are extensions you can add to LocalSettings.php to make them available on the wiki. Check the special page Special:Version which lists every installed extensions.

At the moment I write this document (June 2009) some useful extensions are missing in the repertory fulfilled from MediaWiki SVN, such as:

MaintenanceShell
Freemind
SpecialUploadLocal
Calendar
Events
TopTenPages...

You can download those missing extensions from MediaWiki and add them manually to /extensions directory through ftp.

The main extensions for enterprise use are listed above, comment the unwanted extensions.

################ Extension Chapter of LocalSettings.php
#
# MediaWiki Extensions
#
############ See http://www.mediawiki.org/
require_once( "$IP/extensions/OpenSearchXml/OpenSearchXml.php" ); # Extension:OpenSearchXml
$wgEnableMWSuggest = "true"; //search suggestions & highlight:
$wgAdvancedSearchHighlighting = "true";
$wgSearchHighlightBoundaries = "true";
require_once( "$IP/extensions/ParserFunctions/ParserFunctions.php" ); # Extension:ParserFunctions
require_once('extensions/Cite/Cite.php'); # Extension to allow use of footnotes
require_once("$IP/extensions/embed_document.php"); # Embed document extension.
require_once("{$IP}/extensions/CategoryTree/CategoryTree.php"); 
$wgCategoryTreeSidebarRoot = "Main"; // Is category:Main existing ?
//require_once( "$IP/extensions/FCKeditor/FCKeditor.php" ); # Extension:WYSWYG FCKeditor //$wgFCKEditorExcludedNamespaces
require_once("$IP/extensions/CharInsert/CharInsert.php"); # Extension:CharInsert: Edit tools below edit box
require_once( "{$IP}/extensions/DynamicPageList/DynamicPageList2.php" );
require_once("$IP/extensions/GroupPermissionsManager/GroupPermissionsManager.php");
//include('extensions/FreeMind.php');
require_once("$IP/extensions/Collection/Collection.php");
require_once( "$IP/extensions/Gadgets/Gadgets.php");
require_once("extensions/SubPageList3/SubPageList3.php"); //<splist/>
require_once($IP.'/extensions/InputBox/InputBox.php'); // <inputbox>
require_once("$IP/extensions/SyntaxHighlight_GeSHi/SyntaxHighlight_GeSHi.php");
//require_once("extensions/articletocategory.php"); #Add article to cat. box
require_once("$IP/extensions/ImageMap/ImageMap.php");  // clickable image map
//require_once 'extensions/SpecialUploadLocal/SpecialUploadLocal.php';
// $wgUploadLocalDirectory = $IP.'/extensions/SpecialUploadLocal/images'; //// need an ftp access to extensions folder
require_once( "{$IP}/extensions/Contributors/Contributors.php" );
require_once('extensions/Interwiki/SpecialInterwiki.php');
$wgGroupPermissions['*']['interwiki'] = false;
$wgGroupPermissions['sysop']['interwiki'] = true;
require_once( "$IP/extensions/ContributionScores/ContributionScores.php" );
 $wgContribScoreIgnoreBots = true;          // Exclude Bots from the reporting - Can be omitted.
 $wgContribScoreIgnoreBlockedUsers = true;  // Exclude Blocked Users from the reporting - Can be omitted.
 $wgContribScoreDisableCache = false;       // Set to true to disable cache for parser function and inclusion of table
 //Each array defines a report - 7,50 is "past 7 days" and "LIMIT 50" - Can be omitted.
 $wgContribScoreReports = array(
    array(7,50),				// Last 7 days, top 50 users
    array(14,50),				// Last 14 days, top 50 users
    array(21,50),				// Last 21 days, top 50 users
	array(30,50),				// Last 30 days, top 50 users
    array(0,50));
require_once( "$IP/extensions/UsageStatistics/SpecialUserStats.php" );
 $wgUserStatsGoogleCharts = 1;	// default 0 is using GNUplot tool if installed on server
## categorization extensions
// require_once( 'extensions/CategorySuggest/CategorySuggest.php");
// require_once( 'extensions/SelectCategory/SelectCategory.php' );
## Events or Calendar extensions
//include("extensions/events/Events.php");
//include("includes/SpecialEvents.php");
#require_once("$IP/extensions/Calendar/Calendar.php");
# $wgExtraNamespaces[106] = "Calendars";
# $wgExtraNamespaces[107] = "Calendars_talk";
# $wgNamespacesWithSubpages[106] = true;
# $wgNamespacesWithSubpages[107] = true;
//require_once( "$IP/extensions/TopTenPages.php" );
$wgGroupPermissions['bureaucrat']['maintenanceshell'] = true; # maintenanceShell permission
require_once("$IP/extensions/MaintenanceShell/MaintenanceShell.php"); // this line must remain last

Extra namespaces

See Manual:Namespace

$wgExtraNamespaces[100] = "Portal";
$wgExtraNamespaces[101] = "Portal_talk";
$wgNamespacesWithSubpages = array_fill(0, 200, true); //every NS has subpages
$wgNamespaceAliases = array(
        'U' => NS_USER,
        'P' => 100    // P:pagename => Portal:pagename
    );

Optional tasks:

Those tasks do not need any ftp access and may be performed by pro-active users with sysop rights.

Add some extra-edit buttons

Manual: http://www.mediawiki.org/wiki/Manual:Custom_edit_buttons

[[MediaWiki:Edittools]] to add some edit tools below the edit box.

[[MediaWiki:Commons.js]] to add some extra-buttons to the editbar above the editbox.

Example:

if (mwCustomEditButtons) {
 
   mwCustomEditButtons[mwCustomEditButtons.length] = {
     "imageFile": "http://***/w/images/e/e9/Button_headline2.png",
     "speedTip": "level 3 headline",
     "tagOpen": "=== ",
     "tagClose": " ===",
     "sampleText": "Sub-headline text"};
}

Import JavaScript and CSS style sheets

Customize MediaWiki messages

[[Special:AllMessages]] Lists every MediaWiki messages.

Import some basic content such as templates

Teach users how to use the wiki

Do not believe that users will find how to contribute on the wiki; even if you’ve written a help page, you should teach them how to navigate, edit and follow-up the wiki.

Do some maintenance tasks

Maintenance tasks for every user

Some special pages list what maintenance is needed. They are listed in [[Special:SpecialPages]] in the “Maintenance reports” section, as shown below. A regular task is to categorize uncategorized content:

Maintenance tasks for Administrators

Administrators have the right to delete files and pages, so they should sometimes check for unused content to delete it. Notice that deleted content can be restored therefore you can give sysop rights to every pro-active user without any danger.

Maintenance tasks for Bureaucrats

Bureaucrats can execute some maintenance scripts through [[Special:MaintenanceShell]] extension page. For example they can change registered user options by running the UserOptions.php maintenance script.

Importing first-level content

a Corporate-ready dump is needed there, with basic templates, javascripts and css.