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. Using git at the IMT, the call should look something like this:

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

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

Once you cloned or unziped the files, your file structure should look something like this:

drwxr-xr-x  9 www-data www-data 4096 Dec  9 10:12 .git                           // your repository files
-rw-r--r--  1 www-data www-data  331 Dec  8 08:29 .gitignore                     // ignore files for your repo
-rw-r--r--  1 www-data www-data  101 Dec  3 09:50 .gitmodules                    // listing of all submodules
drwxr-xr-x  2 www-data www-data 4096 Dec  7 15:03 _config                        // this is where your config files are located
drwxr-xr-x 39 www-data www-data 4096 Nov 16 09:49 _extensions                    // this is the assortment of available extensions
drwxr-xr-x 24 www-data www-data 4096 Sep  9 12:45 _images                        // this is your image directory, almost empty after unpacking
drwxr-xr-x  6 www-data www-data 4096 Dec  3 09:50 _opt                           // this is where you find all auxilliary files
lrwxrwxrwx  1 www-data www-data   17 Sep  9 12:45 mediawiki -> mediawiki-1.23.10 // a symbolic link to the current mediawiki core software
drwxr-xr-x 12 www-data www-data 4096 Sep 11 10:49 mediawiki-1.23.10              // the current mediawiki core software
drwxr-xr-x  2 www-data www-data 4096 Dec  9 10:16 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.

Auxilliary files

In ./_opt you can find a bunch of additional files. These are not required for your installation to work, but provide some additional capabilities. Structure is as follows:

-rw-r--r-- 1 www-data www-data   58 Nov 16 09:49 _admin_login.php               // located in this file are the credentials for the local admin login
drwxr-xr-x 3 www-data www-data 4096 Dec  3 09:52 bot                            // a bot adapted to a imt mediawiki project. see there for more information
drwxr-xr-x 5 www-data www-data 4096 Nov 17 09:17 crons                          // here you can place cron jobs in subdirectories. put a script for each job in one of the 
                                                                                // subdirs minutely, hourly, daily. They will called automatically from the system.
drwxr-xr-x 6 www-data www-data 4096 Dec  8 13:16 init                           // contains files and dumps for initial content
drwxr-xr-x 2 www-data www-data 4096 Dec  8 14:03 scripts                        // contains helper scripts

Available helper scripts

These scripts are available for you to help you in your wiki related tasks. Most of them have a help page. Just call the script with parameter --help.

-rwxr-xr-x 1 www-data www-data  6311 Dec  8 11:03 create_dumps                   // takes all *.list files in the current dir (except protection.list) and creates an xlm file each
-rwxr-xr-x 1 www-data www-data   549 Dec  7 09:45 fetch_sources_for_1.23         // call this with subversion number as parameter to get new sources.
                                                                                 // should not be necessary, if you update your repo regularly
-rwxr-xr-x 1 www-data www-data   878 Dec  7 09:46 get_new_version_going          // a small script to initialize a new version (update, not upgrade) of the mediawiki software
-rw-r--r-- 1 www-data www-data    18 Dec  8 08:28 .gitignore                     // a list of files to ignore in the repo
-rwxr-xr-x 1 www-data www-data  4720 Dec  8 12:57 import_dumps                   // imports all .xml files in the current directory or the supplies xml file.
-rwxr-x--- 1 www-data www-data 16364 Dec  8 13:13 init                           // helps you to get your installation going
-rw-r----- 1 www-data www-data   579 Dec  8 11:37 init.config                    // holds configuration for your initialization
-rw-r--r-- 1 www-data www-data    11 Dec  8 14:03 init.lock                      // after you initialized your system, this file will be present
                                                                                 // to warn you, if you accidently execute init a second time
-rwxr-xr-x 1 www-data www-data  5031 Dec  8 11:09 protect_pages                  // looks for a list of pages to protect in the current dir and protects them
-rwxr-xr-x 1 www-data www-data  1194 Nov 16 09:49 tweak_timestamp                // a crude helper scripts that simply updates all timestamps in a
                                                                                 // mediawiki dump xml file. so that, after an import, the imported article will show
