Customizing Wikibase config in the docker-compose example
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.
Really appreciate the work you have done to ‘dockers’ wikibase. I have it up and running, but have found that the quickstatements service fails (having sorted out the Oauth tokens etc. as per the README), with the browser reporting that it is unable to make a secure connection to the server (tested on Safari & Chrome). As far as I can tell, the server redirects from http://localhost:9191 to https://localhost:9191 (note https) and then fails. I have been onto the running container and followed all the Apache configs, but I can see nothing which should be having this effect.
I just came across a ticket on phabricator relating to your issue with some feedback from magnus on it.
I’ll see if I can take a look at getting this fixed.
And in fact it looks like it might be fixed in the latest version of the images! https://phabricator.wikimedia.org/T206767#4743831
Ah – good news! Many thanks for following up on this 🙂
[…] is documented in this blog post, and some customization regarding LocalSettings and extensions was covered here.The current state of the docker-compose file can be seen below with private details […]
[…] the Wikibase Registry(setup post) is deployed using the shoehorning approach described in one of my earlier posts. After continued discussion on the Wikibase User Group Telegram chat about different setups and […]
I wanted to change the logo, so I changed the variable in LocalSettings.php.template, and that worked. Except I wanted to make another change and I thought changing LocalSettings.php.template again then running “docker-compose stop” and “docker-compose up -d” would work, but it did not. I got the change to work by changing LocalSettings.php. Is the .template just a one-time configuration?
In order for the template changes to be picked up you need to recreate the container.
Try something like:
docker-compose up -d --force-recreate --no-deps wikibase
Hi Adam, thanks for making wikibase and mediawiki more accessible. I’m having trouble mounting the
Where is this localsettings file and how can it be placed into the proper location? I’m new to Docker and running VMs on a Mac with Docker Desktop. Thank you in advance.
It’s all documented in the README for the image https://github.com/wmde/wikibase-docker/blob/master/wikibase/README.md#filesystem-layout
See the descriptions of