Projekt:Software customization

There are several ways to customize the Mediawiki platform. Here, we shed some light on the common ones:

• How can I start my own project
• How can I adapt an existing project
• What interconnections are there with external packages

Creating your own project

When you work with the IMT git, get yourself a clean copy and switch to master branch. You should probably make a new branch for your project so that you don't accidently push your customizations into origin/master. If you don't have access to a clean master, copy an existing project and remove LocalSettings_host.php and LocalSettings_extensions.php. Also take extra care not to keep settings from the original project in LocalSettings_project.php

LocalSettings_project.php

Here you setup basic configuration for your project - all settings that are used on all the hosts belonging to your project (or at least some defaults that can be overridden on a host bases). This basic configuration includes:

• Site Configuration
• Database settings (excluding password)
• Namespaces
• ACLs

We'll cover them step-by-step.

Site Configuration

<?php
    # ***************************** NOTE *****************************
    # this is a special config file for all project specific defaults
    # especially general acl and namespace definitions are to be found
    # here.
    #

    ## Sitespecific information:
    # Name of Site (and Project space)
    # place your project sitename here. overwrite on dev or staging, using LocalSettings_host.php
    $wgSitename = "YOURSITENAME";
    $wgMetaNamespace = "Projekt";

    # Server name
    # The protocol and server name for your project to use in fully-qualified URLs
    # you should configure the service url of your project here, e.g. https://project.uni-paderborn.de
    # if you are on staging or dev, overwrite in LocalSettings_host.php
    $wgServer = "https://yourproject.domain";

    # Contact adresses
    $wgEmergencyContact = "thatsme@domain"; // one of your email accounts
    $wgPasswordSender = "thatsme@domain";   // one of your email accounts

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

    # 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!
    # on dev or staging, overwrite in LocalSettings_host.php
    # note: the logo should have a size of 135x135
    #$wgLogo = "$wgStylePath/common/images/wiki.png";
    #$wgLogo = "/images/f/f4/MyUploadedLogo.png";   # when using an uploaded image
    #$wgLogo = "/img_auth.php/f/f4/MyUploadedLogo.png"; # when using img_auth.pgp (see below)
    $wgLogo = "$wgScriptPath/images/common/logo.jpg";   // we recommend storing your wikilog in _images/common

    # since 1.25, we also have the opportunity to add a hd logo;
    # currently 1.5x and 2x are supported (meaning 2x logo can have 270x270)
    #$wgLogoHD = array(
    #   "1.5x" => "path/to/1.5x_version.png",
    #   "2x" => "path/to/2x_version.png"
    #);


    ## File handling
    # To enable image uploads, make sure the 'images' directory
    # is writable, then set this to true:
    $wgEnableUploads = true;

    # for handling files via img_auth, uncomment the following line and set $wgUploadDirectory
    #$wgUploadPath = "$wgScriptPath/img_auth.php";

    # when using img_auth.php, you can specify a different file directory.
    # remember: this must be within apache's open_basedir, but not necessary below DOCUMENT_ROOT
    #$wgUploadDirectory = '/var/www/<yourwikiname>/_images'

    # default allowed file extensions are: .gif, .jpg, .jpeg, .png
    # you can specify more here:
    $wgFileExtensions[] = "svg";
    $wgFileExtensions[] = "pdf";
    #$wgFileExtensions[] = "tif"
    #$wgFileExtensions[] = "tiff"

    ...

The important settings in the first part are:

1. 11: Give your project a name. This shows in the browser title and on various places inside the wiki
2. 18: Here you define the default host name. Good practice is to set the name of your live system here, e.g. hilfe.uni-paderborn.de
3. 21f: contact addresses to use
4. 34: Set the (default) logo here. Recommended is to place it on /_images/common, which will result in a setting as shown in line 33.

Database

You configure most of the settings for your database connection in this file. The password, however, is the be found in LocalSettings_host.php, so you can differenct credentials on different systems.

    ## Database settings
    $wgDBtype = "mysql";
    $wgDBserver = "localhost";
    $wgDBname = "DBNAME";
    $wgDBuser = "DBUSER";
    #$wgDBpassword = "DBPASSWD";    # set in LocalSettings_host.php

Namespaces

What is a namespace? See the documentation on mediawiki.org for more about this.

    ## Namespace configuration
    # including new definition of access rights that have to be assigned to these role arrays:
    # $imtDefaultRoleContributor, $imtDefaultRoleCurator, $imtDefaultRoleDeveloper, $imtDefaultRoleAdministrator, or $imtDefaultRoleMaintenancebot
    define("NS_META", 3500);
    define("NS_META_TALK", 3501);
    $wgExtraNamespaces[NS_META] = "Meta";
    $wgExtraNamespaces[NS_META_TALK] = "Meta_talk";    # NOTE: It is important to use a underscore in namespace name
    $wgNamespacesWithSubpages[NS_META] = true;
    $wgNamespaceProtection[NS_META] = array( 'write_in_NS_META' );
    $imtDefaultRoleContributor["write_in_NS_META"] = true;
    $imtDefaultRoleCurator["write_in_NS_META"] = true;
    $imtDefaultRoleDeveloper["write_in_NS_META"] = true;
    $imtDefaultRoleAdministrator["write_in_NS_META"] = true;

This block can serve as a template for namespace definition. The four highlighted lines are mandatory. Also: Do not uses spaces in namespace names (use underscores instead).

You can configure a namespace further by enabling subpages and setup a namespace protection. The latter will only allow users with the appropriate role to write in this namespace.

ACLs

Access to certain features in mediawiki is governed by permissions. These are bound to groups and as soon as a user is in a certain group, he has all the appropriate rights. For more about the individiual permissions, please consult the documentation on mediawiki.org.