-rwxr-x--- 1 www-data www-data  4357 Dec  8 13:33 update_content                 // creates up-to-date versions of your project's dump files, as long as there
                                                                                 // are *.list files present in _opt/init/local_content
-rwxr-x--- 1 www-data www-data   493 Dec  8 07:03 url                            // returns your projects url
-rw-r--r-- 1 www-data www-data   182 Dec  8 13:11 url.config                     // present after running init for the first time.
                                                                                 // here you can customize your project's url

create_dumps

Usage:

• Switch to a dir that contains at least one file ending with .list
• or call with the name of a file as argument

The script then produces an xml dump (for all list files or the supplied file only). As default, only the current revision will be dumped, use argumment --full to geht the file's full history. The script processes the list file(s) and

• ignores empty lines or lines beginning with a #
• dumps all contents of a given category, if the line starts either with "Category:" or the equivalent of your locale. Excludes subcategories
• dumps the category page, if page name starts with a :Category:
• in every other case, dumps the pagename.

Example:

# this is a comment.
# btw: the following line will also be ignored

# normal page, will be dumped:
Normal Page
# will also be dumped normally:
Namespace4:Funnypage
# and again: dumped directly, no special treatment:
:Category:Funny pages
# now the interesting part
# this category will be dumped. also: all pages, contained in this category, except subcategories
Category:Interesting facts

Note: This script uses the url, supplied in your LocalSettings_host.php. To be more specific, it uses the url the helper script url returns. See there for more information.

More help is available via parameter --help.

fetch_sources_for_1.23

NOTE: You should have no need of this script, if you update your repo regularly.

Supply a subversion of 1.23 (for example 42) and the script will download and extract this subversion in your base dir. After execution, you will find a new dir, e.g. named mediawiki-1.23.42 in your basedir containing the downloaded sources. Call get_new_version_going next.

get_new_version_going

NOTE: You should have no need of this script, if you update your repo regularly.

A small script to initialize a new version (update, not upgrade) of the mediawiki software. You need to be in the new versions directory and a symlink named "mediawiki" to your current version should exist in your basedir.

import_dumps

Usage:

• Switch to a dir that contains at least one medaiwiki dump file ending with .xml
• or call with the name of a mediawiki dump file as argument

This imports all .xml files in the current directory or the supplies xml file in your mediawiki. Useful to call in your ./_opt/init/local_content dir if you want to update your project's content/engine files or even in the ./_opt/init/base_content/default dir if you want to update the package's base files

More help is available via parameter --help.

init

This is an installation wizard for a mediawiki installation. See Finalize, the easy way for more information.

Files belonging to this script are:

• init.config: holds configuration for your initialization
• init.lock: after you initialized your system, this file will be present to warn you, if you accidently execute init a second time

More help is available via parameter --help.

protect_pages

Looks for a file named protection.list in the current dir and protects all pages or all pages in categories listed in it.

Note: This script uses the url, supplied in your LocalSettings_host.php. To be more specific, it uses the url the helper script url returns. See there for more information.

More help is available via parameter --help.

tweak_timestamp

A crude helper scripts that simply updates all timestamps in a mediawiki dump xml file. This fakes the dump file's last revision dates to be NOW so that each page contained in the dump file will automatically have a new revision showing in its page histories.

update_content

Creates up-to-date versions of your project's dump files, as long as there are *.list files present in _opt/init/local_content. When called with parameter --base it updates the base installation files instead.

This script uses the create_dumps and should be used to generated updated xmls for your project. It is probably used only on dev systems.

More help is available via parameter --help.

url

Returns your project's url. This will be fetched from your LocalSettings_host.php or - if present - from a configfile named url.config. If you didn't run init and/or you need a different url than that provided in your config, just create a file named url.config and fill it with the hostname you want. Use this as template:

# this is a configuration script for the instance's url retrival
# as long as this file is present, all scripts will use the url stored here
URL=https://hostname.domain.org

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

Configuration files

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

