User:Loren Johnson (WMDE)/drafts

Overview


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 customizable to suit your needs.

If you do not already have Docker installed and need help installing Docker beyond Docker's own instructions, you can consult these third-party tutorials for Linux, Mac and Windows.

''For installation instructions without Docker, see. For installing just the Wikibase extension within an existing MediaWiki installation, see .''

Download
Check out the Wikibase pipeline repository from GitHub to obtain the example configuration files. The latest release is, so run the following commands:

git clone https://github.com/wmde/wikibase-release-pipeline cd wikibase-release-pipeline git checkout tags/wmde.11

Then, create a new launch directory from which you will launch Docker. For this example we will create the directory wbdocker.

mkdir $HOME/wbdocker cp -r example/* $HOME/wbdocker cd $HOME/wbdocker mv template.env .env

Configure
There are a few things to configured to get Wikibase running the first time. Below are the values you need to populate or change inside the .env file found in the launch directory created above. There are additional additional options to be considered when moving a server into production, please see [Advanced Configuration] below for those:

1. :  MediaWiki uses this key for several purposes (e.g., session management, fallback cryptographic entropy source), and its important that it is unique amongst all other wikis. To generate an appropriately random string for this, you can run this comamnd, and replace the  line in the `.env` file.

echo -n "MW_SECRET_KEY=" tr -dc 'A-Za-z0-9@#%^+_-' </dev/urandom | head -c 64 ; echo ''

2.  and  : Set a secure password for the underlying database and your MediaWiki admin login. It must be at least 8 characters long. Here is a command line snippet you can run to generate a secure and unique password:

echo -n "DB_PASS=" tr -dc 'A-Za-z0-9@#%^+_-' </dev/urandom | head -c 32 ; echo ''

3. :  You'll use this username and password to log into the web interface of your new instance for the first time; the email address will also allow you to reset your password if needed.

4. : The default is , which is fine for testing locally. You may wish to change this to something else in production. You'll use this username along with the  set above to log into the web interface of your new instance for the first time.

Run Wikibase
Now that you've installed all the needed software and customized your environment file you can run your instance of Wikibase.

From the launch directory you created above, run the following Docker command:

docker compose -f docker-compose.yml -f docker-compose.extra.yml up -d

This runs the full WikiBase Suite including MediaWiki, the WikiBase extension (and others), WikiData Query Service (WDQS), Elasticsearch, and QuickStatements.

Optionally you can run only MediaWiki with the WikiBase extension and the required MySQL database service:

docker compose up -d

Using your new Wikibase
Navigating to your local machine's web server and use the  and   to login.

If you don't find a running Wikibase Suite Instance running at that URL, please consult the [Troubleshooting] section below.

Once all services have started, you can begin filling up, extending and customizing your empty instance of Wikibase.

Take a look at our setup resources page to get started.

Sitelinks
To create links between MediaWiki and Wikibase, run the add site script. You can learn more about adding sitelinks on the Wikidata sitelinks help page and the Wikibase advanced configuration page.

Additional environment configuration options
The  file contains the environment variables that govern your Wikibase installation.


 * WIKIBASE_PINGBACK=false: By default, the Wikibase pingback feature is disabled. Please consider enabling this feature (which sends only anonymized data) by changing   to  .  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.
 * : The default is `my_wiki`. Configure according to your environment requirements.
 * : The default is `sql_user`. Configure according to your environment requirements.

If you plan to use any of the Wikibase Suite services outside of a self-contained Docker setup running locally, you need to set,  ,   and/or   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.

Sandbox users (those who want only a locally accessible setup on a single computer) can and mostly should leave these values at their defaults.

Hostnames configuration: 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.



Job Runners
You can specify that the job runner should run more jobs between restarts by setting

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  command, as in this example:

docker compose up -d --scale wikibase_jobrunner=X

Job runner
The example  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  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  project.

If you wish, you can also run several job runners in parallel by adding the option  to the   command.

See the Installing section above.

Confirm Services are Up and Running in Docker
To see your running containers, run.

You will now have at least two Docker containers running.

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.