Projekt:Installation

This is an installation instruction for this MediaWiki platform. All in all you should be done whith this when you read this page. However, it serves as a template to edit when the platform is modified. And you can use it as a cheatsheet or checklist to verify your installtion.

Get the files

Either use a git repository or get a zip file with all the necessary files. Once you cloned or unziped the files, your file structure should look something like this:

drwxr-xr-x  8 www-data www-data 4096 Feb 18 12:43 .git                           // your repository files
-rw-r--r--  1 www-data www-data  362 Feb 18 12:06 .gitignore                     // ignore files for your repo
-rw-------  1 www-data www-data   58 Oct 21 17:11 _admin_login.php               // located in this file are the credentials for the local admin login
drwxr-xr-x  2 www-data www-data 4096 Feb 18 12:06 _config                        // this is where your config files are located
drwxr-xr-x 51 www-data www-data 4096 Feb 18 12:41 _extensions                    // this is the assortment of available extensions
drwxr-xr-x  3 www-data www-data 4096 Dec 16 09:58 _images                        // this is your image directory, almost empty after unpacking
drwxr-xr-x  5 www-data www-data 4096 Feb 17 12:39 _init                          // this is where all starter files and some useful scripts are located
-rwx------  1 www-data www-data  593 Oct 21 17:11 get_new_version_going          // a small script to initialize a new version (update, not upgrade) of the mediawiki software
lrwxrwxrwx  1 www-data www-data   16 Feb 18 12:40 mediawiki -> mediawiki-1.23.8  // a symbolic link to the current mediawiki core software
drwxr-xr-x 12 www-data www-data 4096 Feb 18 12:39 mediawiki-1.23.8               // the current mediawiki core software
drwxr-xr-x  2 www-data www-data 4096 Oct 23 13:04 php_temp                       // folder for temporary files and session data

Placing the config files, extensions and uploaded files in directories parallel to the mediawiki software and not (as per default) inside it, brings certain benefits:

• quicker access via shell
• tidies up the config files
• shared filebase accross different versions of mediawiki core
• easy way to upgrade the core
• keep core and additional (user provided and defined) data separated

However there is one drawback: When calling maintenance scripts in an extension directory, this will most probably fail. The script tries to "guess" the location of the mediawiki core by assuming it in the correct relative position to the script. Since with our installation this isn't the case, the scripts returns an error. This however is easily remedied. Just set an environment variable via:

export MW_INSTALL_PATH=/var/www/<wikiname>/mediawiki

Choose the path according to your installation. You can do this in your server startup config or simply everytime you call a maintenance script. Which won't be that often. But we'll come back to this in a little while, we don't need it now.

Apache

Please configure your Apache to use the ./mediawiki folder as DocumentRoot:

  DocumentRoot /var/www/<wikiname>/mediawiki

It is also advisable to set these directives:

  php_admin_value open_basedir "/var/www/<wikiname>:/usr/share/php/:/usr/bin/:/dev/null"
  php_admin_value upload_tmp_dir "/var/www/<wikiname>/php_temp/"
  php_admin_value session.save_path "/var/www/<wikiname>/php_temp/"

of course replace <wikiname> with whatever wikiname/directory you chose.

If you decided for the luasandbox, you'll have to do some changes to your php configuration. We'll explain below.

Additional Packages

lua

If you opt for the use of a lua sandbox (whiz more performant than the default standalone interpreter), you have to install it. If you can't take advantage of the IMT infrastructure, you have to install and compile the lua-sandbox yourself. See here for a how-to. Keep in mind to still make the alterations to the LocalSettings_extensions.php as described later.

You alse have to add the following line to your php.ini or to /etc/php5/conf.d/:

extension=luasandbox.so

Some installations have more than one php.ini file. You have to add the line to both. For instance:

/etc/php5/cli/php.ini
/etc/php5/apache2/php.ini

APC (Alternative PHP Cache)