-rw-r--r-- 1 www-data www-data  4445 Dec  3 09:50 LocalSettings_acls.php               // defines default roles, you can use later. also sets some basic permissions
-rw-r--r-- 1 www-data www-data  6845 Nov 16 09:49 LocalSettings_extensions.php.sample  // sample file for extension configuration data
-rw-r--r-- 1 www-data www-data  4804 Nov 12 11:54 LocalSettings_host.php.sample        // sample file for your personal host configuration. you have to edit this!
-rw-r--r-- 1 www-data www-data 10664 Dec  3 09:50 LocalSettings_LDAPAuth.php           // ldap configuration. only needed, if you use ldap auth, of course
-rw-r--r-- 1 www-data www-data  8433 Nov 16 09:49 LocalSettings.php                    // general settings

and here is how it must look like:

-rw-r--r-- 1 www-data www-data  4445 Dec  3 09:50 LocalSettings_acls.php               // defines default roles, you can use later. also sets some basic permissions
-rw-r--r-- 1 www-data www-data  6762 Nov 12 12:04 LocalSettings_extensions.php         // here you can add, remove, and configure extensions
-rw-r--r-- 1 www-data www-data  6845 Nov 16 09:49 LocalSettings_extensions.php.sample  // sample file for extension configuration data
-rw-r--r-- 1 www-data www-data  4832 Nov 12 12:03 LocalSettings_host.php               // your personal host configuration, ready to use
-rw-r--r-- 1 www-data www-data  4804 Nov 12 11:54 LocalSettings_host.php.sample        // sample file for your personal host configuration. you have to edit this!
-rw-r--r-- 1 www-data www-data 10664 Dec  3 09:50 LocalSettings_LDAPAuth.php           // ldap configuration. only needed, if you use ldap auth, of course
-rw-r--r-- 1 www-data www-data  8433 Nov 16 09:49 LocalSettings.php                    // general settings

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

LocalSettings.php

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

 98   ## Shared memory settings
 99   #$wgMainCacheType = CACHE_NONE;
100   $wgMainCacheType = CACHE_ACCEL;
101   $wgEnableSidebarCache=true;
102   $wgMemCachedServers = array();
103   ...

• uncomment line 99
• comment line 100 through 102

also, if you don't use LDAP, disable the inclusion of the LDAP config by commenting out line 232:

221   ## include some configfiles
222   # all other extensions will be included and configured in an external file
223   include_once(__DIR__."/LocalSettings_extensions.php");
224 
225   # finally the access control lists i.e. user/group permissions
226   include_once(__DIR__."/LocalSettings_acls.php");
227 
228   # include host specific settings
229   include_once(__DIR__."/LocalSettings_host.php");
230 
231   # include and configure extension LDAPAuthentication
232   include_once(__DIR__."/LocalSettings_LDAPAuth.php");
233   ...

