User:Loren Johnson (WMDE)/drafts

Overview

Wikibase Cloud Vertical 2x RGB

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 meet 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 Wikibase/Suite . For installing just the Wikibase extension within an existing MediaWiki installation, see Wikibase/Installation .

Installation

Download

Check out the Wikibase pipeline repository from GitHub to obtain the example configuration files. The latest release is wmde.11, 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. MW_WG_SECRET_KEY : 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 MW_WG_SECRET_KEY=some-secret-key line in the `.env` file.

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

2. DB_PASS and MW_ADMIN_PASS: 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. MW_ADMIN_EMAIL: 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. MW_ADMIN_NAME: The default is admin, 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 MW_ADMIN_PASS 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 MW_ADMIN_NAME and MW_ADMIN_PASS 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.

Advanced configuration

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 .env 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 false to true. 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.
DB_NAME: The default is `my_wiki`. Configure according to your environment requirements.
DB_USER: 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 WIKIBASE_HOST, WDQS_FRONTEND_HOST, QUICKSTATEMENTS_HOST and/or 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.

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

Don't use localhost in any setup that requires separate services to talk to one another.

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.

WIKIBASE_HOST=wikibase.svc
WIKIBASE_PORT=80
WDQS_FRONTEND_HOST=wdqs-frontend.svc
WDQS_FRONTEND_PORT=8834
QUICKSTATEMENTS_HOST=quickstatements.svc
QUICKSTATEMENTS_PORT=8840
MW_ELASTIC_HOST=elasticsearch.svc
MW_ELASTIC_PORT=9200

Job Runners

MAX_JOBS: Default value of 1. 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 docker compose command, as in this example:

docker compose up -d --scale wikibase_jobrunner=X

Job runner

The example 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.

Troubleshooting

Confirm Services are Up and Running in Docker

To see your running containers, run docker compose ps.

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

MediaWiki interface for Wikibase Suite prelogin

For some more helpful Wikibase-oriented Docker commands, check out the Docker tooling section of our maintenance documentation.