Manual:Running MediaWiki on Windows

Running MediaWiki

This page will give you information about installing MediaWiki on a Microsoft Windows system.

Introduction
Due to the fact that it is coded in PHP (a cross-platform language) it is quite simple to get MediaWiki running on Windows. This guide currently only supports the most recent versions of MediaWiki (the 1.7.x series) in order to avoid having to explain the fixes for bugs in every previous version.

If you already have a working internet-development environment which runs PHP, Apache (or IIS, however this guide focuses on using the Apache HTTP server. You can see Installing MediaWiki on Windows Server 2003 SP1 for instructions on how to use IIS to run MediaWiki instead.) and MySQL you may skip on to the sections about Optional Software.

If you are new to Apache/PHP or MySQL then it may be worth noting that these applications are only supported by their developers on Windows 2000 and above.

Required software

 * Support software
 * MySQL
 * Web Server: Apache or IIS
 * PHP 5.x
 * Windows 2000/XP/2003
 * Mediawiki – the code itself

Optional utilities

 * Texvc (needed for rendering Math formulas)
 * PHP optimising software (Zend Optimizer). Cleans up compiled PHP code to make it run 50-100% more efficiently.
 * PHP caching software (Turke Memcache or eAccelerator). Saves the compiled PHP for future use, so it doesn't need to be recompiled, speeding up execution by 100x or so.
 * Image processing software (ImageMagick or GD). Used for format conversion and thumbnails
 * Web page caching software (Squid). Used to store rendered pages for re-use.

Hardware
You will also need some serious hardware for a large database, e.g. the full Wikipedia database, depending on how much demand it will require. Meta-wiki has some information on how many clients its clusters support, and their configuration, which can be used to gauge this.

A minimum of 256MB of RAM is recommended.

Choosing a software installation method
MediaWiki is developed under a LAMP (Linux+Apache+MySQL+PHP) environment. It is recommended that you use as much of this stack as possible under Windows if you want MediaWiki to run smoothly. Therefore, IIS is not recommended. Instead, using the "AMP" portion of the "LAMP" stack is more likely to succeed.

Although these products are not that difficult to configure under Windows, it can be extremely difficult to install and configure Apache+MySQL+PHP one product at a time if completely new to apache/mysql/php. Under such circumstances it is highly recommended to look for a LAMP or WAMP pre-made combination which can just be installed and used. These will save you 99% of the trouble of configuring each package manually. The down-side is that some of these are trimmed down or modified versions which makes it hard to upgrade individual components, and other ones are seriously out of date.

You can install the support components individually, or all together as a package. A step by step guide to installing mediawiki with separate packages for Apache 2, mySQL 4 and PHP 5, on windows, can be found at Newcomers guide to installing on Windows. Some important information as of December 2004 to help select which software to use can be found in that article too, as well as a guide to issues and sample config files.

Currently, the best example of an up-to-date "all-in-one" package for Windows is the DeveloperSide.NET Web-Server Suite and the Saint WAMP sourceforge. Others include:


 * EasyPHP
 * Xampp
 * Uniform Server
 * IBServer (not recently updated?)
 * FoxServ (not recently updated?)

See also: Wiki on a stick.

Installing Apache, PHP and MySQL as a Package
Choose a package to download from the list above. Step-by-step instructions are provided for Saint WAMP (ver 3.4), and EasyPHP (ver 1.8). Saint is the more up to date of the two packages, however EasyPHP is quite a bit simpler to use. NOTE: Neither one of these options appears to work because both Saint WAMPS and EasyPHP provided PHP4, but the current MediaWiki requires PHP5. For security and other reasons, it is probably better to download PHP5, but another option is to download MediaWiki version 1.4. Even easier is to use the installation at Newcomer's Guide.

Internet Information Services (IIS) Manager Installed
If IIS is installed then there are some considerations. By default IIS and Apache both use port 80, so IIS will need to be uninstalled, disabled or moved to another port.

NOTE: Saint WAMP allows the default port for apache to be changed during the install. If you plan to keep IIS on port 80 and run Apache on a different port then IIS can be left as is.

