Maintaining a Wikibase instance

Here are some resources to give you some insight into your Wikibase instance and to help keep it healthy and up to date.

(next: Extending)

Architecture overview

First it's important to understand what you've got on your hands. Take a look at our Docker architecture overview.

And here's an architecture table with a diagram (click to enlarge):

Service name Access Notes
wikibase localhost:8181 MediaWiki with the Wikibase extension
mysql docker port 3006 the MySQL (MariaDB) database
elasticsearch docker ports 9200, 9300 ElasticSearch
quickstatements localhost:9191 QuickStatements
wdqs docker port 9999 Wikidata query service
wdqs-proxy localhost port 8989 Query service proxy
wdqs-frontend localhost:8282 Query service frontend

Docker tooling

The best tool for managing your Docker install is the one you used to get it going in the first place: docker-compose. This manual can't possibly replace a grounding in Docker, so check out Docker's own command references for docker-compose and the docker engine.

That said, here are some starter commands that might come in handy.

Note: Container names created using docker-compose begin with the basename of the directory in which they were created with the first docker-compose up invocation, separated by an underscore. The example container names below begin with wbdocker_ because, for example purposes, we created them with the docker-compose.yml file sitting in a directory named wbdocker.

Get a command shell on a container

You won't need it for typical Wikibase activity, but for Docker beginners here's one very useful command that connects to a running container:

docker exec -it <container name> bash

Copy a file to your local directory

docker cp wbdocker_wikibase_1:/var/www/html/LocalSettings.php LocalSettings.php

This also works in the other direction, and the combination is useful for, say, grabbing your LocalSettings.php, editing it and putting it right back.

docker cp LocalSettings.php wbdocker_wikibase_1:/var/www/html/LocalSettings.php 

Read Adam Shorland's excellent blog post for more detail on modifying files on containers.

Stop the Docker containers

This command stops the Docker containers, leaving the machines (and of course all data) intact:

docker-compose stop

As you might imagine, you can use docker-compose start to start them again.

Delete the containers while preserving data

This command removes the containers but preserves all data in MySQL, MediaWiki and the query service in Docker volumes.

docker-compose down

Delete everything

WARNING: this will remove ALL of the data you ever added to your Docker install, which includes MediaWiki, Wikibase, ElasticSearch and the MySQL database. There's no coming back from this!

docker-compose down --volumes

Logs

Each application in the Wikibase cluster has its own log output. Consult each service's own documentation to learn how to read its logs.

In the directory where you placed your docker-compose.yml file, run the docker-compose logs command and the name of the service (check the table above) to see its logs. For example:

user@host:~/docker$ docker-compose logs mysql --tail 100
mysql_1 | 2019-12-31 10:00:00+00:00 [Note] [Entrypoint]: Entrypoint script for MySQL Server started.
mysql_1 | 2019-12-31 10:00:00+00:00 [Note] [Entrypoint]: Switching to dedicated user 'mysql'
...

Backup and restore

The data in your Wikibase instance is valuable. Regular backups and tested restores of data are vital.

Generally, there are two bodies of data you'll need to back up: the MediaWiki/Wikibase filesystem and, more importantly, the MySQL database.

First and foremost, we recommend reading the Wikibase Docker README to get the lay of the land.

Docker level

Since this is a Docker install, backup using Docker tools is recommended.

Docker-level backup is explained in some detail in this section of the wikibase-docker README. It involves backing up the Docker volumes and dumping out the database with mysqldump.

For a helpful overview of Docker data backup and restore, including the use of the docker save and docker load commands, read this excellent StackOverflow post. It's been updated several times since its original posting in 2014 and constitutes a great tour and jumping-off point for the docker command-line reference linked above.

On-container level

Backup on the container level is not an easy proposition; we cover it here mainly to present a more complete picture of MediaWiki and Wikibase under the hood.

To that end, read the documentation on backing up a MediaWiki, bearing in mind that the work needs to be done from within the containers (cf. Docker tooling above) and the data extracted and placed somewhere safe outside of Docker.

Wiki tools

Wikibase is an extension of MediaWiki. Much of the functionality you'll be working with is actually that of MediaWiki, so consult the MediaWiki technical manual and the administrator's hub. Of particular note:

Updating

Keeping software up to date is the only way to obtain new features, not to mention how important it is to apply bug and security fixes.

Updating Wikibase on Docker involves upgrading MediaWiki itself (see the MediaWiki update documentation) as well as tweaking the docker-compose.yml file itself.

We recommend reading Adam Shorland's blog post for a step-by-step guide to updating your Wikibase.

(next: Extending)