User:Loren Johnson (WMDE)/drafts
Overview edit
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 Wikibase/Suite. For installing just the Wikibase extension within an existing MediaWiki installation, see Wikibase/Installation.
Installation edit
Download edit
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 edit
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 edit
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 edit
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 edit
Sitelinks edit
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 edit
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
falsetotrue. 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.
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.svcWIKIBASE_PORT=80WDQS_FRONTEND_HOST=wdqs-frontend.svcWDQS_FRONTEND_PORT=8834QUICKSTATEMENTS_HOST=quickstatements.svcQUICKSTATEMENTS_PORT=8840MW_ELASTIC_HOST=elasticsearch.svcMW_ELASTIC_PORT=9200
Job Runners edit
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 edit
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 edit
Confirm Services are Up and Running in Docker edit
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
For some more helpful Wikibase-oriented Docker commands, check out the Docker tooling section of our maintenance documentation.