Quelltext der Seite 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 ==
# get the files via git <code>git clone --branch &lt;branch&gt; --recursive https://imtdev.uni-paderborn.de/git/mediawiki/mediawiki.git &lt;project&gt;</code>
# set up your apache with <code>DocumentRoot /var/www/&lt;project&gt;/mediawiki</code>, adjust ''php_admin_value open_basedir, upload_tmp_dir, and session.save_path'' accordingly
# in <code>_config</code> create a <code>LocalSettings_host.php</code> from the shipped ''.sample'' file. Adjust setting for <code>$wgServer</code> if needed
# in <code>_opt/scripts</code> run script <code>init</code>

== 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:

{{code|lang=bash|code=
git clone --recursive https://imtdev.uni-paderborn.de/git/mediawiki/mediawiki.git <project>
}}

The <code>--recursive</code> 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

{{code|lang=bash|code=
git clone --branch <branch> --recursive https://imtdev.uni-paderborn.de/git/mediawiki/mediawiki.git <project>
}}

{{ambox|type=content|text=If git hangs, make sure your host is in '''imtdev's acls'''.}}

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

== Apache ==
Please configure your Apache to use the {{code snippet|lang=bash|code=./mediawiki}} folder as DocumentRoot:
{{code|apache|
  DocumentRoot /var/www/<project>/mediawiki
}}

