Configuration files

From Wikitech
This page may be outdated or contain incorrect details. Please update it if you can.

Especially #Localization cache which is outdated per Nikerabbit


Our configuration lives in /srv/mediawiki-staging/wmf-config on the deployment host, and tools such as scap sync this directory to /srv/mediawiki on cluster hosts. (The same common directory also has subdirectories for each live branch of the MediaWiki codebase.) Many configuration files are in the subdirectory wmf-config. Most files are maintained in the git repository operations/mediawiki-config . A selection of public configuration files is also available online at


InitialiseSettings.php contains a huge array of settings. The format, roughly, is

'wgDefaultSkin' => [ // Variable name, without the $
	'default' => 'vector', // Default value
	'nostalgiawiki' => 'nostalgia', // Value for a specific wiki
	'wikibooks' => 'monobook', // Value for all wikis listed in wikibooks.dblist
	// etc.

Some random useful facts:

  • The wiki names used in the keys are database names and are listed in all.dblist
  • There is a dblist for every wiki family (wikipedia, wikibooks, ...) as well as 'private' for private wikis and a few others. See *.dblist to see what's available
  • When multiple values apply to one wiki, the most specific one wins (i.e. wiki name beats dblist beats 'default'). When the values are arrays, prefix the wiki name with a + (e.g. '+wikibooks' instead of 'wikibooks') to merge the arrays instead.
    • InitialiseSettings-labs.php (beta cluster) setting arrays are merged into production setting arrays (i.e. beta settings will override the production settings for the wikis/groups present in the beta config file; production settings will be inherited for wikis/groups not present in the beta config; this might result in production settings overriding beta settings when they are more specific, e.g. beta has a setting for wikipedia and production has a setting for enwiki). Prefix the variable name with - to ignore production settings entirely.

wgVariables vs. wmgVariables

Variables starting with wg directly correspond to core, skin or extension configuration variables; since T87875, this applies to all deployed extensions and skins. Most settings are therefore set directly with wg variables in InitialiseSettings.php.

Variables starting with wmg trigger certain block of code in CommonSettings.php, such as enabling extensions with $wmgUseExtensionName. Most extensions should be disabled for the 'lockeddown' dblist even if they are otherwise loaded everywhere, like so:

'wmgUsePhonos' => [
	'default' => true, // T336763
	'lockeddown' => false,

wmg variables may also be used for other kinds of configuration that need more “supporting code” in CommonSettings.php, for example:

if ( $wmgUseJsonConfig ) {
	wfLoadExtension( 'JsonConfig' );

	if ( $wmgUseGraphWithJsonNamespace ) {
		$wgJsonConfigModels['Json.JsonConfig'] = null;
		$wgJsonConfigs['Json.JsonConfig'] = [
			'namespace' => 486,
			'nsName' => 'Data',
			'isLocal' => true,
			'pattern' => '/^Json:./',

Furthermore, prior to the extension registration migration, variables starting with wmg were also often used for regular extension configuration variables; you might still see some assignments like this:

// do not do this anymore
$wgMinimumVideoPlayerSize = $wmgMinimumVideoPlayerSize;

This is generally just legacy code that hasn’t been cleaned up yet; you shouldn’t follow this pattern for any new variables.


This file includes "configuration code", i.e. configuration that can't be done with simple variable assignments. This includes extensions, dynamic things and a whole lot of other random things that have been piling up here in the past years.

When adding a new extension, you should put its setup code (wfLoadExtension() plus any other settings) here in an if ( $wmgEnableMyExtension ) block (assuming it's not going to just be enabled everywhere).

Localization cache

was: "extension-list and ExtensionMessages-XXX.php"

All of our wikis share the same localization cache, but in normal setups this causes problems when the cache is shared between wikis with different sets of enabled extensions. We work around this by listing all extensions enabled on any wiki explicitly.

wmf-config/extension-list lists the paths to the extension setup file (NOT the i18n file!) of every extension enabled on any wiki (except wikitech). The paths start with $IP/extensions and $IP/skins and each path is on a line by itself:


ExtensionMessages-1.NNwmfMM.php is a PHP file that contains the actual workaround[citation needed]. mw-update-l10n rebuilds it from wmf-config/extension-list. You can run it yourself to check for errors. You must use wiki that is deployed to the correct version.

$ cd /srv/mediawiki-staging/wmf-config
$ mwscript mergeMessageFileList.php --wiki=testwiki --list-file=extension-list --output=/tmp/junkExtensionMessages.php

After running this, check the output for error messages, and diff it with the current ExtensionMessages.php to verify the changes are sane.


dblists are used to conveniently group wikis with shared configuration together. They are applied through the config YAML files, and generated automatically.

To add or remove a wiki from a dblist, edit the YAML file (e.g. wmf-config/config/enwiki.yaml) to add or remove a line with the name of the dblist from the inheritsFrom configuration. Then run composer buildDBLists to generate the updated dblists. (If you don't have composer installed locally, do that first.)

You should not create a new dblist without checking with RelEng first, as each list has a significant performance impact.

To deploy a change to dblists, run sync-file dblists/ to sync the change.

Other files

  • abusefilter.php: configuration for the AbuseFilter extension
  • db-*.php: Defines which wikis are in which section, which database servers are in which section, etc., etc., useful as a reference for DB-related facts like those. Don't mess with this file unless you know what you're doing
  • flaggedrevs.php: configuration for the FlaggedRevs extension
  • liquidthreads.php: configuration for the LiquidThreads extension
  • mc.php: configuration for memcached, mostly a list of available memcached servers
  • missing.php: generates the "This wiki doesn't exist" page. Not really a configuration file
  • wgConf.php: setup code for the configuration system

How configuration files are loaded

The web entrypoints index.php, load.php, and so on are shimmed on production hosts, by the files in w/. Most of these files simply load the MWMultiVersion class, do a bit of setup to map the domain name to the correct MediaWiki version (using wikiversions.json) and database name, then delegate to the usual entrypoint.

MediaWiki-core loads its own include/DefaultSettings.php, which are the defaults included in publicly committed code.

On production servers, the LocalSettings.php file is a single line, which loads wmf-config/CommonSettings.php from the parent directory /srv/mediawiki.

CommonSettings.php then picks up configuration from various places in the filesystem (documented in the script) including InitialiseSettings.php, and finally any settings in the body of itself.

On the beta cluster, InitialiseSettings-labs.php is loaded after production InitialiseSettings.php, and CommonSettings-labs.php after its production file, so naturally labs settings override the production ones.