To change the port IIS runs on:
 * 1) Open IIS Manager [Start -> Administrative Tools -> Internet Information Services (IIS) Manager]
 * 2) Expand Web Sites, right-click on Default Web Site and select Properties
 * 3) On the Web Site Tab change the Port field (example: 8080)
 * 4) Click OK
 * 5) Stop then start IIS to make the change come into effect

Installing Saint WAMP
Once Installed an administration account needs to be created After all this process, open the Window that displays all the services running on your computer (use the Apache icon on the task bar). Check if the TSW-MySQL service is running. If not, start it (right-click -> Start).
 * 1) Run the downloaded Saint WAMP installation package
 * 2) Choose Classic WAMP for the install type
 * 3) Use the default install directory or change it as required
 * 4) The global options can be left as is, you may need to change the port if you are running IIS
 * 5) Python and SSL can be unchecked as they will not be used. Status could be useful.
 * 6) Select the mysqld-nt.exe service as it is optimized for the windows environments
 * 7) Start the Apache Monitor
 * 8) Start the TSW-Contentserver (use the Apache icon on the task bar)
 * 1) Open a Command Prompt [Start -> Run -> Type 'cmd' -> OK]
 * 2) Type cd "\Program Files\TSW\Apache2\bin"
 * 3) Type htpasswd -cmd .htpasswd newusername
 * 4) Enter a new password twice
 * 5) Type copy .htpasswd ..\conf
 * 6) Type y to confirm replacing the file
 * 7) Go to http://localhost/ to test it
 * 8) Check out http://localhost:3000. When prompted use the user account created earlier.

Installing EasyPHP

 * 1) Run the downloaded EasyPHP installation package
 * 2) Use the default install directory or change as required
 * 3) When the install finishs wait, two dialogue boxes should appear on top of the final install screen
 * 4) Click OK on the 'Mise a jour' box.
 * 5) The EasyPHP Dialogue box should show Apache and SQL already started
 * 6) Go to http://localhost/ to test it

Tasks after installation:
 * Go to http://localhost/mysql/ to set root password for MySQL. Note that entering the trailing "/" matters! Select "Show MySQL system variables", "Privileges", then click icon at end of line starting with "root". Scroll down to password entry box and enter.

Configure Apache
The Document Root for Apache should be changed to point somewhere else, preferably on a separate volume. Create a new folder (i.e. D:\www) and then edit the Apache configuration file as follows:


 * First, open the httpd.conf file in the .\apache\conf directory where Saint or PHP is installed

DocumentRoot "D:\www"
 * Then search for DocumentRoot and edit it

<Directory "D:\www">
 * Finally, scroll down and change the '<Directory>' tag (NOT the <Directory /> tag or the </Directory> tag!) to be the same as DocumentRoot (if you installed the Saint WAMP distribution, change the '<Directory htdocs>' tag)

You need to restart TSW-Contentserver for the changes to take effect.

You may want to install Memcache if not already included in your WAMP, and ImageMagick or some other graphical manipulation package. Instructions, and links to some Windows builds, are also given in Newcomers guide to installing on Windows, and the php settings needed are shown in the sample php.ini.

Installing MediaWiki
After successfully installing the underlying software, you can install MediaWiki.


 * 1) Download MediaWiki from sourceforge file list or portal page
 * 2) Uncompress the MediaWiki source tree under the Apache Document Root (Example. D:\www\Mediawiki)
 * 3) Access http://localhost/mediawiki</tt> and configure mediawiki as instructed by the page.
 * In case you have difficulty accessing the database, you might need to do this in mysql:
 * set password for 'root'@'localhost' = password ('new-password');
 * If you get a blank page at this point, and it has not created the "LocalSettings.php" file, please contact someone for assistance (either on one of the IRC channels or mailing lists). Sometimes, just hitting Reload in your browser may solve the problem.
 * If you installed it by hand, you may see this:
 * Warning: dl [ function.dl ] : Not supported in multithreaded Web servers - use extension=mysql.so in your php.ini in {path_to_htdocs}\wiki\install-utils.inc on line 17 Could not load MySQL driver! Please compile php --with-mysql or install the mysql.so module.
 * This means that you have forgotten to configure PHP to use MySQL. Please see your manual or install.txt (under PHP) on how to do this.
 * 1) Move generated .\mediawiki\config\LocalSettings.php</tt> to .\mediawiki\</tt>,  I.e. move it into its parent directory
 * 2) Enjoy your MediaWiki under Windows now: http://localhost/mediawiki

