Manual:Installation

This page guides you through the process of installation of the latest stable version on Linux. There is another page for installation from Subversion. The 1.6 series is the last to support versions of PHP earlier than PHP 5.

MediaWiki on Windows/Apache here: http://www.mediawiki.org/wiki/Manual:Simple_Windows_Apache_Installation

There are also guides for installing MediaWiki on Windows and IIS, which is a little harder:
 * Manual:Installing MediaWiki on Windows XP -> Manual:Installing MediaWiki on Windows XP - MediaWiki 1.9.2
 * Manual:Installing MediaWiki on Windows Server 2003
 * see also other guides:

Finally, there are several pages that include instructions on how to install MediaWiki on different operating systems. See Manual:OS specific help.

MediaWiki can be difficult to install for the average computer user who does not have experience with Apache, PHP and MySql. Most users who wish to use wiki software may benefit from using a free wiki host (see a list of wiki hosts on Wikibooks).

Minimum system requirements
The recommended minimum settings is 256MB of RAM for a single-computer website, although this will not suffice for a busy public site. Some users have reported running MediaWiki on computers with as little as 48MB of RAM.

Prerequisites
Before you can install MediaWiki, there are four prerequisite components you must install. When you install these, remember to read the associated documentation. If your website is hosted for you then contact the server administrators or hosting company to ensure these are installed.


 * 1) A web server. Most installations use the Apache web server, available at the official download page.
 * 2) * MediaWiki also apparently runs under IIS 6.0, Cherokee and lighttpd.
 * 3) * Sun has some installation instructions for running Mediawiki on the Sun Java System Web Server 7.0.
 * 4) A recent version of PHP, the programming language in which MediaWiki is written. This is available from the official download page. As of version 1.7 PHP 5.x is required -- PHP 4.x is not supported from this version onwards.
 * 5) * See PHP config for compiling options
 * 6) * Some Linux servers may also require the equivalent MySQL package and PHP session management package; see the documentation for the operating system.
 * 7) * When installing on windows using the Microsoft installer, add the extension for your database of choice (MySQL or Postgres) to the features to be installed.
 * 8) * If your Apache server has the Hardened PHP patch, you may need to edit several variables in your /etc/php.ini file if you wish to have Wiki pages with large amounts of content. In particular, consider the settings for varfilter.max_value_length, hphp.post.max_value_length, and hphp.request.max_value_length.  The default settings may limit your pages to less than 10k or 64k in size.
 * 9) * Many people report blank pages in recent versions after submitting articles to their new wiki. A likely cause is the memory limit in default php installations (usually 8 MB). Please check your PHP and/or Apache error logs. To modify this setting edit  and increase the "memory_limit" setting. For example to  raise it to 20 MB replace the existing text with " ". Make sure to restart your Apache server after you have changed this value.
 * 10) A MySQL database server (4.0 or later), which will be used to store all the text and data. This is available from the official download page.
 * 11) * As of version 1.8, Postgres is also supported. It should be noted that support for Postgres is new and not as well tested as the MySQL equivalent.
 * 12) MediaWiki itself, which is available from the official download page. Development versions are available from the Sourceforge.net project page.

Download and uncompress
Download MediaWiki to your local computer and uncompress the files, so that you can see the files and folders. This is usually done with software such as 7-Zip (open source software), WinZip, WinRAR or IZArc on Windows. On Linux, you can untar the file using this command: tar xvzf mediawiki-*.tar.gz

Upload
Upload the files to a public directory (usually public_html/wiki) using an FTP client such as FileZilla (Open Source Software, Windows) or Cyberduck (OSX). If you are using a Unix server and have access to the httpd.conf, make a symbolic link.

Change the permission settings for the "config" subdirectory so that it is writable by the webserver. If you are using FileZilla, right-click on the directory, select "attributes...", and check "Write" under "Owner". If it prompts you for a number instead or you are using a command-line interface, use 755 (Use 777 on Linux except for RedHat Linux). Alternately, you may be able to change permissions using a "control panel" provided by your web host.

Depending on the server configuration, in some cases you have to check all boxes (777) in FileZilla, to be able to run the install-script of MediaWiki.

