Projekt:Installation

This is an installation manual for a MediaWiki platform. For this project, you are probably done with all of this. However, it serves as a guideline for further mediawiki projects. And you can use it as a cheatsheet or checklist to verify your installtion.

What to do

1. get the files via git git clone --branch <branch> --recursive https://imtdev.uni-paderborn.de/git/mediawiki/mediawiki.git <project>
2. set up your apache with DocumentRoot /var/www/<project>/mediawiki, adjust php_admin_value open_basedir, upload_tmp_dir, and session.save_path accordingly
3. in _config create a LocalSettings_host.php from the shipped .sample file. Adjust setting for $wgServer if needed
4. in _opt/scripts run script init

Get the files

Either use a git repository or get a zip with all the necessary files. Using git at the IMT, the call should look something like this:

git clone --recursive https://imtdev.uni-paderborn.de/git/mediawiki/mediawiki.git <project>

The --recursive is important, otherwise you are missing all the submodules' files.

When using a project branch (like smwcore, hilfe, or imtkb) you can specify it on clone directly with

git clone --branch <branch> --recursive https://imtdev.uni-paderborn.de/git/mediawiki/mediawiki.git <project>

See Project:Software overview for more information about the layout of your wiki software.

Apache

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

DocumentRoot /var/www/<project>/mediawiki

It is also advisable to set these directives:

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

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

Configuration files

On overview and a detailed description of your configuration files can be found on the software overview page.

You at least have to generate a LocalSettings_host.php file and if you want to start a new or change an existing project, create/adjust LocalSettings_project.php. You might also need a LocalSettings_project_extensions.php (which also can be created from a sample file if need be).

We cover the basics that are necessary for an installation here. For a detailed description on customization, please visit Software_customization.

LocalSettings_host.php

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

<?php
	# ***************************** NOTE *****************************
	# This is a special config file for all host specific settings
	# like database, sitename, secret key, etc.
	#
	# For configurations settings that are valid for your whole
	# project, see LocalSettings_project.php
	#
	# See includes/DefaultSettings.php for all configurable settings
	# and their default values, but don't forget to make changes in _this_
	# file, not there.
	#
	# Further documentation for configuration settings may be found at:
	# https://www.mediawiki.org/wiki/Manual:Configuration_settings


	# Protect against web entry
	if ( !defined( 'MEDIAWIKI' ) ) {
		exit;
	}


	## Maintenance mode
	###################
	# This sets your project in maintenance mode. Can also be set in LocalSettings_maintenance.php
	#$wgReadOnly = 'Down for maintenance, access will be restored shortly';


	## Caching
	# is per default active. you maybe want to disable this on dev or staging systems
	#$wgMainCacheType = CACHE_NONE;


	## Site specific information:
	# Name of Site (and Project space).
	# Default for project is found in LocalSettings_project.php; overwrite on project or staging hosts here
	#$wgSitename = $wgSitename . " - staging";
	#$wgMetaNamespace = "Projekt";

	## Host specific settings
	# The protocol and server name to use in fully-qualified URLs
	# project default is set in LocalSettings_project.php
	#$wgServer = "https://yourhostname.domain";

	# The relative URL path to the logo. Make sure you change this from the default,
	# Default for project is found in LocalSettings_project.php; overwrite in project or staging here
	#$wgLogo = "$wgScriptPath/images/common/logo.jpg";


	## Contact addresses
	# Default for project is found in LocalSettings_project.php; overwrite in project or staging here
	#$wgEmergencyContact = "thatsme@domain"; // one of your email accounts
	#$wgPasswordSender = "thatsme@domain";   // one of your email accounts


	## some secrets
	# db password
	$wgDBpassword = "DBPASSWD";

	# secret session fallback hash
	# Note: $wgSecretKey: [0-9a-z]{64}
	$wgSecretKey = "4207ee50e0e84aad131214b2ede66f206ca3b94a00fbecc3b25c62e4e38a96c9";

	# Changing this will log out all existing sessions.
	$wgAuthenticationTokenVersion = "1";


	## debug
	########
#	error_reporting(E_ALL);
#	ini_set ("display_errors", "1");
#	$wgShowExceptionDetails = true;
#	$wgReadOnly = 'Down for maintenance, access will be restored shortly';
#	$wgDebugToolbar = true;
##	$wgShowDebug = true;
#	$wgDevelopmentWarnings = false;
##	$wgShowSQLErrors = true;
##	$wgDebugDumpSql = true;
##	$wgShowDBErrorBacktrace = true;
#	$wgDebugLogFile = $wgTmpDirectory . "/project-debug.log";
##	Lua debug log file is to be configured in LocalSettings_extensions.php