Your wiki platform is configured to take advantage of php opcode caching. You can either install apc (recommended) or uncomment the corresponding line in ./_config/LocalSettings.php.

To install apc hit

apt-get apc

As a sample configuration you can use this:

apc.enabled=1

; If APC is configured with mmap it only uses 1 shm_segment
apc.shm_segments=1

; just large memory example ##
apc.shm_size=200M

; PHP file cache 1 hour ##
apc.ttl=3600

; User cache 2 hour ##
apc.user_ttl=7200

; Garbage collection 1 hour ##
apc.gc_ttl=3600

apc.max_file_size=1M

; Normally set to 1##
apc.stat=1

; TYPO3-Empfehlung
apc.file_update_protection=0

Just save this to /etc/php5/conf.d/apc.ini

Note: When at the imt, configure apc via bcfg2.

Graphviz

If you want to use the installed GraphViz extension, you have to get two packages and install them as well. For linux systems use this line:

sudo aptitude install graphviz graphviz-dev

You can find more information about the configuration and installation at http://www.mediawiki.org/wiki/Extension:GraphViz#Common

MySQL

You need a database server. This package assumes you use MySQL and it has a predefined structure for a quick start. If you should choose a different database engine, just do so. The initialization should be comparable. However you have to get the table structure yourself (for instance by running the mediawiki installation wizard).

1. set up a new database, we recommend naming it the same as your wiki. As collation either choose utf8-general or binary. Binary is the original mediawiki type, utf8 the more modern one (we recommend utf8). If you should opt for binary, please change the collation type in LocalSettings.php to binary.
2. create a database user (or use an existing one)
3. assign the necessary rights for your user to the database:

   use `mysql`;
   update `db` set `Select_priv`='Y', `Insert_priv`='Y', `Update_priv`='Y', `Delete_priv`='Y', `Create_priv`='Y', `Drop_priv`='Y', `References_priv`='Y', `Index_priv`='Y', `Alter_priv`='Y', `Create_tmp_table_priv`='Y', `Lock_tables_priv`='Y', `Create_view_priv`='Y', `Show_view_priv`='Y', `Trigger_priv`='Y' where `db`='DATABASENAME' AND `user`='DBUSERNAME';
   

4. If you use phpmyadmin, please check the following:
   

   Data		Structure		Administration
   	Select		Create		Grant
   	Insert		Alter		Lock Tables
   	Update		Index		References
   	Delete		Drop
   			Create temporary Table
   			Show View
   			Create Routine
   			Alter Routine
   			Execute
   			Create View
   			Event
   			Trigger

5. Import the db_init-<collation>.sql located in the folder ./_init. Choose the one corresponding to your database collation you chose earlier:

   mysql -u DBUSERNAME -p DATABASENAME < db_init-utf8.sql
   

Configuration files

Here is an overview of how your config files look at this point:

-rw-r--r-- 1 www-data www-data 9219 Feb 17 08:41 LocalSettings.php.sample             // sample file for general settings
-rw-r--r-- 1 www-data www-data 9379 Nov 18 09:41 LocalSettings_LDAPAuth.php           // ldap configuration. only needed, if you use ldap auth, of course
-rw-r--r-- 1 www-data www-data 9604 Feb 18 12:06 LocalSettings_acls.php.sample        // sample file for acls. this file manages groups, roles and their permissions
-rw-r--r-- 1 www-data www-data 9108 Feb 18 12:06 LocalSettings_extensions.php.sample  // sample file for extension configuration data
-rw-r--r-- 1 www-data www-data 2496 Feb 18 12:06 LocalSettings_host.php.sample        // sample file for your personal host configuration. you have to edit this!

and here is how it must look like:

