Wikibase/Installation

This document covers installing the Wikibase extension for MediaWiki. For manual installation instructions for the Wikibase suite, see Wikibase/Suite. For Docker installation instructions, see Wikibase/Docker.

This page provides step-by-step instructions for installing a basic, minimal version of Wikibase. If you're interested in more advanced configurations, please refer to the advanced configuration guide. More detailed documentation bound to each version of the code can be found in the docs folder of the Wikibase source repository: see doc.wikimedia.org.

Prerequisites

MediaWiki

Since Wikibase is an extension (actually two extensions) to MediaWiki, you'll first need to set up MediaWiki.

Warning:

Wikibase does not maintain compatibility with older versions of MediaWiki! Recent versions of Wikibase will most likely not work with older versions of MediaWiki (and vice versa). Use the most recent versions of MediaWiki and Wikibase (master branches), or make sure you download the appropriate branch of Wikibase that matches your version of MediaWiki.

Composer

The easiest way to install all dependencies of Wikibase is using Composer. Here you can find installation instructions for Composer.

Installation

A basic installation of Wikibase consists of four steps:

1. Obtain Wikibase
2. Install dependencies
3. Modify LocalSettings.php
4. Run maintenance scripts

The following guide will lead you through these steps.

Before you begin

Make sure you've set up MediaWiki and installed Composer.

Fresh MediaWiki

Obtain Wikibase

Download the latest version of Wikibase (or the version matching your Mediawiki installation) into the extensions folder of your MediaWiki installation.

Download from Git

• For the latest unstable version of Wikibase:

cd extensions
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/Wikibase.git
cd Wikibase
git submodule update --init --recursive # get the dependencies using submodules

• Use the version of Wikibase corresponding to your MediaWiki version. To obtain a specific version of Wikibase, specify the name of the branch you want to download. For example, to install Wikibase for Mediawiki version 1.34.x use the Wikibase branch REL1_34:

cd extensions
git clone -b REL1_34 https://github.com/wikimedia/mediawiki-extensions-Wikibase.git Wikibase
cd Wikibase
git submodule update --init --recursive # get the dependencies using submodules

Make sure the folder you just downloaded is called Wikibase and located in extensions/

Download archive

Warning:

If you download Wikibase this way, you won't get all the required submodules!

• Instead of using git, you can download an archive with the latest version of Wikibase or any specific version of Wikibase.
• Make sure to extract the archive into a new folder called Wikibase in the extensions folder of your MediaWiki installation.

Install dependencies

Use the composer-merge-plugin and add the following into composer.local.json at the root of your MediaWiki installation:

{
  "extra": {
    "merge-plugin": {
      "include": [
        "extensions/Wikibase/composer.json"
      ]
    }
  },
  "require": {
    "monolog/monolog": "~2.0.2"
  }
}

From the root of your MediaWiki installation, run only one of the numbered commands:

# before running any of the three commands below
rm composer.lock

# 1. if composer is available as a binary
composer install --no-dev
# 2. if you downloaded composer.phar
php composer.phar install --no-dev
# 3. use the dockerized version (neither PHP or composer need be installed)
docker run -it --rm --user $(id -u):$(id -g) -v ~/.composer:/tmp -v $(pwd):/app docker.io/composer install --no-dev

Modify LocalSettings.php

Add the following lines to your MediaWiki installation's LocalSettings.php. You can enable Wikibase Repository, Wikibase Client or both.

1. Enable Wikibase Repository only

$wgEnableWikibaseRepo = true;
$wgEnableWikibaseClient = false;
require_once "$IP/extensions/Wikibase/repo/Wikibase.php";
require_once "$IP/extensions/Wikibase/repo/ExampleSettings.php";
$wgWBRepoSettings['siteLinkGroups'] = [ 'mywikigroup' ];
$wgLocalDatabases = [ 'enwiki', 'fawiki' ];
$wgWBRepoSettings['localClientDatabases'] = array(
    'en' => 'enwiki',
    'fa' => 'fawiki'
);

Important: If you're using master or 1.36 (and above) you need to use extension registration instead. The above code will fail:

