Quelltext der Seite 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, [[Project:Installation#Get_the_files|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 ====
<syntaxhighlight lang=php line=1 highlight="11,18,21,22,34">
<?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"

    ...
</syntaxhighlight>
The important settings in the first part are:
# 11: Give your project a name. This shows in the browser title and on various places inside the wiki
# 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
# 21f: contact addresses to use
# 34: Set the (default) logo here. Recommended is to place it on <code>/_images/common</code>, 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.
<syntaxhighlight lang="php" line=1 start="63" highlight="4,5">
    ## Database settings
    $wgDBtype = "mysql";
    $wgDBserver = "localhost";
    $wgDBname = "DBNAME";
    $wgDBuser = "DBUSER";
    #$wgDBpassword = "DBPASSWD";    # set in LocalSettings_host.php
</syntaxhighlight>

==== Namespaces ====
What is a namespace? See [[mw:Help:Namespaces|the documentation on mediawiki.org]] for more about this.
<syntaxhighlight lang="php" line=1 start="81" highlight="4,5,6,7">
    ## 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;
</syntaxhighlight>
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 [[mw:Manual:User_rights#List_of_permissions|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:
* {{code snippet|lang=php|$imtDefaultRoleReader}}, which has only read access
* {{code snippet|lang=php|$imtDefaultRoleContributor}}, which can do basic write operations
* {{code snippet|lang=php|$imtDefaultRoleCurator}}, which has elevated write permissions, and can also perform some gardening operations
* {{code snippet|lang=php|$imtDefaultRoleDeveloper}}, as above, but has also write access to the namespaces modules and templates. Also can configure the mediawiki interface
* {{code snippet|lang=php|$imtDefaultRoleAdministrator}}, as above, but can also perform adminitrative tasks like blocking users, protecting pages, batch deletes, etc.
* {{code snippet|lang=php|$imtDefaultRoleMaintenancebot}}, used for scripts and is based in the curator role.

Let's have a look at the section:
<syntaxhighlight lang="php" line=1 start="96" highlight="5,7,15,18,22">
    ## 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' );
</syntaxhighlight>
* 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 <code>=&</code> 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
{{ambox|type=notice|text=Note that the default user group has been stripped of all permissions. If you want to use this group, assign a role, e.g. {{code snippet|lang=php|code=$wgGroupPermissions['user'] =& $imtDefaultRoleContributor;}}}}

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

<syntaxhighlight lang="php">
    # Nuke
    #wfLoadExtension( 'Nuke' );

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

If you want to integrate additional extensions, place the sources inside the <code>_extensions</code> 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 <code>_extensions</code> and execute
{{code|lang=bash|code=
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'''):
<syntaxhighlight lang="php" line="1" start="35" highlight="5,10,13,21,22">
    ## 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
</syntaxhighlight>

==== Changing credentials ====
The easiest way to do this, is to use [[Project:Software_features#reset_secrets|a script]]. If you want to do it manually, change the following lines:
<syntaxhighlight lang="php" line="1" start="59" highlight="4,8,11">
    ## 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";
</syntaxhighlight>


==== Disable caching ====
Find this line and uncomment the cache type:
<syntaxhighlight lang="php" start="29" line="1">
    ## Caching
    ##########
    # is per default active. you maybe want to disable this on dev or staging systems
    $wgMainCacheType = CACHE_NONE;
</syntaxhighlight>

==== Debugging ====
There is a section at the end where you can add debugging output:
<syntaxhighlight lang="php" start="72" line="1">
    ## 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
</syntaxhighlight>


=== 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 [[Project:Maintenance#Composer|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 <code>LocalSettings_acls.php</code>.

== 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 <code>./_config/LocalSettings.php</code>.

To install apc hit
{{code|bash|
apt-get apc
}}

As a sample configuration you can use this:

{{code|apache|code=
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 <code>/etc/php5/conf.d/apc.ini</code>

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 [http://www.mediawiki.org/wiki/Extension:Scribunto#LuaSandbox here] for a how-to.

You also have to add the following line to your <code>php.ini</code> or to <code>/etc/php5/conf.d/</code>:
{{code|apache|code=
extension=luasandbox.so
}}
Some installations have more than one php.ini file. You have to add the line to both. For instance:
{{code|io|code=
/etc/php5/cli/php.ini
/etc/php5/apache2/php.ini
}}

After you installed the sandbox, modify your <code>LocalSettings_extensions_project.php</code> and add:
<syntaxhighlight lang="php">
  $wgScribuntoDefaultEngine = 'luasandbox';
  $wgScribuntoEngineConf['luasandbox']['memoryLimit'] = 100 * 1024 * 1024;  // default is 50 * 1024 * 1024
  $wgScribuntoEngineConf['luasandbox']['cpuLimit'] = 10;    // default is 7
</syntaxhighlight>

{{ambox|type=notice|text='''Note:''' Since Version 12 of this bundle, the module ''lua'' is configured for a sandbox by default. If you want to disable it, add {{code snippet|lang=php|code=$wgScribuntoDefaultEngine = 'standalone';}} instead.}}


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

{{code|bash|code=
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 <code>_config</code> directory. As you can see, this will raise no warning or error (excerpt from ''LocalSettings.php''):

<syntaxhighlight lang="php">
  ...
  # include and configure extension LDAPAuthentication
  @include_once(__DIR__."/LocalSettings_LDAPAuth.php");
  ...
</syntaxhighlight>