Download & Installation
Download the Apache Web Server MSI installation package from here using the latest 2.0.x binaries (2.2.x is fairly new at the time of writing and is not well supported by binary files for PHP). Currently the latest version of Apache is version 2.0.59 (September 2006)

The installation is fairly simple, however if you do not have Administration privileges on your server you will need to select Port 8080 manual-start installation, as installation of services requires admin privileges.

Configuration
You need to alter the httpd.conf file for apache. It should be located at "C:\Program Files\Apache Group\Apache2\conf" if you used the default installation: LoadModule php5_module c:/php/php5apache2.dll AddType application/x-httpd-php .php .php5 .phtml AddType application/x-httpd-php-source .phps
 * Add these lines at the end of the block of LoadModule lines:
 * You must alter c:/php/ to the location of your php5apache2.dll file (which will be downloaded and configured in the next section). It is recommended not to use a directory with a space.
 * Note: if you are installing Apache 2.2. replace "php5apache2.dll" with "php5apache2_2.dll".

Download & Installation
Download the Windows Binaries of PHP from here. Once you have downloaded the files you simply need to extract the files to the directory you specified in the Apache configuration file. It may also be necessary to place the PHP directory in your PATH if you recieve DLL not found errors.

Rename the file php.ini-recommended to php.ini.

Configuration
Make the following modifications to the php.ini file you renamed above.

Extension Directory

 * Set extension_dir to "./ext"

MySQL

 * Uncomment "extension=php_mysql.dll" (i.e. remove the ';')

GD
You will need to enable the GD library to use thumbnailing. The GD library is contained as an extension in the default download package.
 * Uncomment "extension=php_gd2.dll"

You may now use the services control panel or Apache2 Monitor to restart the Apache 2 server and make sure everything is working.

MySQL Installation
The download link below points to a page with all available versions of MySQL. You will more than likely want to download "Current Release (Recommended)" (which is 5.0 at the time of writing), followed by "Windows Essentials"

While downloading, read the Install Guide using the second link below. Once you've got MySQL set up correctly you can proceed to the installation of MediaWiki.
 * Download
 * Install Guide

Make sure libmysql.dll is in the PATH, either by adding c:\php or the MySQL install directory to the PATH or by copying libmysql.dll to someplace in the PATH (like C:\Windows).

MediaWiki
There are two options
 * Last stable release of the mediawiki software
 * Latest development version.

Stable release

 * Go to http://sourceforge.net/projects/wikipedia/
 * Press Download on the left of "MediaWiki stable release"
 * Save on your disk and extract it to c:\easyphp\www\mediawiki\

Latest release and CVS versions
Often as well as the stable version, there will be a beta of the next version. There may also be an "up to the minute" latest in CVS, not yet released.

These are development versions of MediaWiki and include the latest changes made by the developers. They may work well, or may have serious problems (of any kind, trivial through to major data corruption), so be careful about using a beta or CVS version. Generally use the stable version unless you need the development version to work around a bug you can't avoid, or to gain some key feature or compatibility with latest software, or resolve other issues. Always check the release notes if unsure. If you aren't familiar with computing and don't like to test the latest software, get the stable release.

You can download all versions (stable and development) from CVS, sourceforge, or following links in this meta-wiki. If you want to grab a CVS version ("up to the minute" software) and do not already have a CVS client, you will have to get one and install it. WinCvs is a suitable CVS software for windows and can be found at http://www.wincvs.org. Get MediaWiki from the CVS archives.

Installing
Believe it or not, after all that work, it's fairly simple to install MediaWiki. Head to whereever you extracted your wiki in your browser (for example, if you extracted it to \htdocs\wiki head to http://localhost/wiki) and click the link to begin set up. You should know all the details you need to fill in here, however note that it is wise to disable all forms of email communication if you did not configure PHP's outgoing SMTP.