wfLoadExtension( 'WikibaseRepository', "$IP/extensions/Wikibase/extension-repo.json" );
require_once "$IP/extensions/Wikibase/repo/ExampleSettings.php";
$wgWBRepoSettings['siteLinkGroups'] = [ 'mywikigroup' ];
$wgLocalDatabases = [ 'enwiki', 'fawiki' ];
$wgWBRepoSettings['localClientDatabases'] = array(
    'en' => 'enwiki',
    'fa' => 'fawiki'
);

2. Enable Wikibase Client only

$wgEnableWikibaseRepo = false;
$wgEnableWikibaseClient = true;
require_once "$IP/extensions/Wikibase/client/WikibaseClient.php";
require_once "$IP/extensions/Wikibase/client/ExampleSettings.php";
$wgWBClientSettings['repoUrl'] = 'https://pool.my.wiki';
$wgWBClientSettings['repoScriptPath'] = '';
$wgWBClientSettings['repoArticlePath'] = '/wiki/$1';
$wgWBClientSettings['repositories']['']['repoDatabase'] = 'poolwiki';
$wgWBClientSettings['repositories']['']['changesDatabase'] = 'poolwiki';
$wgWBClientSettings['siteLinkGroups'] = [ 'mywikigroup' ];
$wgWBClientSettings['siteGlobalID'] = 'en';

For another lang-wiki client, like Farsi, change the siteGlobalID to:

$wgWBClientSettings['siteGlobalID'] = 'fa';

Important: Similar to above, if you're using 1.36 or master, you need to use this instead:

wfLoadExtension( 'WikibaseClient', "$IP/extensions/Wikibase/extension-client.json" );
require_once "$IP/extensions/Wikibase/client/ExampleSettings.php";
$wgWBClientSettings['repoUrl'] = 'https://pool.my.wiki';
$wgWBClientSettings['repoScriptPath'] = '';
$wgWBClientSettings['repoArticlePath'] = '/wiki/$1';
$wgWBClientSettings['repositories']['']['repoDatabase'] = 'poolwiki';
$wgWBClientSettings['repositories']['']['changesDatabase'] = 'poolwiki';
$wgWBClientSettings['siteLinkGroups'] = [ 'mywikigroup' ];
$wgWBClientSettings['siteGlobalID'] = 'en';

3. Enable Wikibase Repository and Wikibase Client

$wgEnableWikibaseRepo = true;
$wgEnableWikibaseClient = true;
require_once "$IP/extensions/Wikibase/repo/Wikibase.php";
require_once "$IP/extensions/Wikibase/repo/ExampleSettings.php";
require_once "$IP/extensions/Wikibase/client/WikibaseClient.php";
require_once "$IP/extensions/Wikibase/client/ExampleSettings.php";

These configurations assume that your interwiki prefixes are en and fa. Adjust as needed.

Important: Similar to above:

wfLoadExtension( 'WikibaseRepository', "$IP/extensions/Wikibase/extension-repo.json" );
require_once "$IP/extensions/Wikibase/repo/ExampleSettings.php";
wfLoadExtension( 'WikibaseClient', "$IP/extensions/Wikibase/extension-client.json" );
require_once "$IP/extensions/Wikibase/client/ExampleSettings.php";

Run maintenance scripts

Finally, run some maintenance scripts.

• Run the MediaWiki database update script:

php maintenance/update.php

• Run the script that populates the sites table:

php extensions/Wikibase/lib/maintenance/populateSitesTable.php

Note: By default, this populates the sites table with Wikimedia's project list. See Manual:Sites table#Managing the sites table for how to list non-WMF projects.

For Wikibase Repository only

Run this php script:

php extensions/Wikibase/repo/maintenance/rebuildItemsPerSite.php

For Wikibase Client only

If you want to run Wikibase Client, you'll also need to run the script that populates the interwiki table:

php extensions/Wikibase/client/maintenance/populateInterwiki.php

Warning: This will overwrite existing links in your interwiki table with (by default) Wikipedia values. Don't do this if you have existing inter-language link data you need to keep.

For Wikibase Repository and Wikibase Client

In this case you'll need to run both scripts:

php extensions/Wikibase/repo/maintenance/rebuildItemsPerSite.php
php extensions/Wikibase/client/maintenance/populateInterwiki.php

(Again, running populateInterwiki.php will overwrite existing links in your interwiki table with (by default) Wikipedia values.)

Verifying your installation

Wikibase Repository