-rw-r--r-- 1 www-data www-data 9219 Feb 17 08:41 LocalSettings.php                    // general settings
-rw-r--r-- 1 www-data www-data 9219 Feb 17 08:41 LocalSettings.php.sample             // sample file for general settings
-rw-r--r-- 1 www-data www-data 9379 Nov 18 09:41 LocalSettings_LDAPAuth.php           // ldap configuration. only needed, if you use ldap auth, of course
-rw-r--r-- 1 www-data www-data 9604 Feb 18 12:06 LocalSettings_acls.php               // this file manages groups, roles and their permissions
-rw-r--r-- 1 www-data www-data 9604 Feb 18 12:06 LocalSettings_acls.php.sample        // sample file for acls. this file manages groups, roles and their permissions
-rw-r--r-- 1 www-data www-data 9108 Feb 18 12:06 LocalSettings_extensions.php         // here you can add, remove, and configure extensions
-rw-r--r-- 1 www-data www-data 9108 Feb 18 12:06 LocalSettings_extensions.php.sample  // sample file for extension configuration data
-rw-r--r-- 1 www-data www-data 2496 Feb 18 12:06 LocalSettings_host.php               // your personal host configuration, ready to use
-rw-r--r-- 1 www-data www-data 2496 Feb 18 12:06 LocalSettings_host.php.sample        // sample file for your personal host configuration. you have to edit this!

So simply copy all *.sample files in there normal pendant. These three "unsamples" are excluded from the git.

LocalSettings.php

There is one thing to do here, it is very important:

  // just define a constant to hold location for the configs
  define("toConfigPath", "/var/www/<yourwikiname>/_config");

  ## include some configfiles
  ...

If you don't want to use apc, you have to disable the caching:

  ## Shared memory settings
  #$wgMainCacheType = CACHE_NONE;
  $wgMainCacheType = CACHE_ACCEL;
  $wgEnableSidebarCache=true;
  $wgMemCachedServers = array();
  ...

• uncomment line 99
• comment line 100 through 102

LocalSettings_host.php

As you copied LocalSettings_host.sample.php to LocalSettings_host.php it looks like this:

<?php
# ***************************** NOTE *****************************
# It is important that you adjust the following line at the end of LocalSettings.php to match your layout:
#
# define("toConfigPath", "/var/www/<yourwikiname>/_config");

# this is a special config file for all host specific settings like database, etc.

## Sitespecific information
$wgSitename = "YOURSITENAME";

$wgEmergencyContact = "webmaster@domain"; // one of your email accounts
$wgPasswordSender = "webmaster@domain";   // one of your email accounts

## we store the name of our localhost in this varibale, so we can use it later
$xgNameLocalhost = "yourhostname.domain"; // your fully quallified host name

# Site language code, should be one of the list in ./languages/Names.php
$wgLanguageCode = "en";

## The relative URL path to the logo. Make sure you change this from the default,
## or else you'll overwrite your logo when you upgrade!
#$wgLogo = "$wgStylePath/common/images/wiki.png";
$wgLogo = "$wgScriptPath/images/common/logo.jpg"; // we recommend storing your wikilog in _images/common

## To enable image uploads, make sure the 'images' directory
## is writable, then set this to true:
$wgEnableUploads = true;
$wgTmpDirectory = "/var/www/<yourwikiname>/php_temp"; // the php_temp is part of your bundle. if you change this location, please also alter your apache2.conf
#$wgUseImageMagick = true;
#$wgImageMagickConvertCommand = "/usr/bin/convert";

## For reading Images via img_auth
#$wgWhitelistRead = false;
#$wgImgAuthPublicTest = false;
#$wgUploadPath = "/img_auth.php";
##$wgUploadPath = "$wgScriptPath/img_auth.php";
#$wgUploadDirectory = "/var/www/<yourwikiname>/php_temp"; // the php_temp is part of your bundle. if you change this location, please also alter your apache2.conf

## The protocol and server name to use in fully-qualified URLs
$wgServer = "https://".$xgNameLocalhost;      // DO NOT TOUCH

## Database settings
$wgDBtype = "mysql";
$wgDBserver = "localhost";
$wgDBname = "DBNAME";
$wgDBuser = "DBUSER";
$wgDBpassword = "DBPASSWD";

