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.

Docker required
You'll need to have Docker installed and configured on the computer or server you're installing on to. If you 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
We're almost done, but there are a few things you need to set to get Wikibase running the first time. If moving into production or otherwise to get familiar with additional configuration options, please see [Advanced Configuration] below. Inside the .env file found in the launch directory which you created above:

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 `MW_SECRET_KEY=some-secret-key` 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 `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  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 have one more choice: whether to perform a full install (MediaWiki, database, Wikibase, WDQS, Elasticsearch, QuickStatements) or a minimal install (just MediaWiki, a backing MySQL database and Wikibase).

For a full installation, run the following command from the launch directory where you copied and modified your files above:

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

Or, for a minimal installation, run:

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.

MediaWiki Advanced Configuration
The  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:


 * : The default is `my_wiki`. Configure according to your environment requirements.
 * : The default is `sql_user`. Configure according to your environment requirements.


 * 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.

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.









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,  ,   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.

You can specify that the job runner should run more jobs between restarts by setting  higher than its default value of 1. See below for more information on the job runner.

Job Runners
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

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.

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.

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.