User:Itamar Givon (WMDE)/Multi Wiki Docker

The following page describes how to set up a local multiwiki development environment. This environment will consist of a wikibase repo/client installation as a default site for item entities and an additional wikibase client site to interact with those entities.

A little background

While picking up one of my first tickets (phab:T243969), I wanted to set up a local development environment to help me reproduce this issue. Since I was (am) a beginner in wikimedia, I decided to setup my initial environment using the Addshore's docker instance.

As a complete noob to both docker and mediawiki, I wasn't quite sure how to go about it, and when things went wrong (as they happen to do with every step of the way), I had a hard time trying to decipher how to debug them. Thanks to the help from the great team here at wikibase/wikidata in WMDE, I'm writing this guide as a primer on how to reproduce this setup, with as much of a hassle free process as possible.

The following tutorial assumes that you are working in an Ubuntu (or any other linux distro for that sake) environment, and that you are using bash as your shell.

Step 0: Get you a docker env

Note: This entire tutorial is based on the docker dev environment provided by Addshore If you would like to set up your multi wiki environment in a different way, I recommend visiting Official Installation Guide.

If you haven't done so already, head over to mediawiki-docker-dev on Github and follow the instructions there to prepare your local installation. Once you are done, make sure to also install the wikibase extension according to the instructions for Repo/Client site.

Small Tip #1: Alias

If you don't want to add yourself to the docker group but still want to use the bash alias mentioned here, add the following to your ~/.profile or ~/.bashrc (replace <path-to> with the path to the media-docker-dev repository in your system):

## MediaWiki Docker
if [ -d "$HOME/<path-to>/mediawiki-docker-dev" ]; then
	alias mw-dev='_(){ (cd $HOME/<path-to>/mediawiki-docker-dev; sudo ./$@) ;}; _'	
fi

Important: for the rest of the tutorial, I will be using the alias above when mentioning the commands from mediawiki-docker-dev, feel free to use any method you like to run the scripts used.

Step 1: Add another wiki to the mix

Adding a new site is pretty simple with the provided scripts in mediawiki-docker-dev. To add a new site run the following (replace <site-name> with the name for your wiki:

$ mw-dev addsite <site-name>

Assuming we ran the command above with a name such as testwiki, we will be able to access our new wiki in the browser by going to testwiki.web.mw.localhost:8080. The command above also creates a new database with the exact same name.

Problem #1: Repo vs. Client

Even though we got two wikis with two seperate databases, we still have a small issue: since they are both using the same mediawiki directory, it also means that they are using the same LocalSettings.php file. Normally this wouldn't be an issue. However, we want to create two seperate wikis, with two differening sets of extensions. Namely, we would like to have a "Repo/Client" wikibase in our original wiki, and a "Client Only" wikibase, in our new wiki.

Luckily, this can be mitigated by repurposing a handy variable included by requiring /.docker/LocalSettings.php: $dbName, which contains the name of the wiki being accessed. This will enable us to create and load seperate LocalSettings files such as LocalSettings.default.php or LocalSettings.testwiki.php depending on the requested wiki.

1.1. Prepare git

Since we will be adding several LocalSettings files, we would probably want to ignore them, without shamelessly polluting .gitignore for our own needs. To achieve that (In this and any other project) I like to create a .local directory in the repo and add it to .git/info/exclude.

In your mediawiki directory run the following:

$ mkdir .local
$ echo .local/ >> .git/info/exclude

1.2. Split LocalSettings

Now that we have a place to place our new LocalSettings files, we can add some conditional magic to our main LocalSettings.php.

Paste the following code at the bottom of mediawiki/LocalSettings.php:

// Load correct settings file per site
if(file_exists(__DIR__ . '/.local/LocalSettings.' . $dockerDb . '.php')){
	require_once __DIR__ . '/.local/LocalSettings.' . $dockerDb . '.php';	
}

These lines above will load a LocalSettings files according to the name of the requested site, if that file exists.

1.3. Add per site configuration

Now that we have the code setup, we can add our various LocalSettings files (remember to replace <site-name> with the name of your site):

$ touch .local/LocalSettings.<site-name>.php

Continuing with our example, having our wikibase Client/Repo called default, and our Client Only wikibase called testwiki, we would end up with something like this:

mediawiki/
|- .local/
|  |- LocalSettings.default.php
|  |- LocalSettings.testwiki.php
|
|...
|
|- LocalSettings.php

With this configuration, we can place any shared extensions / skins in the main LocalSettings.php, and we will place wikibase Repo/Client specific configs in LocalSettings.default.php and Client Only specific configs in LocalSettings.testwiki.php. We can validate that the two sites load different extensions by visiting each site's Special:Version page and comparing between them.

Step 2: Introduce your wikis to one another

TODO:

- Describe adding items to the sites table with the maintanace scripts - Describe horrible crashing problem "repo not know or something" - Describe solution the the problem (hiiden configs below)

Important: There are some fairly hidden (as of the time of writing) configurations that must be added in order for the client wiki to be able to communicate with it's repo. Adding these to your client only config, can save some head scratching later (if you're a noob to wikibase like I am [was]):

// Add these after the initial client setup
$wgWBClientSettings['repoUrl'] = 'http://<repo-wiki>.web.mw.localhost:8080';
$wgWBClientSettings['repoScriptPath'] = '/mediawiki';
$wgWBClientSettings['repoArticlePath'] = '/mediawiki/index.php/$1';
$wgWBClientSettings['siteGlobalID'] = '<client-wiki>';
$wgWBClientSettings['repositories']['']['repoDatabase'] = '<repo-wiki>';
$wgWBClientSettings['repositories']['']['changesDatabase'] = '<repo-wiki>';

Step 3: Get your wikis linked

TODO:

- Describe issue with host name resolution: "Page $1 could not be found in $2" - Describe `define('MW_DEV_ENV', 'docker')` as a solution. - Add caveat regarding cache