View source for Manual:Wiki family

<languages/>
<translate><!--T:250--> A '''wiki family''' is a collection of two or more wikis that run on the same server and share a common set of resources from the parent installation, while each wiki remains otherwise independent.</translate>
<translate><!--T:251--> This setup is an alternative to running fully separate installations of MediaWiki.</translate>
<translate><!--T:252--> It may be the preferred choice if the site admin wants to reduce the amount of work involved in managing multiple wikis, or cut down on inode usage.</translate>
<translate><!--T:253--> For this reason, some wiki hosting services opt for the wiki family model.</translate>

<translate><!--T:254--> The best known implementation of a wiki family is the '''wiki farm''', although other approaches are possible.</translate>
<translate><!--T:255--> A [<tvar name=url>https://wikiapiary.com/wiki/Farm:Farms</tvar> list of known wiki farms] is available on <tvar name=1>{{ll|WikiApiary}}</tvar>.</translate>

<translate>
<!--T:1-->
Below are instructions for how to set up MediaWiki to host more than one [[w:wiki|wiki]]. 

== Methods == <!--T:207-->
</translate>

{{anchor|Basic principles|Shared Settings}}
<translate>
=== Wiki farm === <!--T:188-->

<!--T:189-->
The following steps are for running multiple wikis on same version of MediaWiki:
</translate>

# <translate><!--T:190--> Install the first wiki as normal.</translate> <translate><!--T:7--> For details, see <tvar name=1>{{ll|Manual:Installation guide}}</tvar>.</translate>
# <translate><!--T:191--> Enable your web server to share your MediaWiki install with all wikis.</translate> <translate><!--T:249--> For multiple (sub)domains, have your web server accept connections from all the relevant domains.</translate> <translate><!--T:245--> For multiple subdirectories, you could use rewrite rules, aliases, or symlinks.</translate>
# <translate><!--T:219--> Add code to the top of <tvar name="1"><code>LocalSettings.php</code></tvar>, to detect the current wiki.</translate> <translate><!--T:246--> Note that if the argument to <tvar name=1><code>--wiki</code></tvar> contains a hyphen, the argument will be split on the hyphen and the resulting two values assigned to <tvar name=2><code>MW_DB</code></tvar> and <tvar name=3><code>MW_PREFIX</code></tvar>, respectively.</translate> <translate><!--T:208--> For wikis by domain name:</translate><syntaxhighlight lang="php">
// This maps domain names to SQL database names.
$wikis = [
    'example.org' => 'examplewiki',
    'one.example.org' => 'onewiki',
];
if ( defined( 'MW_DB' ) ) {
    // <translate nowrap><!--T:209--> Automatically set from <tvar name=1>--wiki</tvar> option to maintenance scripts</translate>
    $wikiID = MW_DB;
} else {
    // <translate nowrap><!--T:210--> Use <tvar name=1>MW_DB</tvar> environment variable or map the domain name</translate>
    $wikiID = $_SERVER['MW_DB'] ?? $wikis[ $_SERVER['SERVER_NAME'] ?? '' ] ?? null;
    if ( !$wikiID ) {
        die( 'Unknown wiki.' );
    }
}

$wgLocalDatabases = $wgConf->wikis = array_values( $wikis );
$wgDBname = $wikiID;
$wgDBuser = 'mediawiki';
</syntaxhighlight>
# <translate><!--T:220--> Configure settings that must differ for all wikis. For example:</translate><syntaxhighlight lang="php">
$wgCacheDirectory = "/tmp/mediawiki_cache/$wgDBname";
$wgUploadDirectory = "$IP/images/$wgDBname";
$wgUploadPath = "/w/images/$wgDBname";
</syntaxhighlight>
# <translate><!--T:221--> Configure per-wiki overrides.</translate> <translate><!--T:247--> This should include at least <tvar name=1>{{phpi|$wgServer}}</tvar> and <tvar name=2>{{phpi|$wgArticlePath}}</tvar>.</translate><syntaxhighlight lang="php">
$wgConf->settings = [
    'wgServer' => [
        'examplewiki' => 'https://example.org',
        'onewiki' => 'https://one.example.org',
    ],
    'wgArticlePath' => [
        'default' => '/wiki',
    ],
    'wgSitename' => [
        'default' => 'Example',
        'onewiki' => 'One',
    ],
    'wgLogo' => [
        'default' => '/images/examplewiki/Example_logo.png',
    ],
    'wgLanguageCode' => [
        'default' => 'en',
        'onewiki' => 'pt',
    ],
];
extract( $wgConf->getAll( $wgDBname ) );
</syntaxhighlight><translate><!--T:196--> This could be done from a separate file, e.g.:</translate><syntaxhighlight lang="php">
# LocalSettings.php
$wgConf->settings = require __DIR__ . '/LocalSettings_overrides.php';

# LocalSettings_overrides.php
<?php
return [
    'wgServer' => ..,
    ..,
];
</syntaxhighlight>

<translate><!--T:256--> To add a new wiki to the family:</translate>

* <translate><!--T:257--> {{<tvar name="1">ll|Manual:Installing MediaWiki</tvar>|Create its database and add its settings first}}, with <tvar name="2"><code>--wiki=mywiki</code></tvar> if you run <tvar name="3"><code>install.php</code></tvar> from the command line.</translate>
* <translate><!--T:258--> Run <tvar name=1><code>php maintenance/run.php update --wiki=mywiki</code></tvar></translate>

{{anchor|Giant switch statement|Separate settings files}}
<translate>

=== Separate settings files === <!--T:233-->

<!--T:4-->
This approach is for operating entirely independent wikis, but still sharing the same web server and MediaWiki source code.

<!--T:223-->
# Install the first wiki as normal, via the web or CLI installer, which sets up your database and generates a <tvar name=1>{{ll|Manual:LocalSettings.php|LocalSettings.php}}</tvar> file.</translate>
<translate>
<!--T:224-->
# After installation, rename the generated <tvar name=1><code>LocalSettings.php</code></tvar> file to include the wiki ID (e.g. database name), like <tvar name=2><code>LocalSettings_mywiki.php</code></tvar>.</translate>
<translate>
<!--T:9-->
# Repeat step one and two above for each wiki you wish to create.</translate>
<translate>
<!--T:225-->
# Create a new <tvar name=1><code>LocalSettings.php</code></tvar> file that will load the correct one.</translate> <translate><!--T:248--> As with the above wiki farm example, a <tvar name=1><code>--wiki</code></tvar> argument containing a hyphen will be split on the hyphen into two values assigned to <tvar name=2><code>MW_DB</code></tvar> and <tvar name=3><code>MW_PREFIX</code></tvar>, respectively.</translate> <syntaxhighlight lang="php">
<?php
$wikis = [
    'example.org' => 'examplewiki',
    'one.example.org' => 'onewiki',
];
if ( defined( 'MW_DB' ) ) {
    // <translate nowrap><!--T:211--> Automatically set from <tvar name=1>--wiki</tvar> option to maintenance scripts</translate>
    $wikiID = MW_DB;
} else {
    // <translate nowrap><!--T:212--> Use <tvar name=1>MW_DB</tvar> environment variable or map the domain name</translate>
    $wikiID = $_SERVER['MW_DB'] ?? $wikis[ $_SERVER['SERVER_NAME'] ?? '' ] ?? null;
}

if ( $wikiID ) {
    require_once "LocalSettings_$wikiID.php";
} else {
    die( 'Unknown wiki.' );
}

// <translate nowrap><!--T:213--> Add any settings that should apply to all wikis below this line</translate>
// -------
</syntaxhighlight> <translate><!--T:15--> If your wikis are on the same domain but under different paths (e.g. <tvar name=1><code>example.org/wiki1</code></tvar>, <tvar name=2><code>example.org/wiki2</code></tvar> etc.), you can use something like this:</translate><syntaxhighlight lang="php">
<?php
$wikis = [
    'example' => 'examplewiki',
    'w_example' => 'examplewiki',
    'one' => 'onewiki',
    'w_one' => 'onewiki',
];
if ( defined( 'MW_DB' ) ) {
    // <translate nowrap><!--T:214--> Automatically set from <tvar name=1>--wiki</tvar> option to maintenance scripts.</translate>
    $wikiID = MW_DB;
} else {
    $wikiID = $_SERVER['MW_DB'] ?? $wikis[ explode( '/', $_SERVER['REQUEST_URI'], 3 )[1] ] ?? null;
}

if ( $wikiID ) {
    require_once "LocalSettings_$wikiID.php";
} else {
    die( 'Unknown wiki.' );
}
</syntaxhighlight>

{{Note|1=<translate><!--T:226--> If you use [[<tvar name=1>Special:MyLanguage/Manual:Short URL</tvar>|Short URL]], you need to add both your <tvar name=2>{{phpi|$wgArticlePath}}</tvar> and the <tvar name=3>{{phpi|$wgScriptPath}}</tvar>.</translate>}}

<translate>
===[[w:Drupal|Drupal]]-style sites=== <!--T:24-->

<!--T:26-->
This setup has the advantage of being completely transparent to users and reasonably secure in terms of the images directory.
</translate>

# <translate><!--T:27--> Create a base directory to contain all your MediaWiki files ''e.g.'' <tvar name=1><code>mkdir /home/web/mediawiki</code></tvar>.</translate>
# <translate><!--T:28--> Install MediaWiki and additional tools as usual to a version-declaring subdirectory (''e.g.'', <tvar name=1><code>/home/web/mediawiki/mediawiki-1.10.0</code></tvar>).</translate>
# <translate><!--T:29--> Link the version-declaring directory to a code directory.</translate> <translate><!--T:30--> ''e.g.'', <tvar name=1><code>ln -s /home/web/mediawiki/mediawiki-1.10.0 /home/web/mediawiki/code</code></tvar></translate>
# <translate><!--T:31--> Create a <tvar name=1>''sites''</tvar> directory to contain our images and settings: <tvar name=2><code>mkdir /home/web/mediawiki/sites</code></tvar></translate>
# <translate><!--T:32--> Setup the wiki as normal from the ''/code'' directory.</translate>
# <translate><!--T:33--> After successful installation, '''move''' <tvar name=1><code>LocalSettings.php</code></tvar> into a sites directory that will be a match when the site is checked.</translate> <translate><!--T:34--> For example, to capture <tvar name=1><nowiki>http://example.com/mywiki</nowiki></tvar>, one would create the directory <tvar name=2>'''example.com.mywiki'''</tvar>.</translate> <translate><!--T:35--> ''e.g.'', <tvar name=1><code>mkdir /home/web/mediawiki/sites/example.com.mywiki</code></tvar>.</translate> <translate><!--T:36--> See the Drupal's <tvar name=1><code>settings.php</code></tvar> file for more information on this.</translate>
# <translate><!--T:37--> If you intend to use media files, create an <tvar name=1>''images''</tvar> directory in your site directory.</translate> <translate><!--T:38--> ''e.g.'', <tvar name=1><code>mkdir /home/web/mediawiki/sites/example.com.wiki/images</code></tvar>. </translate> <translate><!--T:39--> Make it writable as necessary.</translate>
# <translate><!--T:40--> Place the [[<tvar name=1>Special:MyLanguage/Manual:Wiki family/Drupal-style LocalSettings.php</tvar>|Drupal-style <tvar name=2><code>LocalSettings.php</code></tvar>]] file in your main directory:</translate> <code>cp DrupalLocalSettings.php /home/web/mediawiki/code/LocalSettings.php</code>
# <translate><!--T:41--> Modify the <tvar name=1><code>LocalSettings.php</code></tvar> of each subsite to point to the right places:</translate>
## <translate><!--T:42--> First comment out the code relating to <tvar name=1>{{phpi|$IP}}</tvar>, (lines 16-20 in 1.15.3) as this is set to the <tvar name=2>''code''</tvar> directory by <tvar name=3><code>index.php</code></tvar>.</translate>
## <translate><!--T:43--> Next insert the following two lines to ensure that image files are accessible, ''e.g.'': <tvar name=1>{{phpi|$wgUploadDirectory {{=}} "/home/web/mediawiki/sites/wiki.example.com/images";}}</tvar> and <tvar name=2>{{phpi|$wgUploadPath {{=}} "/images";}}</tvar>.</translate> <translate><!--T:44--> These need to be put somewhere after the call to <tvar name=1><code>DefaultSettings.php</code></tvar> (line 25 in 1.15.3), as the variables will otherwise be reset.</translate>
## <translate><!--T:45--> Make further modifications as required.</translate>
# <translate><!--T:46--> Prepare your Apache 2 installation. Example site:</translate> wiki.example.com
## <translate><!--T:47--> Create a link to the <tvar name=1>''code''</tvar> directory, if required ''e.g.'' <tvar name=2><code>ln -s /home/web/mediawiki/code /home/web/wiki.example.com</code></tvar></translate>
## <translate><!--T:48--> Create an appropriate virtual host configuration:</translate> <syntaxhighlight lang="apache">
<VirtualHost *:80>
    ServerAdmin me@example.com
    DocumentRoot /home/web/wiki.example.com
    ServerName wiki.example.com
    CustomLog /var/log/apache2/wiki.mysite.log common
    # <translate nowrap><!--T:215--> Alias for the site to be accessible</translate>
      Alias /mediawiki/code /home/web/mediawiki/code
    # <translate nowrap><!--T:216--> Alias for wiki so images work</translate>
      Alias /images /home/web/mediawiki/sites/wiki.example.com/images
    # <translate nowrap><!--T:217--> If you want to password protect your site</translate>
    #  <Directory /home/web/wiki.example.com>
    #    AuthType Basic
    #    AuthName "<translate nowrap><!--T:218--> My protected wiki</translate>"
    #    AuthUserFile /etc/apache2/htpasswd/users-mywiki
    #   require valid-user
    #  </Directory>
</VirtualHost>
</syntaxhighlight>
:11. <translate><!--T:49--> If you are setting the sites up locally, update your <tvar name=1><code>hosts</code></tvar> file with the site names.</translate> <translate><!--T:50--> The site should now work.</translate>
<translate><!--T:51--> In my case, I made another copy of the code from which to install and update my <tvar name=1><code>LocalSettings.php</code></tvar> and databases.</translate>
<translate><!--T:52--> Note that <tvar name=1>{{phpi|$_SERVER['HTTP_HOST']}}</tvar> in the companion Drupal code is undefined when running maintenance scripts from the command line, so this solution does not permit the use of maintenance scripts without some modification.</translate>

<translate>
=== Modified Drupal-style method for Ubuntu === <!--T:53-->

<!--T:54-->
A simplified method for multiple wikis and multiple (or nested) subwikis on Ubuntu/Kubuntu that is loosely based on the above method can be found at:
</translate>

*[https://web.archive.org/web/20170712122500/http://ubuntuguide.org/wiki/MediaWiki_tips <translate><!--T:55--> Ubuntuguide.org MediaWiki tips</translate>]

<translate>
==How wiki farms are handled in maintenance scripts== <!--T:242-->
</translate>
<translate><!--T:238--> MediaWiki maintenance scripts (''e.g.'' <tvar name=1>[[Special:MyLanguage/update.php|update.php]]</tvar>) accept a <tvar name=2><code>--wiki</code></tvar> argument that is passed to your <tvar name=3>{{ll|Manual:LocalSettings.php|LocalSettings.php}}</tvar> file as the constants <tvar name=4><code>MW_DB</code></tvar>, <tvar name=5><code>MW_PREFIX</code></tvar>, and <tvar name=6><code>MW_WIKI_NAME</code></tvar>.</translate>
<translate><!--T:239--> The entire value of the <tvar name=1><code>--wiki</code></tvar> argument is the value of <tvar name=2><code>MW_WIKI_NAME</code></tvar>.</translate>

{{note|1=<translate><!--T:240--> If there is a dash in the <tvar name=1><code>--wiki</code></tvar> argument, then the part before the dash is assigned to <tvar name=2><code>MW_DB</code></tvar> and the part after the dash is assigned to <tvar name=3><code>MW_PREFIX</code></tvar>.</translate>}}

<translate>
<!--T:234-->
This table demonstrates how this works:
</translate>

{| class="wikitable"
|+ <translate><!--T:241--> How the <tvar name=1><code>--wiki</code></tvar> argument is parsed.</translate>
! <code>--wiki</code> !! <code>MW_WIKI_NAME</code> !! <code>MW_DB</code> !! <code>MW_PREFIX</code>
|-
| enwiki || enwiki || enwiki || ''empty''
|-
| enwiki-one || enwiki-one || enwiki || one
|-
| enwiki-one-two || enwiki-one-two || enwiki || one-two
|}

<translate><!--T:243--> Since there is no <tvar name=1><code>--wiki</code></tvar> argument for web requests, they must be handled differently.</translate>
<translate><!--T:236--> Typically, the domain name and/or URL path is used to select a wiki.</translate>

<translate>
==Tips for sharing between wikis== <!--T:56-->

<!--T:57-->
You can use <tvar name=1>{{wg|ForeignFileRepos}}</tvar> to share uploaded media files across wikis. This is similar to Wikimedia Commons for Wikipedia.

<!--T:58-->
For example:
</translate>

*en.example.org - {{#language:en|{{PAGELANGUAGE}}}}
*fr.example.org - {{#language:fr|{{PAGELANGUAGE}}}}
*de.example.org - {{#language:de|{{PAGELANGUAGE}}}}
*pool.example.org - <translate><!--T:59--> Shared media files for all wikis.</translate>

{{Note|1=<translate><!--T:227--> The above example uses the name "<tvar name=2>pool</tvar>". Avoid using the name "<tvar name=3>commons</tvar>" because this may conflict with the [[<tvar name=1>Special:MyLanguage/Help:Interwiki linking</tvar>|interwiki link]] also named <tvar name=4><code>commons</code></tvar> for [[<tvar name=5>commons:Special:MyLanguage/Main Page</tvar>|Wikimedia Commons]].</translate>

<translate>
<!--T:228-->
Also avoid using the name "<tvar name=1>media</tvar>" (e.g. <tvar name=2>media.example.org</tvar>) as that may cause a conflict between your interwiki and the internal namespace <tvar name=3><code>Media:</code></tvar> for accessing local media files, e.g. <tvar name=4><nowiki>[[media:File.png]]</nowiki></tvar>.
</translate>
}}

<translate>
===Shared database tables=== <!--T:123-->
</translate>
<translate><!--T:237--> Consider using a shared database for user accounts.</translate>
<translate><!--T:124--> See <tvar name=1>{{ll|Manual:Shared database}}</tvar> for instructions on setting up shared database tables.</translate>

<translate>
=== Interwiki === <!--T:182-->
</translate>
<translate><!--T:75--> You can create [[<tvar name=1>Special:MyLanguage/Help:Interwiki linking</tvar>|interwiki links]] between all wikis, by using <tvar name=2>{{ll|Extension:Interwiki}}</tvar>.</translate>
<translate><!--T:229--> If the wikis are language editions, it is recommended to name the interwiki prefix after the exact language code. For example, "de" for the German wiki in your family.</translate>
<translate><!--T:230--> This way, you can connect pages about the same subject using language links.</translate>

<translate><!--T:80--> Adding <nowiki>[[de:Hauptseite]]</nowiki> on your English "Main Page" will create a link "Deutsch" in the languages sidebar.</translate>
<translate><!--T:81--> For further information visit <tvar name=1>{{ll|Help:Interwiki linking}}</tvar></translate>

<translate><!--T:231--> If you have a central wiki for files, create a prefix for this as well.</translate>
<translate><!--T:232--> E.g. <tvar name=1><code>pool</code></tvar> to <tvar name=2><nowiki>https://pool.example.org/wiki/$1</nowiki></tvar> and enable the "Forward" checkbox to recognise it as a local wiki in the same family.</translate>

<translate>
===Upload=== <!--T:86-->

<!--T:87-->
Make sure that folder "<tvar name=1>images</tvar>" of the pool-wiki is writable.
</translate>

<translate><!--T:88--> It is useful to change the "Upload file"-Link of the language-wikis to point to poolwiki's upload-site.</translate>
<translate><!--T:89--> Open the "<tvar name=1>LocalSettings.php</tvar>" of each language-wiki and add:</translate>

<syntaxhighlight lang="php">
$wgUploadNavigationUrl = "https://pool.example.org/index.php/Special:Upload";
</syntaxhighlight>

<translate>
<!--T:90-->
In 1.17, you'll also have to set <tvar name=1>{{phpi|$wgUploadMissingFileUrl}}</tvar> to be redirected to the pool-wiki on red links.
</translate>

<syntaxhighlight lang="php">$wgUploadMissingFileUrl= "https://pool.example.org/index.php/Special:Upload";</syntaxhighlight>

{{anchor|Use shared files}}
<translate>
<!--T:205-->
If you want to allow uploads only for your pool wiki, you may use something like this:</translate>
<syntaxhighlight lang="php">
if ( $wgDBname === 'pool' ) {
	$wgEnableUploads = true;
} else {
	$wgEnableUploads = false;
}
</syntaxhighlight>

<translate>
===Use shared files=== <!--T:91-->

<!--T:92-->
To use poolwiki's files in the languagewikis, open "<tvar name=1>LocalSettings.php</tvar>" for each languagewiki and add:
</translate>

<syntaxhighlight lang="php">
$wgUseSharedUploads = true;
$wgSharedUploadPath = 'https://pool.example.org/images';
$wgSharedUploadDirectory = '/(LOCALPATH)/POOL-FOLDER/images/';
$wgHashedSharedUploadDirectory = true;
</syntaxhighlight>

<translate>
<!--T:93-->
Now you can integrate pool's files with (e.g. <tvar name=1><nowiki>[[File:MyLogo.png]]</nowiki></tvar>) in the languagewikis.

===Image description=== <!--T:94-->

<!--T:95-->
In each languagewiki, open (as an admin) the message <tvar name=1>[[MediaWiki:Sharedupload-desc-here]]</tvar>.</translate>

<translate>
<!--T:96-->
Change the text to something like:
</translate>
<!-- ( old line ) [[pool:File:{{PAGENAME}}|description there]]. -->

<pre>
<translate nowrap><!--T:97--> This file is stored in our data-pool.</translate>
<translate nowrap><!--T:98--> For information and description, please visit the [[<tvar name=1>:pool:File:{{PAGENAME}}</tvar>|description there]].</translate>
</pre>

<translate>
<!--T:100-->
(And note the '<tvar name=1>:</tvar>' at the beginning of the line, which stops '<tvar name=2>pool</tvar>' from being included in the interwiki list at the left of the page.)

<!--T:101-->
If you want to output the media-description, stored in the PoolWiki, too, add to the "<tvar name=1>LocalSettings.php</tvar>" of the languagewikis:
</translate>

<syntaxhighlight lang="php">
$wgFetchCommonsDescriptions = true;
$wgSharedUploadDBname = 'pool';  # DB-Name of PoolWiki
$wgSharedUploadDBprefix = 'wiki_'; # Table name prefix for PoolWiki
$wgRepositoryBaseUrl = "https://pool.example.org/index.php/Image:";
</syntaxhighlight>

<translate>
== Wiki Farm extensions == <!--T:168-->

<!--T:169-->
There are several MediaWiki extensions that attempt to simplify hosting of several wikis by using just one code base, however only one is currently noteworthy:
</translate>

* {{ll|Extension:MediaWikiFarm}} - beta.

* {{ll|Extension:SkinCustomiser}}: <translate><!--T:206--> For [[w:internationalization and localization|localisation]] issues of the <tvar name=1>{{ll|sidebar}}</tvar> and customising the [[<tvar name=2>Special:MyLanguage/Manual:Skins</tvar>|Skins]] regarding the files <tvar name=3><code>[[MediaWiki:Cologneblue.css]]</code>, <code>[[MediaWiki:Modern.css]]</code>, <code>[[MediaWiki:Monobook.css]]</code>, <code>[[MediaWiki:Vector.css]]</code>, <code>[[MediaWiki:Mobile.css]]</code>, <code>[[MediaWiki:Common.css]]</code></tvar> respectively.</translate>

<translate>
== See also == <!--T:173-->
</translate>
* {{ll|Extension:CentralAuth}}
* {{ll|Manual:InitialiseSettings.php}}
* {{ll|Manual:CommonSettings.php}}
* {{ll|Manual:$wgConf}}
* {{ll|Manual:Central ID}} — <translate><!--T:203--> the mechanism by which user accounts can have an extra 'central' identifier.</translate>

[[Category:MediaWiki configuration{{#translation:}}|Wiki family]]
[[Category:Installation{{#translation:}}|W]]
[[Category:Wiki farm{{#translation:}}| ]]