MediaWiki

The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

MediaWiki is a free and open source wiki software written in PHP, originally developed for Wikipedia. It also powers this wiki (see Special:Version and the GitHub repository).

Installation

To run MediaWiki you need three things:

the mediawiki package, which pulls in PHP
a web server, such as Apache HTTP Server, nginx or lighttpd
a database system – one of MariaDB, PostgreSQL, SQLite or MySQL

To install MediaWiki on XAMPP, see mw:Manual:Installing MediaWiki on XAMPP

Configuration

The steps to achieve a working MediaWiki configuration involve editing the PHP settings and adding the MediaWiki configuration snippets.

Note: This guide assumes that mediawiki depends on php7.

PHP

MediaWiki requires the iconv extension, so you need to uncomment extension=iconv in /etc/php7/php.ini.

Optional dependencies:

For thumbnail rendering, install either ImageMagick or php7-gd. If you choose the latter, you also need to uncomment extension=gd.
For more efficient Unicode normalization, install php7-intl and uncomment extension=intl.

Enable the API for your DBMS:

If you use MariaDB, uncomment extension=mysqli.
If you use PostgreSQL, install php7-pgsql and uncomment extension=pgsql.
If you use SQLite, install php7-sqlite and uncomment extension=pdo_sqlite.

Second, tweak the session handling or you might get a fatal error (PHP Fatal error: session_start(): Failed to initialize storage module[...]) by finding the session.save_path path. A good choice can be /var/lib/php/sessions or /tmp/.

/etc/php7/php.ini

session.save_path = "/var/lib/php/sessions"

You will need to create the directory if it does not exist and then restrict its permissions:

# mkdir -p /var/lib/php/sessions/
# chown http:http /var/lib/php/sessions
# chmod go-rwx /var/lib/php/sessions

If you use PHP's open_basedir and want to allow file uploads, you need to include /var/lib/mediawiki/ (mediawiki symlinks images/ to /var/lib/mediawiki/).

Web server

Apache

Follow Apache HTTP Server#PHP.

Copy /etc/webapps/mediawiki/apache.example.conf to /etc/httpd/conf/extra/mediawiki.conf and edit it as needed.

Add the following line to /etc/httpd/conf/httpd.conf:

Include conf/extra/mediawiki.conf

Restart the httpd.service daemon.

Note: The default file from /etc/webapps/mediawiki/apache.example.conf will overwrite the PHP open_basedir setting, possibly conflicting with other pages. This behavior can be changed by moving line starting with php_admin_value between the <Directory> tags. Further, if you are running multiple applications that depend on the same server, this value could also be added to the open_basedir value in /etc/php7/php.ini instead of /etc/httpd/conf/extra/mediawiki.conf

Nginx

To get MediaWiki working with Nginx, create the following file:

/etc/nginx/mediawiki.conf

location / {
   index index.php;
   try_files $uri $uri/ @mediawiki;
}
location @mediawiki {
   rewrite ^/(.*)$ /index.php;
}
location ~ \.php$ {
   include /etc/nginx/fastcgi_params;
   fastcgi_pass unix:/var/run/php-fpm7/php-fpm.sock;
   fastcgi_index index.php;
   fastcgi_param  SCRIPT_FILENAME  $document_root$fastcgi_script_name;
   try_files $uri @mediawiki;
}
location ~* \.(js|css|png|jpg|jpeg|gif|ico)$ {
   try_files $uri /index.php;
   expires max;
   log_not_found off;
}
# Restrictions based on the .htaccess files
location ~ ^/(cache|includes|maintenance|languages|serialized|tests|images/deleted)/ {
   deny all;
}
location ~ ^/(bin|docs|extensions|includes|maintenance|mw-config|resources|serialized|tests)/ {
   internal;
}
location ^~ /images/ {
   try_files $uri /index.php;
}
location ~ /\. {
   access_log off;
   log_not_found off; 
   deny all;
}
location /rest.php {
   try_files $uri $uri/ /rest.php?$args;
}

Ensure that php7-fpm is installed and php-fpm7.service is started.

Include a server directive, similar to this

/etc/nginx/nginx.conf

server {
  listen 80;
  server_name mediawiki;
  root /usr/share/webapps/mediawiki;
  index index.php;
  charset utf-8;
# For correct file uploads
  client_max_body_size    100m; # Equal or more than upload_max_filesize in /etc/php7/php.ini
  client_body_timeout     60;
  include mediawiki.conf;

}