Notable differences in Windows' LocalSettings.php
For example on linux you may have: $IP = "/var/www/apache2-default/wiki"; But on windows this is: $IP = "D:\\Program Files\\Apache Group\\Apache2\\htdocs\\mediawiki-1.5.6";
 * Windows file paths in php are different than *nix style paths.

Content
For each wiki three sets of page data are produced as dumps in XML format. The download site shows the status of each dump, if it's in progress, when it was last dumped, etc. With mwdumper these dumps can be filtering and converting to produce output as another XML dump as well as SQL statements for inserting data directly into a database in MediaWiki's 1.4 or 1.5 schema.

''See more: Data dumps

Diffutils
Diffutils (which contains diff3) can be downloaded from here, and file from here.

To activate the use of diffutils within MediaWiki, you have to ignore the fact that they won't be found during installation (they may actually be found if you install diff into your path) and open up LocalSettings.php to make the following changes: $wgDiff3 = "/usr/bin/diff3"; becomes $wgDiff3 = "C:/Program Files/GnuWin32/bin/diff3.exe"; and replace: $wgMimeDetectorCommand= "file.exe -bi"; #use external mime detector (linux) with $wgMimeDetectorCommand= "C:/Program Files/GnuWin32/bin/file.exe -bi"; #use external mime detector

Please note that you have to replace "C:/Progra..." with the actual location where you installed the tools to.

ImageMagick

 * Note: PHP now comes with GD enabled by default. This will work for thumbnailing, and will not require any configuration or modification.

The "Q8" ImageMagick releases use 8 bits per channel, while the "Q16" releases use 16 bits per channel. In order to make image thumbnailing work, you will need to open includes/Image.php, locate the line that starts with, and remove the escapeshellarg function, then do the same to the next line, so that the command variable builds like this:

In addition, check to be sure that the  in localsettings.php points to (your imagemagick folder path)/convert.exe
 * Note:
 * use the .exe extension! It won't work, if ommitted.
 * use a path without spaces as install path for ImageMaick or use the short name of the path.

Another way to make this work is to add the ImageMagick path to your Windows PATH variable, and simply setting the  in LocalSettings.php as follows (note that you must still modify Image.php as shown above):

$wgImageMagickConvertCommand = "convert.exe";

Make sure that the Internet Guest Account (Usually IUSR_MACHINENAME) has Read & Execute rights to the ImageMagick bin directory. Without this you might see an PHP shell execution error similar to what happens when it can't find the convert.exe file.


 * Is this up to date in 1.7.1 Image.Php looks like this

$cmd =  $wgImageMagickConvertCommand. " {$quality} -background white -size {$width} ". ($this->imagePath). // Coalesce is needed to scale animated GIFs properly (bug 1017). ' -coalesce '. // For the -resize option a "!" is needed to force exact size, // or ImageMagick may decide your ratio is wrong and slice off // a pixel. " -resize ". "{$width}x{$height}!" . 		" -depth 8 ". ($thumbPath). " 2>&1";


 * Note: You may also have to delete the content of $wgUploadPath/thumb directory if
 * You have installed ImageMagick later than the first thum image created, and
 * ?action=purge has no affect on caching (like i had in MediaWiki 1.8.2)

Thumbnail creation did not work for me. Here's what worked after some debugging:
 * Make sure that in LocalSettings.php you give the absolute path to ImageMagick.
 * In Image.php replace the lines given above (i.e. $cmd=$wgImageMagickConvertCommand etc) with:

$cmd =  $wgImageMagickConvertCommand. " {$quality} -background white -size {$width} ". str_replace( chr(47),chr(92), $this->imagePath). // Coalesce is needed to scale animated GIFs properly (bug 1017). " -coalesce ". // For the -resize option a "!" is needed to force exact size, // or ImageMagick may decide your ratio is wrong and slice off // a pixel. " -thumbnail {$width}x{$height}!" .                   " -depth 8 ". str_replace( chr(47),chr(92), $thumbPath). " 2>&1";                   //$fp = fopen("myoutputlog.txt", "w");fwrite($fp, $cmd);fclose($fp);