## LDAP Settings
# If you use LDAP-Authentication plugin, configure your ldap proxy agent here
$wgLdapProxyAgent = ""; // "cn=,ou=,ou=,o=,c=de";
$wgLdapProxyAgentPassword = "";  // "PASSWORD";

$wgSecretKey = "4207ee50e0e84aad131214b2ede66f206ca3b94a00fbecc3b25c62e4e38a96c9";

# Site upgrade key. Must be set to a string (default provided) to turn on the
# web installer while LocalSettings.php is in place
$wgUpgradeKey = "b971c5e721f9ea0a";
?>

Your tasks here are:

1. Line 10: specify the name of your site
2. Line 12f: email contact addresses
3. Line 16: give here your fully qualified host name, e.g. en.wikipedia.org
4. Line 19: here you choose your language locale (e.g. en, de, au, ...)
5. Line 24: specify the location or your wiki's logo. we recommend putting it in ./_images/common
6. Line 28: is for enabling (or disabling) file uploads
7. Line 29: if you allow fileuploads, specify here the temporary upload directory. we recommend the php_temp folder that came with your installation. If you choose a different folder, be sure to also change your Apache configuration accordingly.
8. Line 34ff: This section deals with a secure image wrapper. if you have to use it, configure it here. See here for further details.
9. Line 41: We'll mention it here again: as it says in the comment: DO NOT TOUCH (unless of course you really know what you do)
10. Line 44ff: configure your database connection here. Specify database, database user and database user's password here like you set it up earlier.
11. Line 52f: if you use Kerberos (or any other sso authentication) with LDAP, specify a LDAP proxy user here
12. Line 55ff: For security reasons you must personalize $wgSecretKey and $wgUpgradeKey

LocalSettings_extensions.php

This includes and configures all extensions of your platform. You can add and remove extensions here.

Note: The first part (that one being about semantic) configures semantic media wiki and dependant extensions. Most of them are installed via composer, therefore you won't find any file inclusions for these extensions here. Please see Maintenance for more information on how to install, remove and upgrade composer dependant extensions.

Second part containes the traditionally installed extensions in an alphabetical order. With each extensions comes their basic configuration. However, if they require certain access rights specify them in LocalSettings_acls.php.

lua

This platform needs the Scribunto extension - which gives lua support - to work properly. You can either use the default Lua standalone compiler or a mediawiki optimized lua sandbox. When you are at the university, just install the debian packet php-luasandbox or get the bcfg2 bundle lua. Then modify the LocalSettings_extensions.php. Search for this section:

  # Scribunto (hope, this thing works out)
  require_once( "$IP/extensions/Scribunto/Scribunto.php");
  $wgScribuntoUseGeSHi = true;  # adds GeSHi-capabilities to scribunto
  $wgScribuntoUseCodeEditor = true; # lets Scribunto use the CodeEditor
  $wgScribuntoDefaultEngine = 'luastandalone';
  #$wgScribuntoDefaultEngine = 'luasandbox';
  $wgScribuntoEngineConf['luasandbox']['memoryLimit'] = 100 * 1024 * 1024;  // default is 50 * 1024 * 1024
  $wgScribuntoEngineConf['luasandbox']['cpuLimit'] = 10;    // default is 7

and uncomment the highlighted line.

If you can't take advantage of the IMT infrastructure, you have to install the sandbox yourself. See here for a how-to. Keep in mind to still make the alterations to the LocalSettings_extensions.php as described above.

You alse have to add the following line to your php.ini or to /etc/php5/conf.d/:

extension=luasandbox.so

Some installations have more than one php.ini file. You have to add the line to both. For instance:

/etc/php5/cli/php.ini
/etc/php5/apache2/php.ini

LocalSettings_acls.php

Here you can specify groups, roles and their rights. At the moment this platform is set to read only for anonymous user and edit for authenticated users. Please refer to Customization for more information about rights management.

