2019 Edit: If you want to use a Dockerfile and custom image take a look a here.

Just over a month ago I setup the Wikibase registry project on Wikimedia Cloud VPS using the docker-compose example provided by Wikibase docker images. The Wikibase registry is the first Wikibase install that I control that uses the Wikibase docker images, so I’ll be using it as an example showing how the docker images can be manipulated to configure MediaWiki, Wikibase, and load custom extensions and skins.

The example docker-compose file at the time of writing this post can be found at https://github.com/wmde/wikibase-docker/blob/5919016eac16c5f0aefc448240fdf6a09bb56bec/docker-compose.yml

Since the last blog post new wikibase image tags have been created (the ‘bundle’ tags) that include some extensions you might want to enable, as well a quickstatements image for the quickstatements service used on Wikidata written by Magnus Manske.

Reloading currently running services

Before we learn how to change configuration and alter the default containers we need to know how to reload them to pull in the changes.

To reload a single service from the docker compose example you can use the following command example from the directory of your docker-compose file, which will create a new container for the wikibase service:

docker-compose up --no-deps -d wikibase

• –no-deps, do not also stop and recreate services which are listed as depending on this one in the docker-compose file.
• -d, load in detached mode.
• wikibase, the service to be reloaded.

Using volume mounts

Changing basic configuration

Everyone using the wikibase docker images will likely want to change some configuration, be it a logo, website description or a change of language.

For a few configuration settings the ENV vars provided as part of the image can be used, although these generally only cover connecting services together such as DB_SERVER, DB_USER, DB_PASS and DB_NAME. Other ENV vars exist and are documented by the image README file.

For everything else you’ll want to change LocalSettings.php directly. Docker and docker-compose allow you to override files in an image while running a container using volumes.

Example volume mount

The docker-compose example file already contains examples of volume use by mounting persistent volumes into the running containers. For the wikibase image this can be seen in the docker-compose file with the below snippet which mounts a persistent docker volume called ‘mediawiki-images-data’ to /var/www/html/images within the container.

    volumes:
      - mediawiki-images-data:/var/www/html/images

If we wanted to have the images directory be mounted from our host disk rather than using a docker volume we could instead change this to the snippet below:

    volumes:
      - ./images:/var/www/html/images

Note: If you already had images saved in the ‘mediawiki-images-data’ volume this would not copy them to the local images directory. The directory would start as an empty directory and you would have to copy the files from the docker volume. You will also have to make sure that the correct permissions have been set to allow the user running in the wikibase container to write to the local directory.

Volume mount LocalSettings

The wikibase docker image README file (which in its current version can be found here) provides various files and directories of interest that a user might want to override. These include 2 locations for LocalSettings that may be of interest:

• /LocalSettings.php.template – Template for Mediawiki Localsettings.php (substituted to /var/www/html/LocalSettings.php at runtime)
• /var/www/html/LocalSettings.php – LocalSettings.php location, when passed in /LocalSettings.php.template will not be used. install.php & update.php will also not be run.

The LocalSettings template continues to get passed through the envsubst command in the container entrypoint in a command similar to the below (with DOLLAR being substituted to a real $):

export DOLLAR='$'
envsubst < /LocalSettings.php.template > /var/www/html/LocalSettings.php

Using the same volume mounting technique described in the section above we can mount local files over these image provided files:

    volumes:
      - ./images:/var/www/html/images
      - ./LocalSettings.php.template:/LocalSettings.php.template

The default LocalSettings.php.template can then be provided on your host and modified, for example a logo is added in the configuration below, which can be seen on this github gist:

Using this method all you need to know if the correct MediaWiki or Wikibase configuration option that you wish to change and follow the regular documentation.

Shoehorning in extensions & skins

The volume mounting method can be used to rather ungracefully shoe horn extensions into the image container.

Extensions can be cloned onto disk:

user@wbregistry-01:/srv/wbrdc# git clone https://github.com/wikimedia/mediawiki-extensions-Nuke.git extensions/Nuke
user@wbregistry-01:/srv/wbrdc# git clone https://github.com/wikimedia/mediawiki-extensions-ConfirmEdit.git extensions/ConfirmEdit

Directories can mounted to locations in the containers in the docker-compose file:

    volumes:
      - mediawiki-images-data:/var/www/html/images
      - ./LocalSettings.php:/var/www/html/LocalSettings.php:ro
      - ./Nuke:/var/www/html/extensions/Nuke
      - ./ConfirmEdit:/var/www/html/extensions/ConfirmEdit

And configuration added to our LocalSettings (here using the LocalSettings file directly rather than the template):

wfLoadExtension( 'Nuke' );

wfLoadExtensions([ 'ConfirmEdit', 'ConfirmEdit/QuestyCaptcha' ]);
$wgCaptchaQuestions = [
        'Question 1' => 'Response 1',
        'Question 2' => 'Repsonse 2',
];
$wgCaptchaTriggers['create'] = true;

With a quick service reload both extensions should be visible on the MediaWiki Special:Version page.

Custom Dockerfile & image

For a more permanent solution you probably want to create your own Dockerfile and docker images.

Documentation for this process can be found here.