Char 47 is the '/', while char 92 is the '\' (look at http://www.asciitable.com/). So instead of using the function wfEscapeShellArg that just replaces backslashes and double quotes, I transformed the / into \ (literal characters). I think the caveat here (which allows one to get away without using wcEscapeShellArg) is that you cannot have any blank spaces in your paths to images. The last commented line will produce a file "myoutputlog.txt" that contains the string that actually gets executed to produce the thumbnails.

Mathematics Support
MediaWiki uses a program called texvc</tt> to render math expressions into nice looking PNG.

Getting it up and running on Windows can be somewhat troublesome, as it was developed on and for linux, so it is recommended to use one of the other options found below. The first alternative solution has the highest success rate, assuming you have the correct software installed.


 * Note: Maths support is strictly optional. Your wiki will run fine without it, although you'll need it if you want to enter formulae which are more complicated than a simple subscript.

What you'll need for all solutions:
 * Latex and dvips (using the Miktex package for Windows)
 * GhostScript for its Postscript libraries (Caution! in newer versions the gswin32c.exe has to be renamed or linked to gs.exe)
 * ImageMagick binaries for windows

Install these packages to a short directory, preferably one which does not contain spaces. C:\texmf seems to be the most common. You may have to manually add these packages to the path.

Once you have these programs installed, check if the commands gs</tt>, latex</tt>, dvips</tt> and convert</tt> (not the built-in windows-tool!) are work by typing them at the cmd prompt. (Note that you may have to use ctrl-c to quit them as they take input from the console if no arguments are supplied). If they're not found you'll have to modify your PATH variable and restart your operating system. (For some reason Apache or PHP doesn't update its PATH until reboot, a service stop-start does not work)

Building texvc on Windows
This is a quick and dirty hack to make texvc work under Windows.

What you'll need:
 * the texvc</tt> sources (included in the math directory of the MediaWiki distribution)
 * a Make utility (for example mingw32-make, included in MinGW)
 * an OCaml compiler

If you want to skip the OCaml compilation process you can use one of the following precompiled binaries:


 * Mediawiki 1.4.5 + Cygwin (built by User:Connelly)
 * Mediawiki 1.4.7, Native Win32 binary (built by User:Fernando, based on the final render.ml</tt> listed below)
 * Mediawiki 1.5.5, built like described below

However please note that most of these binaries are now out of date.

If you use a pre-compiled binary you can skip this section, however you will still have to make the edits to Math.php and LocalSettings.php as described below.

Before we compile texvc, we need to modify some of the files to reflect certain differences between Windows and Unix/Linux (mainly filesystem differences).

Modify math\render.ml</tt> so it looks like the file found here.

If you have Visual C++ and MASM installed, make the optimized texvc.exe</tt> by running the make utility in the math directory. If you do not have Visual C++ and MASM, make the bytecode version texvc.bc</tt> (by typing for example mingw32-make texvc.bc</tt> in the math directory) and rename it to texvc.exe</tt>.

Configuring Mediawiki to use texvc
1. Copy the texvc executable into your base MediaWiki directory.

2. In /includes/Math.php</tt> replace the following: wfDebug( "TeX: $cmd\n" );
 * with the following:

$cmd=str_replace("'","\"",$cmd); wfDebug( "TeX: $cmd\n" );

because in Windows single quotes do not work as quote markers in command line.

In <tt>LocalSettings.php</tt>, uncomment or insert: $wgUseTeX= true; to activate texvc functionality.

If you are using MediaWiki with IIS then you should replace "REQUEST_URI" with "SCRIPT_NAME" in all files.

And finally, set the <tt>texvc</tt> executable path to the root path of Wiki, by inserting this line in <tt>LocalSettings.php</tt>: $wgTexvc = "texvc.exe"; # Location of the texvc binary

Let me know how this works for you in the discussion page.

Alternative Solution
You may find compiling texvc to be very complicated or simply not working. Here is another solution (Using LatexRender, thanks to Benjamin Zeiss, completed by MetaSharp). The directories given here are examples, use your owns.

Installation
latex dvips convert (not the microsoft convert)
 * install MikTeX in D:\wikitex\miktex
 * install ImageMagick in D:\wikitex\imagick
 * open a command line (start -> execute -> cmd.exe)
 * verify that the following commands are working:

Settings
(your wiki directory = $) $wgUseTeX= true; $wgImageMagickConvertCommand   = 'D:\wikitex\imagick\convert.exe'; $wgImageMagickIdentifyCommand  = 'D:\wikitex\imagick\identify.exe'; #Tex $wgLaTexCommand                = 'D:\wikitex\miktex\miktex\bin\latex.exe'; $wgDvipsCommand                = 'D:\wikitex\miktex\miktex\bin\dvips.exe';
 * replace the file $/includes/Math.php with this one
 * uncomment or insert in $/LocalSettings.php:
 * insert in $/LocalSettings.php:
 * 1) ImageMagick
 * reboot if needed so that paths variables are updated for your services too