Database schema

You have to update the database structure once, to alter the schema for use of all the selected extensions. Switch to ./mediawiki/maintenance and run

php update.php

You should also do this after installing new extensions and after each update.

Import packages

Now that the database is ready, you can start getting the content in. For that matter, we are going to import the bundled pages. You can do this later, even inside your wiki on Special:Import, but we recommend doing it right ahead. So, remember we're still in ./mediawiki/maintenance. First run:

find ../../_init/packages/default/ -name \*.xml -exec php importDump.php --no-updates {} \;

to import the mandatory packages. After that, you have to choose which optional packages you want installed:

• package-boilerplates.xml, which gives you some predefined preloader pages to use with Extension:Preloader
• package-gadgets.xml, a large list of nice and useful gadgets to use with Extension:Gadgets
• package-gardening.xml, some templates and categories to help you with quality assurance in your wiki
• package-kerberos.xml, predefined messages and the login page you need when using kerberos with ldap authentication

To install them all, hit

find ../../_init/packages/optional/ -name \*.xml -exec php importDump.php --no-updates {} \;

otherwise just import the packages you want one by one.

Systemlanguage

Depending on what system language you chose you have to import a different package for systemmessages. You find them in ./_init/packages/language/package-lang-<langcode>.xml. Please choose the file corresponding to your system language you set earlier.

Finalize with update.php

To let the changes on the system messages take place, you have to run update.php again. Switch back to ./mediawiki/maintenance and execute

php update.php

Import images

With your platform comes an assortment of 47 pictures, mainly used in interface and message box templates. They are bundled in the extension directory and can easily be imported with a maintenance script So please go ti ./mediawiki/maintenance and run:

php importImages.php ../../_init/images png gif

If you want, you can specify the wiki user that the upload will be attributed to with --user=<username>.

Run maintenance

To finalize the imported content, you have to run a bunch of maintenance scripts. First set an environment variable with:

export MW_INSTALL_PATH=/var/www/<wikiname>/mediawiki

Start with rebuildall.php to populate the categorylinks, pagelinks, and imagelinks tables and set up the search index. Go to ./mediawiki/maintenance and run:

php rebuildall.php

This could take a minute or two.