It is also advisable to set these directives:
{{code|apache|
  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 {{code snippet|lang=apache|code=<project>}} with whatever project/directory you chose.

{{ambox|type=info|text=See [[Project:Software customization]] to enable, disable, or configure additional packages like lua, graphvis, or apc.}}

== Configuration files ==
On overview and a detailed description of your configuration files can be found [[Project:Software_overview#Configuration_files|on the software overview page]].

You at least have to generate a <code>LocalSettings_host.php</code> file and if you want to start a new or change an existing project, create/adjust <code>LocalSettings_project.php</code>. You might also need a <code>LocalSettings_project_extensions.php</code> (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 [[Project:Software_customization|Software_customization]].

=== LocalSettings_host.php ===
As you copied <code>LocalSettings_host.sample.php</code> to <code>LocalSettings_host.php</code> it looks like this:
<syntaxhighlight lang="php" line="1" highlight="43">
<?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'] =
}
</syntaxhighlight>

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 <code>LocalSettings_project.php</code> 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 [[#Finalize, the easy way|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 [[Project:Software_overview#Helper_scripts|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 <code>init.config</code>. It looks like this:
<syntaxhighlight lang="bash" line="1">
# 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=
</syntaxhighlight>

* Line 4: select your database collation. This must match your {{code snippet|lnag=php|code=$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|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 <code>init.lock</code>.

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).
<ol>
<li>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 <code>LocalSettings.php</code> to <code>binary</code>.</li>
<li>create a database user (or use an existing one)</li>
<li>assign the necessary rights for your user to the database:
{{code|mysql|code=
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';
|3=no}}</li>
<li>If you use phpmyadmin, please check the following: <br />
{| class="wikitable"
|-
! colspan="2" | Data
! colspan="2" | Structure
! colspan="2" | Administration
|-
| {{ya}} || Select
| {{ya}} || Create
| {{na}} || Grant
|-
| {{ya}} || Insert
| {{ya}} || Alter
| {{ya}} || Lock Tables
|-
| {{ya}} || Update
| {{ya}} || Index
| {{ya}} || References
|-
| {{ya}} || Delete
| {{ya}} || Drop
| colspan="2" rowspan="9" | {{spaces}}
|-
| colspan="2" rowspan="8" | {{spaces}}
| {{ya}} || Create temporary Table
|-
| {{ya}} || Show View
|-
| {{na}} || Create Routine
|-
| {{na}} || Alter Routine
|-
| {{na}} || Execute
|-
| {{ya}} || Create View
|-
| {{na}} || Event
|-
| {{ya}} || Trigger
|}</li>
<li>Import the <code>db_init-<collation>.sql</code> located in the folder <code>./_init</code>. Choose the one corresponding to your database collation you chose earlier:
{{code|bash|code=
mysql -u DBUSERNAME -p DATABASENAME < db_init-utf8.sql
|3=no}}</li>
</ol>

=== Database schema ===
You have to update the database structure once, to alter the schema for use of all the selected extensions. Switch to <code>./mediawiki/maintenance</code> and run
{{code|io|
php update.php
}}

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

{{ambox|type=info|text=At this point your installation is ready to use. If you don't want any predefined content installed, skip to [[#Run_maintenace|run maintenace]] ahead and finalize.}}

=== 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 <code>./mediawiki/maintenance</code>. First run:

{{ambox|type=notice|text=For the import you can also use [[Project:Software_overview#import_dumps|the script import_dumps]].}}

{{code|io|
find ../../_opt/init/base_content/default/ -name \*.xml -exec php importDump.php --no-updates {} \;
}}
or
{{code|io|
./import_dumps --base;
}}

to import the mandatory packages. After that, you have to choose which optional packages you want installed:
* <code>package-boilerplates.xml</code>, which gives you some predefined preloader pages to use with [http://www.mediawiki.org/wiki/Extension:Preloader Extension:Preloader]
* <code>package-documentation.xml</code>, containing these documentation pages. It is recommended to omit them in public wikis
* <code>package-gadgets.xml</code>, a large list of nice and useful gadgets to use with [http://www.mediawiki.org/wiki/Extension:Gadgets Extension:Gadgets]
* <code>package-kerberos.xml</code>, predefined messages and the login page you need when using kerberos with ldap authentication
To install them all, hit
{{code|io|
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 <code>./_opt/init/base_content/language/package-lang-<langcode>.xml</code>. Please choose the file corresponding to your system language you set [[#LocalSettings_host.php|earlier]].

=== Finalize with update.php ===
To let the changes on the system messages take place, you have to run <code>update.php</code> again. Switch back to <code>./mediawiki/maintenance</code> and execute
{{code|io|
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 <code>./_opt/bin</code>:
{{code|io|code=
.\import_images --base
}}
or do a manual import with a maintenance script in <code>./mediawiki/maintenance</code>
{{code|io|code=
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 <code>--user=<username></code>.

=== Run maintenance ===
To finalize the imported content, you have to run a bunch of maintenance scripts. First set an environment variable with:
{{code|lang=bash|code=
export MW_INSTALL_PATH=/var/www/<project>/mediawiki
}}

Start with <code>rebuildall.php</code> to populate the categorylinks, pagelinks, and imagelinks tables and set up the search index. Go to <code>./mediawiki/maintenance</code> and run:
{{code|lang=io|code=
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 [[Project:Maintenance|Maintenance]] for more on this). Switch to <code>./_extensions/SemanticMediaWiki/maintenance</code> and hit:
{{code|lang=io|code=
php rebuildData.php -f -v 
}}

If you use the extension [http://www.mediawiki.org/wiki/Extension:Approved_Revs Approved Revisions] you'll have to approve all imported revisions. Otherwise your wiki will be as empty as a fresh installation. Switch to <code>./_extensions/ApprovedRevs/maintenance</code> and run
{{code|lang=io|code=
php approveAllPages.php
}}

And finally the biggest chunk. Executing all these maintenance scripts (especially <code>rebuildall.php</code>) 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 <code>./mediawiki/maintenance</code> and execute
{{code|io|
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 <code>./_opt/scripts/</code> 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 <code>--user</code>. For instance:

  ./protect_pages --user ProtecT0r

{{ambox|text=As of today (18.02.2015) there is a minor bug in the maintenance script that protects pages. It ignores specified user and reason.}}
If you want to fix this, go to <code>./mediawiki/maintenance/</code> and edit <code>protect.php</code>. Change:

<syntaxhighlight lang="php" line start="43">
  public function execute() {
  $userName = $this->getOption( 'u', 'Maintenance script' );
  $reason = $this->getOption( 'r', '' );

  $cascade = $this->hasOption( 'cascade' );
</syntaxhighlight>

into this:
<syntaxhighlight lang="php" line start="43">
  public function execute() {
  $userName = $this->getOption( 'user', 'Maintenance script' );
  $reason = $this->getOption( 'reason', '' );

  $cascade = $this->hasOption( 'cascade' );
</syntaxhighlight>

After you're finished, it is recommended that you run
{{code|lang=io|code=
php rebuildall.php
php runJobs.php
}}
again. :( I know, sucks. But in order to populate the categories, it had to be executed once before.

{{ambox|text=You can use <code>protect_pages</code> later at any time when you have new pages to protect. You can also add more categories and pages to the protection list. Simply create a file <code>protection.list</code> with pages or categorys to protect and run the script in the same dir as the file you created.}}

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 <code>/var/www/mywiki</code> and run
{{code|io|code=
chown -R apache-user:apache-group *
}}
where <code>apache-user</code> is the local username, your apache runs as and <code>apache-group</code> 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:
# Installing [http://www.mediawiki.org/wiki/Extension:DeleteBatch Extension:DeleteBatch] and feed it the names of the pages to delete. You can find files containing the necessary pagenames in <code>./_init/lists/ext_db/package-<packagename>.txt</code>
# Use a maintenance script located in <code>./mediawiki/maintenance</code> together with a prepared text file:
{{code|io|code=
php deleteBatch.php -r "preparing to merge" ../../_init/lists/deletebatch/
}}
{{warning|text='''Untested''' Could be, this doesn't work since the pages are still in the database and importing the platform pages will merely sort their revisons in those of the old platform's and therefore somewhere in the page histories. This would lead to the deletion still being the latest revision and hence not showing the pages at all.}}

=== 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:
{{code|mysql|code=
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 <code>./_init/lists/package/package-*.list</code> 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.
{{warning|text=If you are going to import the generated XML files via [[Special:Import]] make sure they are not to big or otherwise your import will timeout. A good rule of thumb to include max. 100 revisions in all. So either 100 pages with 1 revision or 1 page with 100 revisions.}}

As alternative you can use a [http://www.mediawiki.org/wiki/Manual:DumpBackup.php maintenance script] <code>php dumpBackup.php.--full</code>. 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 <code>./_init/_scripts/</code>:
{{code|bash|code=
./tweak_timestamp FILENAME
}}
This script takes the specified xml-file containing a mediawiki xml dump and replaces all timestamp entries with a current timestamp.
{{warning|text=Importing this file will result in overwriting all corresponding pages! Please make sure you know what you are doing. And of course: make a backup before you import any of these files!}}