/**
 * LDAP Debugging
 */
if ( false ) {
	// @debug
	$LDAPProviderCacheType = CACHE_NONE;
	#ldap_set_option( null, LDAP_OPT_DEBUG_LEVEL, 7 );
	$wgDebugLogGroups['LDAP'] = __DIR__ . '/../LDAP.log';
	$wgDebugLogGroups['MediaWiki\\Extension\\LDAPProvider\\Client'] = __DIR__ . '/../LDAPClient.log';
	$wgDebugLogGroups['LDAPGroups'] = __DIR__ . '/../LDAPGroups.log';
	$wgDebugLogGroups['LDAPAuthorization'] = __DIR__ . '/../LDAPAuth.log';
	// $$wgDebugLogGroups['LDAPUserInfo'] =
}

All you really need to do is to create it. What might also be necessary is to configure your hostname, if the one set in LocalSettings_project.php is not the correct one. Please see the highlighted line #44. You can also set database credentials in this file (line #62) if you opt not to use the init script, in which case you also should set a new secret session fallback hash (line #66).

Finalize, the easy way

The easy way to finalize your project is to run one of your helper scripts: init. This is a wizard to guide you through the last steps of your installation.

But before you start you can customize your init. To do this switch to

./_opt/bin

and edit init.config. It looks like this:

# configuration file for script init

# use this database collation. supported are utf8 and bin
COLLATION=utf8

# instance language. supported are de, en
LANG=de

# switches for all the optional base packages
OPT_BOILERPLATES=1
OPT_DOCUMENTATION=0
OPT_GADGETS=1
OPT_KERBEROS=1

# contribute image imports and page protections to this username
USERNAME=

# you can specify database settings here. normally, they are obtained
# from LocalSettings_host.php automatically, though.
# nevertheless, entries specified here must match your configured settings
DBSERVER=
DATABASE=
DBUSER=
DBPASSWORD=

• Line 4: select your database collation. This must match your $wgDBTableOptions from your MediaWiki configuration. Normally this is utf8
• Line 7: this is your default language. Supported entries are de and en
• Line 10ff: There are four optional packages you can import. Set the corresponding entry to something different than 1 to disable the package. Note: When your are not using Kerberos, you should comment out the inclusion of LocalSettings_LDAPAuth.php in your LocalSettings.php.
• Line 16: If you want to contribute file uploads and page protections to a local user, set USERNAME accordingly
• Line 21ff: init should be able to obtain database information from your LocalSettings_project.php and LocalSettings_host.php directly. However, if you want to make sure, use a different configuration or file structure, you can set this data here manually.

When you are finished customizing your config, you can start the wizard. If you want to play it safe, you can do a dry-run first, no action will be taken. You can do this with the command:

 ./init --dryrun

If you are sure, just skip the parameter and start the wizard with

 ./init

Please read the printout thoroughly and follow through with the user guided script. When the wizard is done, it will create a lock file to prevent you from running the wizard again. If you - for any reason - need to repeat the init-process, you have to delete the file init.lock.

You can get more help for the script, by executing

 ./init --help

Finalize, the hard way

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
   

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 ../../_opt/init/base_content/default/ -name \*.xml -exec php importDump.php --no-updates {} \;

or

./import_dumps --base;

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-documentation.xml, containing these documentation pages. It is recommended to omit them in public wikis
• package-gadgets.xml, a large list of nice and useful gadgets to use with Extension:Gadgets
• package-kerberos.xml, predefined messages and the login page you need when using kerberos with ldap authentication

To install them all, hit

find ../../_opt/init/base_content/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 ./_opt/init/base_content/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 one of the provided scripts in ./_opt/bin:

.\import_images --base

or do a manual import with a maintenance script in ./mediawiki/maintenance

php importImages.php ../../_opt/init/base_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/<project>/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 -f -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 ./_opt/scripts/ execute

 ./protect_pages

If you want to contribute the proctection to a local username other than "127.0.0.1", you can do this by specifying a username with the parameter --user. For instance:

 ./protect_pages --user ProtecT0r

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 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.

More information about the script can be obtained by running

 ./protect_pages --help

Clean up

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.