Finally, restart nginx.service and php-fpm7.service daemons.

Lighttpd

You should have Lighttpd installed and configured. "mod_alias" and "mod_rewrite" in server.modules array of lighttpd is required. Append to the lighttpd configuration file the following lines

/etc/lighttpd/lighttpd.conf

alias.url += ("/mediawiki" => "/usr/share/webapps/mediawiki/")
url.rewrite-once += (
                "^/mediawiki/wiki/upload/(.+)" => "/mediawiki/wiki/upload/$1",
                "^/mediawiki/wiki/$" => "/mediawiki/index.php",
                "^/mediawiki/wiki/([^?]*)(?:\?(.*))?" => "/mediawiki/index.php?title=$1&$2"
)

Restart the lighttpd.service daemon.

Database

Set up a database server as explained in the article of your DBMS: MariaDB, PostgreSQL, SQLite or MySQL.

If you have set a non-empty root password for the database server, MediaWiki can automatically create the database during the next step. (See MariaDB#Reset the root password for how to set this password retrospectively for MariaDB.) Otherwise the database needs to be created manually - see upstream instructions.

LocalSettings.php

Open the wiki URL (usually http://your_server/mediawiki/index.php) in a browser and do the initial configuration. Follow upstream instructions.

The generated LocalSettings.php file is offered for download, save it to /etc/webapps/mediawiki/LocalSettings.php and create symbolic link to it from /usr/share/webapps/mediawiki/LocalSettings.php:

# ln -s /etc/webapps/mediawiki/LocalSettings.php /usr/share/webapps/mediawiki/LocalSettings.php

Warning: LocalSettings.php contains database connection settings, such as the usename and password, and the MediaWiki web-based updater password. Make sure only the root and http users have access to /etc/webapps/mediawiki/LocalSettings.php:

# chown root:http /etc/webapps/mediawiki/LocalSettings.php
# chmod 640 /etc/webapps/mediawiki/LocalSettings.php

This file defines the specific settings of your wiki. Whenever you upgrade the mediawiki package, it will not be replaced.

Upgrading

See mw:Manual:Upgrading, and do not forget to run:

# cd /usr/share/webapps/mediawiki
# php maintenance/update.php

Tips and tricks

Mathematics (texvc)

Usually installing texvc and enabling it in the config is enough:

$wgUseTeX = true;

If you get problems, try to increase limits for shell commands:

$wgMaxShellMemory = 8000000;
$wgMaxShellFileSize = 1000000;
$wgMaxShellTime = 300;

Unicode

Check that PHP, Apache HTTP Server and MariaDB all use UTF-8. Otherwise you may face strange bugs because of encoding mismatch.

VisualEditor

The VisualEditor MediaWiki extension provides a rich-text editor for MediaWiki. Follow mw:Extension:VisualEditor to install it.

You will also need the Parsoid Node.js backend, which is available in parsoid-git^AUR.

Adjust the path to MediaWiki in /usr/share/webapps/parsoid/api/localsettings.js:

parsoidConfig.setInterwiki( 'localhost', 'http://localhost/mediawiki/api.php' );

After that enable and start parsoid.service.

Alternatively, one may also use the parsoid^AUR package, and configure the service via the yaml file, where the following lines should be present:

/usr/share/webapps/parsoid/config.yaml

uri: `'http://localhost/mediawiki/api.php'`
domain: 'localhost'

The matching part in the mediawiki settings:

/etc/webapps/mediawiki/LocalSettings.php

$wgVirtualRestConfig['modules']['parsoid'] = array(
  // URL to the Parsoid instance - use port 8142 if you use the Debian package - the parameter 'URL' was first used but is now deprecated (string)
  'url' => 'http://localhost:8000/',
  // Parsoid "domain" (string, optional) - MediaWiki >= 1.26
  'domain' => 'localhost',
  // Parsoid "prefix" (string, optional) - deprecated since MediaWiki 1.26, use 'domain'
  'prefix' => 'localhost',
  // Forward cookies in the case of private wikis (string or false, optional)
  'forwardCookies' => false,
  // request timeout in seconds (integer or null, optional)
  'timeout' => null,
  // Parsoid HTTP proxy (string or null, optional)
  'HTTPProxy' => null,
  // whether to parse URL as if they were meant for RESTBase (boolean or null, optional)
  'restbaseCompat' => null,
);

After configuration, the parsoid service may be started (restarted) and (if not done yet) enabled.