To verify that Wikibase Repository has been installed successfully, navigate to the Special:NewItem page in your MediaWiki. You should be able to create your first Item. Enter a label and optional description and aliases and click Create. You should be redirected to the item page.

Special:NewItem special page

Your first item

Wikibase Client

If you've enabled Wikibase Client and everything is correct, you should see an "Add links" link in the languagelinks section in the main page sidebar.

First Item page

Enable sitelinks

Sitelinks are special links with a site and a title, linking from individual Items to pages on other wikis. In Wikidata these go to other Wikimedia sites such as Wikipedia, Wikisource and Wikivoyage. Among other things, sitelinks allow referencing an Item's property on the linked page in the client wiki, a feature known as Direct access.

1. Configure your sitelink groups

First, consider how to group the client wikis you want to see in your sitelinks area for the Items in your repo wiki.

Define custom groups

In your repo wiki, replace the content of $wgWBRepoSettings['siteLinkGroups'] in LocalSettings.php with the groups you would like to see there.

For example, consider the following line in LocalSettings.php:

$wgWBRepoSettings['siteLinkGroups'] = [ 'wikipedia', 'mywikigroup', 'anothergroup' ];

This would create three groups in the Item page's sitelinks box:

• the standard defined wikipedia for the global Wikipedia sites
• two custom wiki groups (here named mywikigroup and anothergroup)

The names defined here will relate to the site_group field in the sites table, as specified below.

In your client wiki, add a similar configuration line with your siteLinkGroups:

$wgWBClientSettings['siteLinkGroups'] = [ 'wikipedia', 'mywikigroup', 'anothergroup' ];

Deactivate the sitelinks feature

If you do not want your installation to make use of sitelinks at all, you can deactivate them by setting the configuration to an empty array:

$wgWBRepoSettings['siteLinkGroups'] = [];

$wgWBClientSettings['siteLinkGroups'] = [];

2. Localize your groups

To show the correct heading for your groups, you must create the page MediaWiki:Wikibase-sitelinks-mywikigroup with the desired heading as text.

You can create subpages to set headings for different languages, e.g., create MediaWiki:Wikibase-sitelinks-mywikigroup/de to create a German heading.

3. Add the wikis to the sites table

In order to add sitelinks to Items in your repo wiki, you must add the client wikis to the sites table. Group names must match the group names you added to your configuration. Following the example above, you would have one or more sites with mywikigroup and anothergroup as text in the site_group field.
You must set both the file path and the page path, and each must include the $1 placeholder.

Example

To add your wiki (with an id ending with wiki) to the group mywikigroup, runL

cd maintenance
php addSite.php --pagepath=https://mw.wiki/wiki/\$1  --filepath=https://mw.wiki/w/\$1 --language en --interwiki-id en en mywikigroup
php addSite.php --pagepath=https://fa.mw.wiki/wiki/\$1  --filepath=https://fa.mw.wiki/w/\$1 --language fa --interwiki-id fa fa mywikigroup

Be sure to do this on the repo wiki and all client wikis so that the "Add links" functionality in the other languages section works correctly.

For further details on how to add sites to the table, please see these instructions.

4. Inform the repo wiki of the other client wiki databases

$wgLocalDatabases = [ 'enwiki', 'fawiki' ];
$wgWBRepoSettings['localClientDatabases'] = array(
    'en' => 'enwiki',
    'fa' => 'fawiki'
);

localClientDatabases: An array of locally accessible client databases, for use by the dispatchChanges.php script. This setting specifies which wikis to directly push changes to. It must be specified either as an associative array (mapping global site IDs to logical database names) or as a list of databases (if the database names match the site IDs). The default is an empty array, indicating no local client databases.

5. Verify that you can add sitelinks

1. Go to the Special:SetSiteLink page in your repo wiki and try to link an existing Item (field "ID") to one of the sites configured above (field "Site ID") by specifying an existing page on that wiki (field "Sitelink"). If it fails, it should provide a useful error message.
2. On the page you added above, check that Direct access works by referencing a property of the Item in a parser function.

Troubleshooting

There are very few languages I can set labels for in a new item.

Make sure you installed Extension:UniversalLanguageSelector

There are no sites I can link pages to in an item.

One or more of the following may help:

php lib/maintenance/populateSitesTable.php

php repo/maintenance/rebuildItemsPerSite.php