Wikibase/Installation

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.

PrerequisitesEdit

MediaWikiEdit

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.


ComposerEdit

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

InstallationEdit

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 beginEdit

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

 
Fresh MediaWiki

Obtain WikibaseEdit

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

Download from GitEdit

  • 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 archiveEdit

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


Install dependenciesEdit

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.phpEdit

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

1. Enable Wikibase Repository onlyEdit

$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 onlyEdit

$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 ClientEdit

$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 scriptsEdit

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 onlyEdit

Run this php script:

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

For Wikibase Client onlyEdit

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 ClientEdit

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 installationEdit

Wikibase RepositoryEdit

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 ClientEdit

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 sitelinksEdit

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 groupsEdit

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 groupsEdit

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 featureEdit

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 groupsEdit

To show the correct heading for your groups, you must create the page MediaWiki:Wikibase-sitelinks-mywikigroup[1] 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 tableEdit

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.

ExampleEdit

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 databasesEdit

$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 sitelinksEdit

  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.

TroubleshootingEdit

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

Make sure you installed Extension:UniversalLanguageSelector

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

One or more of the following may help:

php lib/maintenance/populateSitesTable.php
php repo/maintenance/rebuildItemsPerSite.php


ReferencesEdit