LocalSettings_host.php

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

  1 <?php
  2 # ***************************** NOTE *****************************
  3 # It is important that you adjust the following line at the end of LocalSettings.php to match your layout:
  4 #
  5 # define("toConfigPath", "/var/www/<yourwikiname>/_config");
  6 
  7 # this is a special config file for all host specific settings like database, etc.
  8 
  9 ## Sitespecific information:
 10 # Name of Site (and Project space)
 11 $wgSitename = "YOURSITENAME";
 12 $wgMetaNamespace = "Project";
 13 
 14 # Contact adresses
 15 $wgEmergencyContact = "webmaster@domain"; // one of your email accounts
 16 $wgPasswordSender = "webmaster@domain";   // one of your email accounts
 17 
 18 # we store the name of our localhost in this varibale, so we can use it later
 19 $xgNameLocalhost = "yourhostname.domain"; // your fully quallified host name
 20 
 21 # Site language code, should be one of the list in ./languages/Names.php
 22 $wgLanguageCode = "en";
 23 
 24 # The relative URL path to the logo. Make sure you change this from the default,
 25 # or else you'll overwrite your logo when you upgrade!
 26 #$wgLogo = "$wgStylePath/common/images/wiki.png";
 27 #$wgLogo = "/img_auth.php/f/f4/MyUploadedLogo.png"; # when using img_auth.pgp (see below)
 28 $wgLogo = "$wgScriptPath/images/common/logo.jpg";   // we recommend storing your wikilog in _images/common
 29 
 30 
 31 ## File handling
 32 # To enable image uploads, make sure the 'images' directory
 33 # is writable, then set this to true:
 34 $wgEnableUploads = true;
 35 $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
 36 
 37 # for handling files via img_auth
 38 #$wgUploadPath = "$wgScriptPath/img_auth.php";
 39 
 40 # when using img_auth.php, you can specify a different file directory.
 41 # remember: this must be within apache's open_basedir, but not necessary below DOCUMENT_ROOT
 42 #$wgUploadDirectory = '/var/www/<yourwikiname>/_images'
 43 
 44 # default allowed file extensions are: .gif, .jpg, .jpeg, .png, .tar, .zip, .rar, .pdf, .svg
 45 # you can specify more here:
 46 #$wgFileExtensions[] = ".tif"
 47 #$wgFileExtensions[] = ".tiff"
 48 
 49 
 50 ## The protocol and server name to use in fully-qualified URLs
 51 $wgServer = "https://".$xgNameLocalhost;            // DO NOT TOUCH
 52 
 53 
 54 ## Database settings
 55 $wgDBtype = "mysql";
 56 $wgDBserver = "localhost";
 57 $wgDBname = "DBNAME";
 58 $wgDBuser = "DBUSER";
 59 $wgDBpassword = "DBPASSWD";
 60 
 61 
 62 ## some secret keys
 63 # Note: $wgSecretKey: [0-9a-z]{64}
 64 $wgSecretKey = "4207ee50e0e84aad131214b2ede66f206ca3b94a00fbecc3b25c62e4e38a96c9";
 65 
 66 # Site upgrade key. Must be set to a string to turn on the
 67 # web installer while LocalSettings.php is in place
 68 # Note: if you want web updates set $wgUpgradeKey to a random string [0-9a-z]{16}
 69 $wgUpgradeKey = false;
 70 
 71 
 72 ## Namespace configuration
 73 # including new definition of access rights that have to be assigned to these role arrays:
 74 # $imtDefaultRoleContributor, $imtDefaultRoleCurator, $imtDefaultRoleDevelope, $imtDefaultRoleAdministrator, or $imtDefaultRoleMaintenancebot
 75 #define("NS_META", 3500);
 76 #define("NS_META_TALK", 3501);
 77 #$wgExtraNamespaces[NS_META] = "Meta";
 78 #$wgExtraNamespaces[NS_META_TALK] = "Meta_talk";
 79 #$wgNamespacesWithSubpages[NS_META] = true;
 80 #$wgNamespaceProtection[NS_META] = array( 'write_in_NS_META' );
 81 #$imtDefaultRoleContributor["write_in_NS_META"] = true;
 82 #$imtDefaultRoleCurator["write_in_NS_META"] = true;
 83 #$imtDefaultRoleDeveloper["write_in_NS_META"] = true;
 84 #$imtDefaultRoleAdministrator["write_in_NS_META"] = true;
 85 
 86 
 87 ## Access control
 88 # public or not
 89 # by default, content can only be viewed after a successful login
 90 # with this setting, however, your wiki is free to READ for all:
 91 #$wgGroupPermissions['*'] =& $imtDefaultRoleReader;
 92 # if you configured the use of img_auth above, you also have to uncomment this:
 93 #$wgImgAuthPublicTest = false;
 94 
 95 # access roles: you can assign default roles or use an array with custom rights
 96 # default roles are: $imtDefaultRoleContributor, $imtDefaultRoleCurator, $imtDefaultRoleDevelope, $imtDefaultRoleAdministrator, or $imtDefaultRoleMaintenancebot
 97 # note:
 98 # * 'user' (the group of authenticated user) already has the role contributor
 99 # * 'imt-web' (imt's application managers) already has the role administrator
100 # * 'imt-mediawiki-maintenance' (ldap bot accounts) already has the role maintenancebot
101 # also remember: an ldap group used here must have the ldap group attribute 'Wiki Gruppe'
102 #$wgGroupPermissions['sample group'] =& $imtDefaultRoleAdministrator;
103 
104 # you can restrict login to a list of groups (each of which has its users added to wiki group 'user' automatically)
105 #$imtGrantAccessRoles = array( 'sample_group' );
106 
107 # you can also deny access for a list of groups
108 # remember: an ldap group used here also must have the ldap group attribute 'Wiki Gruppe'
109 #$imtDenyAccessRoles = array( 'blacklist_group' )
110 ?>