Then you could initialize the semantic data (that is, if you're using the semantic extensions). This datastore shoud be empty but nevertheless, lets see it as a dry run since you should do this regularily (or by cron, see Maintenance for more on this). Switch to ./_extensions/SemanticMediaWiki/maintenance and hit:

php rebuildData.php -v

If you use the extension Approved Revisions you'll have to approve all imported revisions. Otherwise your wiki will be as empty as a fresh installation. Switch to ./_extensions/ApprovedRevs/maintenance and run

php approveAllPages.php

And finally the biggest chunk. Executing all these maintenance scripts (especially rebuildall.php) has packed up your job queue quite a bit. Before starting to use the wiki, you'll have to run all queued jobs. Switch back to ./mediawiki/maintenance and execute

php runJobs.php

This will take really long! Take a coffee break (You deserve it!) and come back in 10.

Protect all vital pages

Now you can choose to protect all vital pages (i.e. some sample pages and a bunch of articles contained in certain categories). Switch to ./_init/_scripts/ and edit the script protect_pages.config:

# config file for script protect_pages

# this is the path in your fs where your wiki is located
PATHTOMYWIKI=/var/www/<wikiname>/mediawiki

# the url, your wiki is accessiable from
WIKIURL=https://host.domain

# the user all the protection actions are attributed to
USERNAME=anyuser

The three variables must be specified or protect_pages will render errors.

If you want to fix this, go to ./mediawiki/maintenance/ and edit protect.php. Change:

  public function execute() {
  $userName = $this->getOption( 'u', 'Maintenance script' );
  $reason = $this->getOption( 'r', '' );

  $cascade = $this->hasOption( 'cascade' );

into this:

  public function execute() {
  $userName = $this->getOption( 'user', 'Maintenance script' );
  $reason = $this->getOption( 'reason', '' );

  $cascade = $this->hasOption( 'cascade' );

After that simply run protect_pages. You can do this fromanywhere in your file system. :) It will take some time. After you're finished, it is recommended that you run

php rebuildall.php
php runJobs.php

again. :( I know, sucks. But in order to populate the categories, it had to be executed once before.

Clean up

You can scrap some files now, you wont need them anymore. You can delete ./_init (unless of course you haven't imported all the packages and images and want to do so later) and ./_config/LocalSettings_host.sample.php. Please mind that in doing so your repository becomes modified. Alternatively, you can remove the ./.git as well, preventing you from getting any updates.

Finally, we have to see to it that the webserver can read (and in some cases) modify alle the necessary files. Please change to your platform's root (not your wiki root), for instance to /var/www/mywiki and run

chown -R apache-user:apache-group *

where apache-user is the local username, your apache runs as and apache-group its local group.

Notes on merging with existing installations

This is a very tricky thing to do. First, please backup your system.

Basically what you have to do is take all content from your old system excluding the pages brought to you by this platform and import them both in a new system. Exporting data from your old system could be done via databasedump, XML page export or brute force.

Database

If you use the database option it could be difficult to exclude the pages from this platform. Easiest way to do this is to delete the corresponding pages in your old system. To do that, there are two ways:

1. Installing Extension:DeleteBatch and feed it the names of the pages to delete. You can find files containing the necessary pagenames in ./_init/lists/ext_db/package-<packagename>.txt
2. Use a maintenance script located in ./mediawiki/maintenance together with a prepared text file:

php deleteBatch.php -r "preparing to merge" ../../_init/lists/deletebatch/

Export

Here the trick is to generate a list of all pages used in your wiki. Including all custom namespaces, talk pages, systemmessges, subpages, userpages, etc. If you miss one, it won't be your new installation. For instance you could create that list with Special:AllPages with going through all namespaces. Or you could write a databasequery like:

select concat('NAMESPACE_ID_', page_namespace, ':', page_title) from page;

Dump the result and replace all accurances of 'NAMESPACE_ID_?' with the corresponding namespace name.

When you have that list, remove from it all entries found in the ./_init/lists/package/package-*.list files (or at least those corresponding to the packages you like to import later). Here you need some clever scripting, time or a combination of both (for instance an excel with rules for highlighting double entries).

With that list, you can start exporting pages. Do this either via Special:Export. Make shure you include the page history if you want to maintain it (thus unchecking 'Only latest revision') Important: Exclude the used templates, since we are gonna dump them anyway.

As alternative you can use a maintenance script php dumpBackup.php.--full. for export. Unfortunately, this script omits site-related data (they do not contain user accounts, image metadata, logs, etc), so you have to somehow identify those pages and export them via Special:Export. Also, you have to have your 'undesired' pages remove later from the dump. Finding them in the XML could be more tricky and unreliably that the manual export version.

Brute force

Just import both one after another. Pages that exist in both installations will have their history merged. The newest revision will become the current version. You can, however "cheat" if you edit the dump files and change the timestamps accordingly. For instance by script.

Namespace issues

If you had a namespace called meta defined in your old wiki already contaning pages, make sure these namespace had the id 3500 (and the corresponding talk space 3501). If not, you could either renumber the namespace in this platform or replace all namespace ids in our old wiki's dump. If the latter, note that: - each XML dump has a namespace section up front where you have to replace the id - each page entry in the XML dump has a numeric namespace id - the mysql page table contains the namespace as numeric id Change the ids accordingly.

Helper script

You can find a helper script to tweak xml-output in ./_init/_scripts/:

./tweak_timestamp FILENAME

This script takes the specified xml-file containing a mediawiki xml dump and replaces all timestamp entries with a current timestamp.