Verifications
$$\sqrt{2}$$
 * and voilà ;) Now you can try in the sandbox to see whether it works. Enter something like this and hit preview to see if it works:
 * the folders "math" and "tmp" should have been created in the "images" folder automatically.

Troubleshooting
You might experience some problems with formulas not being displayed if you are not logged in. In such a case comment out the 3 following lines in $/LocalSettings.php: $wgMathPath        = "{$wgUploadPath}/math"; $wgMathDirectory   = "{$wgUploadDirectory}/math"; $wgTmpDirectory    = "{$wgUploadDirectory}/tmp"; like this: or just suppress them. Everything should be working fine now.
 * 1) $wgMathPath        = "{$wgUploadPath}/math";
 * 2) $wgMathDirectory   = "{$wgUploadDirectory}/math";
 * 3) $wgTmpDirectory    = "{$wgUploadDirectory}/tmp";

Extra Info
With above method make sure you install
 * GhostScript for its Postscript libraries (Caution! in newer versions the gswin32c.exe has to be renamed or linked to gs.exe)

Not explicitly mentioned in initial instructions. I had to rename gswin32c.exe to gs.exe and cut gs.exe out of its folders to the c:/ root. Use cmd.exe to check all are working (latex, dvips, convert and gs) by running from C:/. If any fail to be found then reposition their path (closer to c:/) until they work

Alternative Solution with dvipng
The file: Help:Running_MediaWiki_on_Windows/math-dvipng.php

This is a hack of Alternative Solution using dvipng instead of dvips + gs + convert. It does not require ghostscript or imagemagick. It doesn't check for correct image dimensions. The dvipng parameters are: -q -Q 8 -T tight -bg transparent -D 120 filename.dvi -o filename.png. It uses 8x8 antialiasing, because dvipng renders equations a little differently (not as sharp), and the 8x8 antialiasing seemed the best (see the file's talk page for details). If you want full 8-bit transparency, use Transparent instead of transparent.

0) Make sure you have latex and dvipng (e.g. MikTeX)

1) Copy the file FROM EDIT/SOURCE as includes/Math.php (without the pre and nowiki lines, of course)

2) Add the following to the end of LocalSettings.php (latex.exe and dvipng.exe without path suffice if you have them in your PATH):

$wgUseTeX	=	true; $wgLaTexCommand	=	'insert_path_here/latex.exe'; $wgDvipsCommand	=	'insert_path_here/dvipng.exe';

3) Try it. My test is usually $$E=mc^2$$ :)


 * Comment: This works for me except the formulas have small errors, like if I do $$x+y+z-q$$, the PNG gets rendered without the minus sign. However, if I put whitespace between the formula and the closing tag, everything works correctly. I suspect there is an "off by 1" parsing error somewhere. This is with MediaWiki 1.9.3, Windows 2003 Server, PHP 5.2.1, MiKTex 2.5, OCAML 3.09.3 (MinGW-based native Win32 port). Maiden taiwan 03:16, 6 March 2007 (UTC)

Next page: Running MediaWiki on Mac OS X >