Quelltext der Seite Projekt:Software overview

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

<syntaxhighlight lang="io">
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
-rw-r-----  1 www-data www-data 2462 Oct 24 09:42 ___first_steps                 // a short installation instruction
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
drwxr-xr-x  6 www-data www-data 4096 Oct 12 07:48 _skins                         // this is the assortment of available skins
lrwxrwxrwx  1 www-data www-data   17 Sep  9 12:45 mediawiki -> mediawiki-1.31.15 // a symbolic link to the current mediawiki core software
drwxr-xr-x 12 www-data www-data 4096 Sep 11 10:49 mediawiki-1.31.15              // 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
</syntaxhighlight>

Placing the config files, extensions, skins and uploaded files in directories parallel to the mediawiki software and not (as per default) inside it, has 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
** especially as skins and extensions are mostly integrated as submodules, their paths would all have to be adjusted every time the core updates
* 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 is 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:
{{code|lang=bash|code=
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.

=== Core files ===
You can see that there is a folder named <code>mediawiki-1.nn.m</code> that holds all core files from MediaWiki version ''1.nn.m''. There also is a symbolic link named <code>mediawiki</code> pointing to that directory. This makes sure, that you don't have to edit your <code>apache.conf</code> every time you update your core. Also, you can keep old core files as a precaution and only need to adjust the symbolic link.

Your core directory however looks something like this (excerpt):
<syntaxhighlight lang="io">
-rw-r-----  1 www-data www-data   4159 Oct 11 09:47 api.php
-rw-r-----  1 www-data www-data 112767 Oct 11 09:47 autoload.php
drwxr-x---  2 www-data www-data   4096 Oct 11 09:47 cache
-rw-r-----  1 www-data www-data   2747 Oct 11 14:36 composer.json                                     // core composer.json file. comes bundled with the core software. you should not touch this
-rw-r-----  1 www-data www-data    102 Oct 11 09:47 composer.local.json-sample                        // sample for a composer.local.json file. use this for your customization
-rw-r-----  1 www-data www-data  92613 Oct 11 14:36 composer.lock
...
lrwxrwxrwx  1 www-data www-data     14 Oct 11 09:47 extensions -> ../_extensions                      // symbolic link to the directory, holding all extension files
...
-rw-r-----  1 www-data www-data     19 Dec  7 14:02 .htaccess -> .htaccess.operation                  // symbolic link to the .htaccess used according to the current mode
-rw-r-----  1 www-data www-data    945 Oct 11 09:47 .htaccess.maintenance                             // active in maintenance mode. blocks all access except from a certain subnet
-rw-r-----  1 www-data www-data    319 Oct 11 09:47 .htaccess.operation                               // active in operation mode. does url shortening
lrwxrwxrwx  1 www-data www-data     10 Oct 11 09:47 images -> ../_images                              // symbolic link to the directory, holding all uploaded files
...
lrwxrwxrwx  1 www-data www-data     28 Oct 11 09:47 LocalSettings.php -> ../_config/LocalSettings.php // symbolic link to LocalSettings.php in your _config directory
drwxr-x--- 17 www-data www-data  12288 Oct 20 10:54 maintenance                                       // here, mediawiki maintenance scripts are located
...
lrwxrwxrwx  1 www-data www-data     10 Oct 11 09:47 skins -> ../_skins/                               // symbolic link to the directory, holding all extension files
...
drwxr-x--- 25 www-data www-data   4096 Oct 11 14:36 vendor                                            // composer's vendor directory. created and filled by composer
-rw-r-----  1 www-data www-data     98 Oct 11 09:48 wiki.phtml
</syntaxhighlight>

The script [[Project:Software features#get_new_version_going|get_new_version_going]] replaces the dirs/config file with smybolic links, creates the .htaccess files and copies your composer.local.json from your previous installation. It also runs [[#Composer|composer]] for you, if wanted.

=== Configuration files ===
Here is an overview of all files in your <code>_config</code> directory:

<syntaxhighlight lang="io">
-rw-r-----  1 www-data www-data  4192 Dec  6 12:37 LocalSettings_acls.php                       // here, user permissions are bundled into 5 (6) available roles
-rw-r-----  1 www-data www-data  4192 Dec  6 12:37 LocalSettings_base.php                       // base configuration settings, applicable to all projects
-rw-r-----  1 www-data www-data  6633 Dec  6 12:59 LocalSettings_extensions.php                 // the globally installed extensions, available across all projects
-rw-r-----  1 www-data www-data  3498 Dec  6 12:15 LocalSettings_host.php                       // host specific configuration settings. MANDATORY
-rw-r-----  1 www-data www-data  2981 Oct 11 09:48 LocalSettings_host.sample.php                // template for your host config file
-rw-r-----  1 www-data www-data 11521 Dec  6 12:39 LocalSettings_LDAPHub.php                    // holds all settings and extension calls for LDAP authentication
-rw-r-----  1 www-data www-data 10011 Dec  6 13:10 LocalSettings.php                            // original config file, only augmented by loading of additional config
-rw-r-----  1 www-data www-data  5400 Nov 10 15:09 LocalSettings_project.php                    // all project specific settings 
-rw-r-----  1 www-data www-data  3392 Dec  6 12:40 LocalSettings_project_extensions.php         // project extensions and project specific extension settings.
                                                                                                // not included in master branch. OPTIONAL FILE
-rw-r-----  1 www-data www-data  3392 Dec  6 12:40 LocalSettings_project_extensions.sample.php  // template for your project_extensions.php file.
</syntaxhighlight>

==== Loading order ====
# LocalSettings.php
# LocalSettings_base.php
# LocalSettings_acls.php
# LocalSettings_extensions.php
# LocalSettings_project.php
# LocalSettings_project_extensions.php
# LocalSettings_host.php
# LocalSettings_LDAPHub.php
# LocalSettings_maintenance.php

Note that once an extension is loaded in one of the config files it can not be unloaded. Also: an extension normally initializes its config settings, so trying to configure an extension before it is loaded usually fails. However, you can overwrite any config settings in one of the subsequently loaded config files.

==== LocalSettings.php ====
The config file "shipped" with the distribution. Augmented by loading of all other config files. '''You should not edit this file!'''

==== LocalSettings_base.php ====
This contains all the changes to the basic settings, setting some defaults that are used in all projects. '''You should not edit this file!'''

==== LocalSettings_acls.php ====
Provides you with some sample roles, you can set your groups to. How this is done is shown in [[#LocalSettings_project.php|LocalSettings_project.php]]. Available roles are:
* <code>$imtDefaultRoleReader</code>: Only has read permissions, '''cannot''' edit his own user page, preferences, info or watchlist.
* <code>$imtDefaultRoleContributor</code>: Can also create and edit pages (including his own user page, , preferences, info and watchlist). No access to gardening operations
* <code>$imtDefaultRoleCurator</code>: Also has access to gardeing operations like move, delete, rename pages, including permission to use the help namespace
* <code>$imtDefaultRoleDeveloper</code>: Also has access to the mediawiki, module, and template namespace.
* <code>$imtDefaultRoleAdministrator</code>: Holds permissions to powerful operations like mass delete, block users, edit user css and js pages and so on
* <code>$imtDefaultRoleMaintenancebot</code>: This is only used for bots. Its permissions are based on the curator role with some special settings needed for script operations.

'''This file should not be edited.''' You can use the roles in your project or host file and even customize them there.

==== LocalSettings_extensions.php ====
This one loads and configures all base extensions that are available throughout your projects. '''Please do not edit here!'''. If you want to load additional extensions, please use <code>LocalSettings_extensions_project.php</code>. You can overwrite the base extensions' settings there also. A noteable exception are extensions loaded by [[#Composer|composer]].

==== LocalSettings_project.php ====
Here you set your project specifics. You can find comments for every suggested setting in the file, but of course you are not limited to them. Feel free to add all the mediawiki config settings you need. Also configure access rights here. Refrain from including extensions though, since then some [[Project:Software features#Helper scripts|Helper scripts]] will fail. Use [[#LocalSettings_extensions_project.php|LocalSettings_extensions_project.php]] instead.

{{collapse top|title=Template <code>LocalSettings_project.php</code>}}
{{code|lang=php|line=1|code=
<?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 = "webmaster@uni-paderborn.de"; // one of your email accounts
    $wgPasswordSender = "webmaster@uni-paderborn.de";   // 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 protocol and server name to use in fully-qualified URLs
    $wgServer = "https://".$xgNameLocalhost;            // DO NOT TOUCH


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



    ## some secret keys
    # Note: $wgSecretKey: [0-9a-z]{64}
    #$wgSecretKey = "4207ee50e0e84aad131214b2ede66f206ca3b94a00fbecc3b25c62e4e38a96c9"; # set in LocalSettings_host.php

    # Site upgrade key. Must be set to a string to turn on the
    # web installer while LocalSettings.php is in place
    # Note: if you want web updates set $wgUpgradeKey to a random string [0-9a-z]{16}
    $wgUpgradeKey = false;


    ## Namespace configuration
    # including new definition of access rights that have to be assigned to these role arrays:
    # $imtDefaultRoleContributor, $imtDefaultRoleCurator, $imtDefaultRoleDevelope, $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;

    ## 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: $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' );
?>}}
{{Collapse bottom}}

For more information on how to customize your project software, please see [[Project:Software customization|Software customization]]. If you have more than one host on your project (e.g. you cluster your hosts, or have a live, staging and dev system), they all should use the same <code>LocalSettings_project.php</code> file. Individualize your hosts in <code>LocalSettings_host.php</code>

==== LocalSettings_project_extensions.php ====
This one loads and configures all project specifix extensions. In branch master, this file is not included. Use <code>LocalSettings_project_extensions.php.sample</code> to create one if needed. This is not necessary for normal operations, though. Again, noteable exceptions are extensions loaded by [[#Composer|composer]].

==== LocalSettings_host.php ====
Here you configure all host specific settings like db credentials, or secret hash key. If this is a staging host, this is the place to overwrite your <code>$wgServer</code> and maybe your access control. Refrain from including extensions here, since then some [[Project:Software features#Helper scripts|Helper scripts]] will fail.

{{collapse top|title=Template <code>LocalSettings_host.php</code>}}
{{code|lang=php|line=1|code=
<?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;


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

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

    # note, that if you're running semantics, uncomment this and specify your host (w/o protocoll) again
    #enableSemantics( "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 adresses
    # Default for project is found in LocalSettings_project.php; overwrite in project or staging here
    #$wgEmergencyContact = "webmaster@uni-paderborn.de"; // one of your email accounts
    #$wgPasswordSender = "webmaster@uni-paderborn.de";   // 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;
#   $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
?>}}
{{Collapse bottom}}

For more information on how to customize your project software on a per host basis, please see [[Project:Software customization|Software customization]]. Note that this file is gitignore-d by default, so changes here will not show up on <code>git status</code>.

==== LocalSettings_LDAPHub.php ====
Contains all config settings and Extension inclusions for LDAP and KRB authentication to work.

==== LocalSettings_maintenance.php ====
This file is not bundled in your software package and normally not present. Some scripts create this file on demand, you yourself can create if need be. This normally contains temporary settings like maintenance mode or acl overwrites. '''Please refrain from using the closing <code>?&gt;</code>!'''

=== Extensions ===
Your <code>_extensions</code> directory contains all available extensions. Most of them are included as submodules, so they can easily be updated via git. Again, the noteable exception being the [[#Composer|composer]] extensions. Also there are a handful of old or customized extensions that are stored directly in the master branch.

=== Skins ===
In the <code>_skins</code> directory you can find all available skins for your project. Select and configure them in your config files.

=== Auxilliary files ===
In <code>/_opt</code> you can find a bunch of additional files. These are not required for your installation to work, but provide some additional capabilities. See [[Project:Software features]] for more information.

== Logging ==
Some scripts dump informational output to a central log file. This is located in <code>/var/log/<project>.log</code>.

== Composer ==
{{ambox|type=notice|text=Normally, you should not need be concerned about composer. All mediawiki composer components necessary to run your project are included in the repo. Additional composer extensions are probably provided in your project feature branch.}}
Since mediawiki 1.25 some components of the core software are managed by composer. There is a <code>composer.json</code> file located in the software core directory that manages all of that. '''Don't edit this file unless you know exactly what you are doing!'''

Problem is that if you install an extension via the recommended <code>composer require &lt;extension&gt;</code> command, composer automatically edits the composer.json file. On next core update, these changes are lost. The suggested way is [https://www.mediawiki.org/wiki/Composer#Using_composer-merge-plugin documented here]. So please generate a <code>composer.json-local</code> file (you can use the [[#Core_files|composer.json-local.sample]]) and maintain it manually. Your composer command to actually install it is <code>composer update</code>.