This is a step-by-step guide to installing Wikibase Suite on your own computer using Docker.
Our Docker images contain a complete install of MediaWiki and Wikibase, and the install process is customisable to suit your needs.
Preparing your environment[edit source]
Complete all these steps before beginning the Wikibase install.
Install Docker[edit source]
On the computer where you want to run Wikibase, first install Docker.
Check out files[edit source]
Check out the Wikibase pipeline repository from GitHub to obtain the example configuration files. The latest release is
wmde.13, so run the following commands:
git clone https://github.com/wmde/wikibase-release-pipeline cd wikibase-release-pipeline git checkout tags/wmde.13
Prepare your files[edit source]
Create a new launch directory from which you will launch Docker. Bear in mind the name of that directory will appear in your Docker container names. For this example we will create the directory "wbdocker".
mkdir $HOME/wbdocker cp -r example/* $HOME/wbdocker cd $HOME/wbdocker mv template.env .env
Customise your environment[edit source]
.env file contains the environment variables that govern your Wikibase installation. You will need to edit this file and change the information on specific lines as follows.
MediaWiki Configuration[edit source]
These values define the username, password and email address of the administrative user in your new MediaWiki installation. You'll use this username and password to log into the web interface of your new instance for the first time; the email address you enter here will also allow you to reset your password if needed.
This secret key should be unique; MediaWiki uses it for several purposes (e.g., session management, fallback cryptographic entropy source). See the link for further information. To generate a random string for use in this file:
echo -n "MW_SECRET_KEY=" tr -dc 'A-Za-z0-9@#%^+_-' </dev/urandom | head -c 64 ; echo ''
Database Configuration[edit source]
These values control the name of the database that MediaWiki will use, as well as the database username and password.
At the bare minimum, change
echo -n "DB_PASS=" tr -dc 'A-Za-z0-9@#%^+_-' </dev/urandom | head -c 32 ; echo ''
Wikibase Configuration[edit source]
By default, the Wikibase pingback feature is disabled.
Please consider enabling this feature (which sends only anonymised data) by changing
Enabling this feature significantly improves Wikimedia Deutschland's insight into how Wikibase is being used and helps us make more informed decisions regarding the development roadmap. For more information, read our pingback documentation topic.
These lines define the host name and port of your Wikibase (what you would put in your browser’s address bar) and, optionally, of the external services for an extended install.
Sandbox users (those who want only a locally accessible setup on a single computer) can and should leave this section untouched.
However, if you plan to use any of the above external services outside of a self-contained Docker setup, you need to set
MW_ELASTIC_HOST to publicly accessible hostnames -- that is, hostnames that can be resolved in DNS -- or IP addresses.
The latter might be the right choice if you're running this on a local network.
in any setup that requires separate services to talk to one another.
Installing and running Wikibase[edit source]
Now that you've installed all the needed software and customised your environment file, you have one more choice: whether to perform a minimal install (just MediaWiki, a backing MySQL database and Wikibase) or an extended install (MediaWiki, database, Wikibase, WDQS, Elasticsearch, QuickStatements).
Minimal install[edit source]
For a minimal install, in the launch directory where you copied and modified your files, simply run:
docker compose up -d
Extended install[edit source]
For an extended install, in the launch directory where you copied and modified your files, run this extended command:
docker compose -f docker-compose.yml -f docker-compose.extra.yml up -d
If you need to run multiple job runners, you can add the following option (with X being the number of job runners to run) onto your
docker compose command, as in this example:
docker compose up -d --scale wikibase_jobrunner=X
Up and running[edit source]
You will now have at least two Docker containers running.
To see your running containers, run
docker compose ps.
The following example output is from an extended install:
$ docker compose ps NAME COMMAND SERVICE STATUS PORTS wbdocker-elasticsearch-1 "/usr/local/bin/dock…" elasticsearch running 9300/tcp wbdocker-mysql-1 "docker-entrypoint.s…" mysql running 3306/tcp wbdocker-quickstatements-1 "/bin/bash /entrypoi…" quickstatements running 0.0.0.0:8840->80/tcp, :::8840->80/tcp wbdocker-wdqs-1 "/entrypoint.sh /run…" wdqs running 9999/tcp wbdocker-wdqs-frontend-1 "/entrypoint.sh ngin…" wdqs-frontend running 0.0.0.0:8834->80/tcp, :::8834->80/tcp wbdocker-wdqs-proxy-1 "/bin/sh -c \"/entryp…" wdqs-proxy running 80/tcp wbdocker-wdqs-updater-1 "/entrypoint.sh /run…" wdqs-updater running wbdocker-wikibase-1 "/bin/bash /entrypoi…" wikibase running 0.0.0.0:80->80/tcp, :::80->80/tcp wbdocker-wikibase_jobrunner-1 "/bin/bash /jobrunne…" wikibase_jobrunner running 80/tcp
For some more helpful Wikibase-oriented Docker commands, check out the Docker tooling section of our maintenance documentation.
Log into your new Wikibase by navigating to your local machine's web server.
Job runner[edit source]
docker-compose.yml sets up a dedicated job runner which restarts itself after every job, to ensure that changes to the configuration are picked up as quickly as possible.
If you run large batches of edits, this job runner may not be able to keep up with edits.
You can speed it up by increasing the MAX_JOBS variable in your
.env file (see above), in order to run more jobs between restarts.
This change won't take effect in the job runner until you restart your
docker compose project.
If you wish, you can also run several job runners in parallel by adding the option
--scale wikibase_jobrunner=8 to the
docker compose up command.
See the Installing section above.
Using your new instance[edit source]
Once all services have started, you can begin filling up, extending and customising your empty instance of Wikibase. Take a look at our setup resources page to get started.