For ease of use, this plattform defines a list of roles with predefined permission sets. You can simply assign one of this roles to a group. The available groups are:

• $imtDefaultRoleReader, which has only read access
• $imtDefaultRoleContributor, which can do basic write operations
• $imtDefaultRoleCurator, which has elevated write permissions, and can also perform some gardening operations
• $imtDefaultRoleDeveloper, as above, but has also write access to the namespaces modules and templates. Also can configure the mediawiki interface
• $imtDefaultRoleAdministrator, as above, but can also perform adminitrative tasks like blocking users, protecting pages, batch deletes, etc.
• $imtDefaultRoleMaintenancebot, used for scripts and is based in the curator role.

Let's have a look at the section:

    ## Access control
    # public or not
    # by default, content can only be viewed after a successful login
    # with this setting, however, your wiki is free to READ for all:
    #$wgGroupPermissions['*'] =& $imtDefaultRoleReader;
    # if you configured the use of img_auth above, you also have to uncomment this:
    #$wgImgAuthPublicTest = false;

    # access roles: you can assign default roles or use an array with custom rights
    # default roles are: $imtDefaultRoleReader, $imtDefaultRoleContributor, $imtDefaultRoleCurator, $imtDefaultRoleDeveloper, $imtDefaultRoleAdministrator, or $imtDefaultRoleMaintenancebot
    # note:
    # * 'user' (the group of authenticated user) already has the role contributor
    # * 'imt-mediawiki-maintenance' (ldap bot accounts) already has the role maintenancebot
    # also remember: an ldap group used here must have the ldap group attribute 'Wiki Gruppe'
    #$wgGroupPermissions['sample group'] =& $imtDefaultRoleAdministrator;

    # you can restrict login to a list of groups (each of which has its users added to wiki group 'user' automatically)
    #$imtGrantAccessRoles = array( 'sample_group' );

    # you can also deny access for a list of groups
    # remember: an ldap group used here also must have the ldap group attribute 'Wiki Gruppe'
    #$imtDenyAccessRoles = array( 'blacklist_group' );

• 100,102: If you want your wiki to be public readable, uncomment these two lines
• 110: this line shows an example on how to define a permission group. If you use the ldap extension, name your ldap group here. Pleae note the =& operator! Use it to make sure, changes to the roles later in LocalSettings_extensions.php is propagated back to your group.
• 113: If you want to restrict login to members of certain (ldap) groups, name them here. If you keep it commented, all valid accounts are able to login.
• 117: furthermore, if you want to deny login to certain (ldap) groups, name them here

LocalSettings_project_extensions.php

If you want your project to have additional extensions, configure them here and not in LocalSettings_extensions.php. For most of the shipped extensions there is an entry here (if they are not a default extension, that is). Just uncomment the include/loader command. For example:

    # Nuke
    #wfLoadExtension( 'Nuke' );

    # our otrsconnector
    #require_once( "$IP/extensions/OtrsConnector/OtrsConnector.php" );
    $wgOtrsConnectorMailtoAddress = "imt@uni-paderborn.de";
    $wgOtrsConnectorOtrsAddress = "otrs.uni-paderborn.de";

If you want to integrate additional extensions, place the sources inside the _extensions directory and add the loader command in LocalSettings_project_extensions.php. It is recomended, to add extensions as submodules instead of downloading the sources. If you want to do this, venture in _extensions and execute

git submodule add https://gerrit.wikimedia.org/r/p/mediawiki/extensions/WikiEditor.git

For more information about the configuration of a certain extension, please see its documentation page.

Configuring your host

You also need a host specific config file - at least for your database credentials and your session hash token.

What you can also do with this config file is to override some (project-)defaults. For instance you could disable caching on a dev system, give your staging system a different logo or add additional permissions for your testing team. Every setting from LocalSettings.php and LocalSettings_project.php can be overwritten here. We will not show this in detail, just add the neccessary lines somewhere in the file.

Not on productive system

When you are not on your main/live/productive, you maybe want to change some settings in addition to your host name (which you have to set):

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

    # The protocol and server name to use in fully-qualified URLs
    # Default for project is found in LocalSettings_project.php; overwrite in project or staging here
    $wgServer = "https://yourhostname-staging.domain";

    # note, that if you're running a semantic media wiki, uncomment this and specify your host (w/o protocol) again
    enableSemantics( "yourhostname-staging.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-stage.jpg";

    # Contact adresses
    # 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

Changing credentials

The easiest way to do this, is to use a script. If you want to do it manually, change the following lines:

    ## 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";

Disable caching

Find this line and uncomment the cache type:

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

Debugging

There is a section at the end where you can add debugging output:

    ## debug
    ########
#   error_reporting(E_ALL);
#   ini_set ("display_errors", "1");
#   $wgShowExceptionDetails = true;
#   $wgMainCacheType = CACHE_NONE;
#   $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

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.

External Components

There are some features of this platform, that needs "external" help to work:

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.

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.

You also 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

After you installed the sandbox, modify your LocalSettings_extensions_project.php and add:

  $wgScribuntoDefaultEngine = 'luasandbox';
  $wgScribuntoEngineConf['luasandbox']['memoryLimit'] = 100 * 1024 * 1024;  // default is 50 * 1024 * 1024
  $wgScribuntoEngineConf['luasandbox']['cpuLimit'] = 10;    // default is 7

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

Disabling LDAP

If you don't want to use LDAP, rename or remove LocalSettings_LDAPAuth.php in your _config directory. As you can see, this will raise no warning or error (excerpt from LocalSettings.php):

  ...
  # include and configure extension LDAPAuthentication
  @include_once(__DIR__."/LocalSettings_LDAPAuth.php");
  ...