Troubleshooting
chown -R apache:apache /var/www/html/mediawiki/*
 * Case: If you are using a different FTP client than FileZilla, be sure to configure the client to not force uppercase or lowercase filenames on the webserver. MediaWiki filenames are case-sensitive.
 * Incomplete uploads: The pack includes a lot of files, spread over dozens of directories. Be careful when uploading. If the transfer is interrupted, you might have missing or incomplete files. You may have to retry your upload several times, especially if you have an unreliable connection.
 * 403 Forbidden: If your webserver produces a "403 Forbidden error" page, then make sure your Apache httpd.conf have Options FollowSymLinks to allow symbolic links and that each directory leading up to your linked directory have +x permission for user running httpd.
 * Internal error: If your webserver produces a "500 Internal Error" at the beginning of the install process, you may need to change the permissions on the config folder to 755.
 * SELinux: Linux distributions which support SELinux ('Security Extensions') are becoming more widespread. On such systems, PHP scripts will still be unable to write to the config directory, after you have set the normal file permissions. You will also need to use the 'chcon' command to change the SELinux file type. See SELinux.
 * If you are running the Mediawiki software on a free site that requires banners or prefix advertising, this may cause MediaWiki not to work, and appear to only generate empty pages beyond the banner advertising. A fix for this will need to be done in the future.  In the interim the only option is to find a paid hosting site.  This may be considered a bug, and is being reported.
 * Config directory unwritable: If you have changed the permissions for the config directory and still get an unwritable error try changing the owner to apache.
 * If you're running the MediaWiki on Debian with Apache2 and PHP5, and have problems connecting to MySQL, try uncommenting: ';extension=mysql.so' in the '/etc/php5/apache2/php.ini' file.

Create a database
Currently, you must use either MySQL or Postgres to store the actual contents of your wiki.

MySQL
The MySQL database server stores the text and data of your wiki.


 * If you know the root password for your database server, (the password for the user called "root") the MediaWiki setup script can automatically create a database and an account to access it. You can skip to the Run the installation script section below.
 * If you don't know the root password for your MySQL server, for example if you don't have the password because you are using a shared host, you need to create a MySQL database and a user before installing MediaWiki. You can do this using various control panels such as PhpMyAdmin, which are often available from shared hosts, or you may be able to use ssh to login to your host and type the commands into a MySQL prompt. See the corresponding documentation. Alternatively, contact your host provider to have them create an account for you


 * 1. Download and install MySQL 5.0. It should put itself in /usr/local/mysql
 * 2. Check and see if the database server is running ("/usr/local/mysql/bin/mysqladmin status"), If not, sudo /usr/local/mysql/bin/safe_mysqld &. (For Fedora Core 5, use /usr/bin/mysqld_safe)
 * 3. Set a password for the "root" account on your database server. /usr/local/mysql/bin/mysqladmin -u root password yourpassword
 * 4. Set up a user in MySQL for your Wiki--do this in your terminal: /usr/local/mysql/bin/mysql -u root -p mysql
 * 5. This starts up the MySQL command line client. Now, do this in the client:

create database wikidb; grant create, select, insert, update, delete, lock tables on wikidb.* to 'wikiuser'@'localhost' identified by 'password'; flush privileges; \q

If your database is not running on the same server as your web server, you need to give the appropriate web server hostname -- mediawiki.example.com in my example -- as follows: grant create, select, insert, update, delete, lock tables on wikidb.* to 'wikiuser'@'mediawiki.example.com' identified by 'password';

Postgres
If you are using Postgres, you will need to either have a database and user created for you, or simply supply the name of a Postgres user with "superuser" privileges to the configuration form. Often, this is the database user named postgres.

The database that MediaWiki will use needs to have both plpgsql and tsearch2 installed. The installer script will try and install plpgsql, but you may need to install tsearch2 yourself. (tsearch2 is used for searching the text of your wiki). Here's one way to do most of the setup. This is for a Unix-like system, and assumes that you have already installed the plpgsql and tsearch2 modules. In this example, we'll create a database named wikidb, owned by a user named wikiuser. From the command-line, as the postgres user, perform the following steps.

createuser -S -D -R -P -E wikiuser (then enter the password) createdb -O wikiuser wikidb createlang plpgsql wikidb

Adding tsearch2 to the database is not a simple step, but hopefully it will already be done for you by whatever packaging process installed the tsearch2 module. In any case, the installer will let you know right away if it cannot find tsearch2.

The above steps are not all necessary, as the installer will try and do some of them for you if supplied with a superuser name and password.

For installing tsearch2 to the wikidb database under Windows, do the following steps: 1. find tsearch2.sql (probably under .\PostgreSQL\8.x\share\contrib) and copy it to the postgresql\8.x\bin directory; 2. from a command prompt at the postgresql\8.x\bin directory, type "psql wikidb < tsearch2.sql -U wikiuser"; 3. it will prompt you for the password for wikiuser; That's it!

point 2. seems only to work on windows, cause on debian linux 4.0 (etch) only user postgres is allowed to use language c. so there it must be called by:

su - postgres -c psql wikidb < tsearch2.sql

afterwards you must grant select rights to wikiuser to the tsearch table's and insert the correct locale.

su - postgres psql -d wikidb -c "grant select on pg_ts_cfg to wikiuser;" psql -d wikidb -c "grant select on pg_ts_cfgmap to wikiuser;" psql -d wikidb -c "grant select on pg_ts_dict to wikiuser;" psql -d wikidb -c "grant select on pg_ts_parser to wikiuser;" psql -d wikidb -c "update pg_ts_cfg set locale = current_setting('lc_collate') where ts_name = 'default' and prs_name='default';"

Run the installation script
Use your browser to visit the wiki directory on your webserver to run the installation script. If you are running a distribution with SELinux, e.g. Fedora Core, be sure to set the context on the installation directory correctly e.g.: ls -aZ chcon -R system_u:object_r:httpd_sys_content_t wiki If you installed into public_html/wiki, this will probably be something similar to  http://www.yourdomain.com/wiki . Depending on how you uploaded the files, you may need to visit  http://www.yourdomain.com/wiki/config </tt> instead. Follow the installation instructions on the installation script page. Refer to the following table if you're uncertain what to enter.

Click the "Install!" button.

If you are using a hosting service, the database name and database username may have an extra prefix (normally the userid given by your hosting provider). For example, if you have created a database named db01 with username u01 and your userid is ocom (given by your hosting provider), you should enter the database name and database username as ocom_db01 and ocom_u01 respectively.

If you get a " 'user_password' can't have a default value" error, ensure that MySQL is not running in strict mode.

If you selected "experimental UTF-8", there may be a MySQL error of the type "specified key was too long". One way of solving that is to edit the file maintenance/tables.sql</tt> so that the table causing the problem uses shorther keys. (Depending on MediaWiki version, there might be other tables.sql</tt> files you also need to change; for example, maintenance\mysql5\tables.sql</tt> in 1.6.10 if you use MySQL 5.)

For example, if you find the error message: PRIMARY KEY job_id (job_id), KEY (job_cmd, job_namespace, job_title) ) TYPE=InnoDB " failed with error code "Specified key was too long; max key length is 1024 bytes (localhost)".

Then you should find table "job" in tables.sql and replace KEY (job_cmd, job_namespace, job_title)</tt> with something like KEY (job_cmd(160), job_namespace, job_title(160))</tt>.

(The point is that the total length of all the fields in every KEY declaration should be less then the max key size mentioned in the error message, even when you multiple the varchar fields with three (because a UTF-8 character takes up 3 bytes). In the example, job_cmd is varchar(255), job_namespace is int, job_title is varchar(255), thus the total key length in KEY (job_cmd, job_namespace, job_title)</tt> is 3*255 + 4 + 3*255 = 1534, which is greater than 1024. After replacing, 3*160 + 4 + 3*160 = 964, which should be okay.) After fixing tables.sql</tt>, you should drop all the tables you have made before, and then run the install script again (just reload the page with the error message, that way you don't have to enter everything again). You might get this error for several tables - job and page_restrictions are some that can be affected.

See also MediaWiki bug 4445.

Missing table prefix
A MySQL installation of MediaWiki 1.8.2 on a shared host failed to display the database table prefix input box. The form field was generated in the configuration page with no-display attributes. If you experience this problem, the addition of the //</tt> characters to config/index.php</tt> as shown below will cause this field to re-materialize. This input box is not needed unless more than one MediaWiki instance is being installed into a single database, so most installations will not need to do this, whether the field is present or not. <?php // database_switcher('mysql'); ?> <?php aField( $conf, "DBprefix", "Database table prefix:" ); ?>

Note: the problem persists in MediaWiki 1.9.3. Subsequent experience suggests that the optional database portion of the installation form (which comes up with a yellow background for MySQL options, and blue for Postgres options) can be activated--if it does not appear on its own--with extra clicks on the database selection radio buttons (observed to work under Firefox 1.5)

Local settings
After the setup script has finished running, a file called LocalSettings.php</tt> is created in the "config" directory. This file contains all the information needed by MediaWiki to run.


 * 1) Move this file to the main wiki directory (if you installed MediaWiki to public_html/wiki</tt>, move it there).
 * 2) Set stringent permissions on the LocalSettings.php</tt> file. ( chmod 600 and chown )
 * 3) Delete the "config" directory.

Advanced configuration
For help with more advanced technical configuration, see m:Help:Configuration and m:Help:Administration.

For a brief overview that addresses the empty help pages and text and layout modification, see m:Help:Installation-Software_Configuration.

Uninstallation
Removing MediaWiki entirely can be accomplished in two steps: removing the directory where MediaWiki was installed, and dropping the MediaWiki database from MySQL or Postgres.

For example, if you installed MediaWiki to /var/www/mediawiki-xyz, you might do

rm -rf /var/www/mediawiki-xyz

MySQL
To remove the MySQL database holding your wiki, use the mysql utility to interactively connect to MySQL as a user with adequate permissions, then issue the following command at the mysql> prompt:

DROP DATABASE wikidb;

Postgres
To remove the Postgres database holding your wiki, run the following command:

dropdb wikidb

or connect to the database as a user with the correct permissions and issue:

DROP DATABASE wikidb;