This page describes the manual path for installing Wikibase Suite (WBS) with Docker Compose. For the recommended browser-based setup flow, see Installing Wikibase Suite (WBS).
[!IMPORTANT] These instructions are for setting up WBS on an internet-reachable Linux server, not on your laptop or desktop. WBS needs public DNS records and HTTPS certificate setup to work correctly. If you are looking for individual WBS Docker Images instead of the full setup, see hub.docker.com/u/wikibase.
Start by provisioning a Linux VPS or cloud server for your WBS instance. Most Wikibase production installs are on cloud-based servers. Follow your provider’s documentation to create a server that meets the requirements below.
The minimum requirements for your server are as follows:
amd64 / x86_64); ARM servers are not currently supported by the published WBS Docker ImagesYou need a domain you own or control, and access to that domain provider’s DNS settings.
Choose two hostnames for your WBS services: one for Wikibase itself and one for the Query Service. These are the web addresses where people will access your Wikibase and Query Service. Many Wikibase users configure the Query Service as a subdomain of the main address.
Examples:
yourdomain.examplequery.yourdomain.exampleIn your DNS provider’s control panel, create two records of either A or CNAME type, one for each hostname. Point both records to your server’s public IP address. Note that DNS record changes may take a few minutes to propagate.
[!NOTE] Your DNS provider may call the IP address field
value,content,address, orpoints to. Use only the server’s public IP address as the value.
To learn more about DNS records, see DNS basics or Understanding DNS records. Common provider guides are also available for Cloudflare, GoDaddy, and Namecheap.
Most bare VPS instances do not have current versions of Docker, Docker Compose, or git installed. Before continuing, install these dependencies on your server:
Check out the files from GitHub, then change to the repository directory.
git clone https://github.com/wmde/wikibase-suite
cd wikibase-suite
Make a copy of the example environment file in the WBS directory.
cp .env.example .env
Edit .env and set the values below.
| Setting | Default value | Description |
|---|---|---|
WIKIBASE_PUBLIC_HOST |
None | The public hostname for your Wikibase web interface. Use one of the hostnames from step 2, without https:// or a trailing slash. |
WDQS_PUBLIC_HOST |
None | The public hostname for the Query Service web interface and SPARQL endpoint. Use the other hostname from step 2, without https:// or a trailing slash. This must be different from WIKIBASE_PUBLIC_HOST. |
MW_ADMIN_NAME |
None | The username for the first MediaWiki administrator account. |
MW_ADMIN_EMAIL |
None | The email address for the first MediaWiki administrator account. |
MW_ADMIN_PASS |
None | The password for the first MediaWiki administrator account. It must be at least 10 characters, must be different from MW_ADMIN_NAME, and must not appear in the list of commonly used passwords checked by MediaWiki. |
DB_NAME |
my_wiki |
The name of the MariaDB database created for MediaWiki. The default value can be used for a new install. |
DB_USER |
sqluser |
The MariaDB user created for MediaWiki. The default value can be used for a new install. |
DB_PASS |
change-this-password |
The MariaDB password for DB_USER. Set this to something other than the default value before first start. |
METADATA_CALLBACK |
true |
Set to true to opt into the WBS metadata callback, or false to opt out. |
WIKIMEDIA_OAUTH_CONSUMER_TOKEN (optional) |
None | Wikimedia OAuth consumer token. See Enabling Login with Wikimedia. |
WIKIMEDIA_OAUTH_SECRET_TOKEN (optional) |
None | Wikimedia OAuth secret token. |
[!WARNING] With the exception of
METADATA_CALLBACKand the twoWIKIMEDIA_OAUTH_*values,.envvalues are setup values. To change them after first start, follow Resetting an Instance.
Run the following command from within the WBS directory:
docker compose up -d
The first start may take a couple of minutes. You can check the status of the stack by running docker compose ps from another terminal. When your WBS instance is ready, the wikibase service will be marked healthy.
You can now access your services using the hostnames you set in .env:
https://<WIKIBASE_PUBLIC_HOST>https://<WDQS_PUBLIC_HOST>https://<WDQS_PUBLIC_HOST>/sparqlhttps://<WIKIBASE_PUBLIC_HOST>/tools/quickstatements[!NOTE] If anything goes wrong, see Troubleshooting.
To stop WBS without deleting data, run:
docker compose down
To restart it, run:
docker compose up -d
If something is not working as expected, start with Troubleshooting. If you have questions or need help, use this bug report form to start a conversation with the engineering team.