Your tasks here are:

1. Line 11: specify the name of your site
2. Line 12: specify the name of your project's namespace. this usually is either "Project" (or your language equivalent) or your project id (e.g. "imtkb")
3. Line 15f: email contact addresses
4. Line 19: give here your fully qualified host name, e.g. en.wikipedia.org
5. Line 22: here you choose your language locale (e.g. en, de, au, ...)
6. Line 28: specify the location or your wiki's logo. we recommend putting it in ./_images/common
7. Line 34: is for enabling (or disabling) file uploads
8. Line 35: 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.
9. Line 38,42: This section deals with a secure image wrapper. if you have to use it, configure it here. See here for further details.
10. Line 51: We'll mention it here again: as it says in the comment: DO NOT TOUCH (unless of course you really know what you do)
11. Line 55ff: configure your database connection here. Specify database, database user and database user's password here like you set it up earlier.
12. Line 64: For security reasons you must personalize $wgSecretKey

1. Line 69: Webupdate is disabled by default. If you need this, set $wgUpgradeKey accordingly
2. Line 72ff: Here begins the namespace configuration. you can take the dollowing lines as templates and define one or more new namespaces
   1. Line 75f: specify a unique constant name for a namespace id. The ids must be unique and should not be lower than 3500. Remember to specify a corresponding talk namespace
   2. Line 77f: Like this you can assign a name to your namespace. Be careful not to pick an existing one
   3. Line 79: If you want subpages enabled in your namespace,
   4. Line 80ff:You can restrict write access to your namespace. remember to assign a corespronding permissin to a role/roles
3. Line 87ff: Here you have to assign roles to security groups. See Access control for more information.

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#Composer 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:

177   # Scribunto (hope, this thing works out)
178   require_once( "$IP/extensions/Scribunto/Scribunto.php");
179   $wgScribuntoUseGeSHi = true;  # adds GeSHi-capabilities to scribunto
180   $wgScribuntoUseCodeEditor = true; # lets Scribunto use the CodeEditor
181   $wgScribuntoDefaultEngine = 'luastandalone';
182   #$wgScribuntoDefaultEngine = 'luasandbox';
183   $wgScribuntoEngineConf['luasandbox']['memoryLimit'] = 100 * 1024 * 1024;  // default is 50 * 1024 * 1024
184   $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

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 should customize your init. To do this switch to

./_opt/scripts

and edit init.config. It looks like this:

 1 # configuration file for script init
 2 
 3 # use this database collation. supported are utf8 and bin
 4 COLLATION=utf8
 5 
 6 # instance language. supported are de, en
 7 LANG=de
 8 
 9 # this is your apache user and apache usergroup
10 APACHERUNSAS=www-data:www-data
11 
12 # switches for all the optional base packages
13 OPT_BOILERPLATES=1
14 OPT_GADGETS=1
15 OPT_KERBEROS=1
16 
17 # contribute image imports and page protections to this username
18 USERNAME=
19 
20 # you can specify database settings here. normally, they are obtained
21 # from LocalSettings_host.php automatically, though.
22 # nevertheless, entries specified here must match your configured settings
23 DBSERVER=
24 DATABASE=
25 DBUSER=
26 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 10: when init is finished it runs a chown -R with this as a username/usergroup. if you want to skip the execution of chown, set this to an empty string
• Line 13ff: There are three optional packages you can import. set the corresponding entry to something different than 1 to disable the package. Note: When no using Kerberos, you should comment out the inclusion of LocalSettings_LDAPAuth.php in your LocalSettings.php.
• Line 18: If you want to contribute file uploads and page protections to a local user, set USERNAME accordingly
• Line 23: init should be able to obtain database information from your 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 {} \;

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-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 a maintenance script So please go ti ./mediawiki/maintenance and run:

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

43   public function execute() {
44   $userName = $this->getOption( 'u', 'Maintenance script' );
45   $reason = $this->getOption( 'r', '' );
46 
47   $cascade = $this->hasOption( 'cascade' );

into this:

43   public function execute() {
44   $userName = $this->getOption( 'user', 'Maintenance script' );
45   $reason = $this->getOption( 'reason', '' );
46 
47   $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.