docs: docusaurus

Dockerfile

@@ -54,4 +54,7 @@ ENV PATH="/root/.local/share/pnpm:${PATH}"
 # Add npm module bins and activate Python venv virtual environment
 ENV PATH="/workspace/node_modules/.bin:/root/venv/bin:$PATH"
 
+# https://github.com/nrwl/nx/issues/27040
+ENV NX_ISOLATE_PLUGINS=false
+
 ENTRYPOINT [ "./entrypoint.sh" ]

build/wikibase/CHANGELOG.md

@@ -1,11 +1,10 @@
 ## 3.0.2 (2024-10-28)
 
-
 ### 🏡 Chore
 
 - bump mediawiki to 1.42.3, bump extensions
 
-## **wikibase@3.0.1** (2024-10-09)
+## 3.0.1 (2024-10-09)
 
 ### 📖 Documentation
 
@@ -16,3 +15,9 @@
 
 - Removes re-installation of extensions already packaged with MediaWiki (ConfirmEdit, Nuke, Scribunto, SyntaxHighlight_Geshi, VisualEditor)
 - Updates Wikibase EDTF extension
+
+## 3.0.0 (2024-07-15)
+
+### 🏡 Chore
+
+- Initial release featuring MediaWiki 1.42.1.

deploy/CHANGELOG.md

@@ -24,7 +24,7 @@
 
 - bump deploy to version 2
 
-## **deploy@3.0.1** (2024-10-09)
+## 3.0.1 (2024-10-09)
 
 ### 🩹 Fixes
 
@@ -41,3 +41,18 @@
 ### 🏡 Chore
 
 - Adds default Traefik LetsEncrypt configuration for services
+
+## 3.0.0 (2024-07-15)
+
+### 🏡 Chore
+- Initial release featuring MediaWiki 1.42.
+
+## 2.0.0 (2024-07-15)
+
+### 🏡 Chore
+- Initial release featuring MediaWiki 1.41.
+
+## 1.0.0 (2024-07-15)
+
+### 🏡 Chore
+- Initial release featuring MediaWiki 1.39.

docker-compose.yml

@@ -8,13 +8,14 @@ networks:
 services:
   runner:
     image: wbs-dev-runner:latest
-    scale: 0
+    scale: 1
     build:
       context: .
     stop_grace_period: 1s
     ports:
       - 9229:9229
       - 4211:4211
+      - 3000:3000
     volumes:
       - .:/workspace
       - /var/run/docker.sock:/var/run/docker.sock
@@ -23,3 +24,7 @@ services:
       - local.env
     environment:
       HOST_PWD: $PWD
+    entrypoint:
+      - sleep
+    command:
+      - infinity

docs/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docs/README.md

@@ -0,0 +1,41 @@
+# Website
+
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ yarn
+```
+
+### Local Development
+
+```
+$ yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+Using SSH:
+
+```
+$ USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```
+$ GIT_USER=<Your GitHub username> yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

docs/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

docs/deploy/01_intro.md

@@ -0,0 +1,28 @@
+---
+sidebar_position: 1
+slug: /
+sidebar_label: Introduction
+---
+# Wikibase Suite Deploy
+
+Wikibase Suite (WBS) Deploy is a containerized, production-ready [Wikibase](https://wikiba.se) system that allows you to self-host a knowledge graph similar to [Wikidata](https://www.wikidata.org/wiki/Wikidata:Main_Page). In addition to Wikibase on MediaWiki, WBS Deploy includes the Wikidata Query Service (WDQS), QuickStatements, Elasticsearch, and a Traefik reverse proxy with SSL termination and ACME support. The service orchestration is implemented using Docker Compose.
+
+> 🔧 This document is for people wanting to self-host the full Wikibase Suite using Wikibase Suite Deploy. If you are looking for individual WBS images, head over to [hub.docker.com/u/wikibase](https://hub.docker.com/u/wikibase).
+
+> 💡 This document presumes familiarity with basic Linux administration tasks and with Docker and Docker Compose.
+
+### What's in the box?
+
+WBS Deploy consists of the following services:
+
+- **[Wikibase](https://hub.docker.com/r/wikibase/wikibase)** MediaWiki packaged with the Wikibase extension and other commonly used extensions.
+- **Job Runner** The MediaWiki [JobRunner](https://www.mediawiki.org/wiki/Manual:Job_queue#Cron) service which uses the same Wikibase container as above.
+- **[MariaDB](https://hub.docker.com/_/mariadb)** Database service for MediaWiki and Wikibase.
+- **[Elasticsearch](https://hub.docker.com/r/wikibase/elasticsearch)** Search service used by MediaWiki.
+- **[WDQS](https://hub.docker.com/r/wikibase/wdqs)** Wikidata Query Service to process SPARQL queries.
+- **[WDQS Frontend](https://hub.docker.com/r/wikibase/wdqs-frontend)** Web front end for SPARQL queries.
+- **[WDQS Proxy](https://hub.docker.com/r/wikibase/wdqs-proxy)** A middle layer for WDQS which serves to filter requests and make the service more secure.
+- **[WDQS Updater](https://www.mediawiki.org/wiki/Wikidata_Query_Service/User_Manual#runUpdate.sh)** Keeps the WDQS data in sync with Wikibase.
+- **[Quickstatements](https://hub.docker.com/r/wikibase/quickstatements)** A web-based tool to import and manipulate large amounts of data.
+- **[Traefik](https://hub.docker.com/_/traefik)** A reverse proxy that handles TLS termination and SSL certificate renewal through ACME.
+

docs/deploy/02_quickstart.md

@@ -0,0 +1,63 @@
+# Quickstart
+
+> 💡 If you want to run a quick test on a machine that has no public IP address (such as your local machine), check our [FAQ entry](./09_faq.md#can-i-host-wbs-deploy-locally) below.
+
+### Requirements
+
+#### Hardware
+
+- Network connection with a public IP address
+- AMD64 architecture
+- 8 GB RAM
+- 4 GB free disk space
+
+#### Software
+
+- Docker 22.0 (or greater)
+- Docker Compose 2.10 (or greater)
+- git
+
+#### Domain names
+
+You need three DNS records that resolve to your machine's IP address, one for each user-facing service:
+
+- Wikibase, e.g., "wikibase.example"
+- QueryService, e.g., "query.example"
+- QuickStatements, e.g., "quickstatements.example"
+
+### Initial setup
+
+#### Download WBS Deploy
+
+Check out the files from Github, move to the subdirectory `deploy` and check out the latest stable branch.
+
+```sh
+git clone https://github.com/wmde/wikibase-release-pipeline
+cd wikibase-release-pipeline/deploy
+git checkout deploy-3
+```
+
+#### Initial configuration
+
+Make a copy of the configuration template in the `wikibase-release-pipeline/deploy` directory.
+
+```sh
+cp template.env .env
+```
+
+Follow the instructions in the comments in your newly created `.env` file to set usernames, passwords and domain names.
+
+#### Starting
+
+Run the following command from within `wikibase-release-pipeline/deploy`:
+
+```sh
+docker compose up
+```
+
+The first start can take a couple of minutes. Wait for your shell prompt to return.
+
+🎉 Congratulations, your Wikibase Suite instance should now be up and running. Web interfaces are available over HTTPS (port 443) for the domain names you configured for Wikibase, the WDQS front end and Quickstatements.
+
+> 💡 If anything goes wrong, you can run `docker logs <CONTAINER_NAME>` to see some hopefully helpful error messages.
+

docs/deploy/03_stopping_resetting.md

@@ -0,0 +1,25 @@
+# Stopping and Resetting
+
+## Stopping
+
+To stop, use
+
+```sh
+docker compose stop
+```
+
+## Resetting the configuration
+
+Most values set in `.env` are written into the respective containers after you run `docker compose up` for the first time.
+
+If you want to reset the configuration while retaining your existing data:
+
+1. Make any needed changes to the values in the `.env` file copied from `template.env` above. NOTE: Do not change `DB_*` values unless you are also [re-creating the database](./07_remove.md#removing-wikibase-suite-completely-with-all-its-data).
+2. Delete your `LocalSettings.php` file from the `./config` directory.
+3. Remove and re-create containers:
+
+```sh
+docker compose down
+docker compose up
+```
+

docs/deploy/04_advanced_config.md

@@ -0,0 +1,22 @@
+# Advanced Configuration
+On first launch, WBS Deploy will create files in the `./config` directory alongside your `.env` file, the `docker-compose.yml` and `template.env`. This is your instance configuration. **You own and control those files.** Be sure to include them in your backups.
+
+## config/LocalSettings.php
+
+This file is generated by the [MediaWiki installer script](https://www.mediawiki.org/wiki/Manual:Install.php) and supplemented by the Wikibase container's `entrypoint.sh` script on first launch. Once this file has been generated, you own and control it. This means that not only *can* you make changes to it, you may *need* to do so for [major version updates](https://www.mediawiki.org/wiki/Manual:Upgrading#Adapt_your_LocalSettings.php).
+
+If `config/LocalSettings.php` is missing, it triggers the Wikibase container to run the [MediaWiki installer script](https://www.mediawiki.org/wiki/Manual:Install.php). If you need to run the installer again, you can remove the generated `LocalSettings.php` file (but keep a backup just in case!) and restart your instance.
+
+## config/wikibase-php.ini
+This is Wikibase's `php.ini` override file, a good place for tuning PHP configuration values. It gets loaded by the Wikibase web server's PHP interpreter.
+
+## docker-compose.yml
+To further customize your instance, you can also make changes to `docker-compose.yml`. To ease updating to newer versions of WBS Deploy, consider putting your customizations into a new file called `docker-compose.override.yml`. If you do this, you'll need to start using the following commands to restart your instance:
+
+```sh
+docker compose -f docker-compose.yml -f docker-compose.override.yml down
+docker compose -f docker-compose.yml -f docker-compose.override.yml up --wait
+```
+
+This way, your changes are kept separate from the original WBS Deploy code.
+

docs/deploy/05_data.md

@@ -0,0 +1,49 @@
+# Your data
+Besides [your configuration](./04_advanced_config.md), it's your data that makes your instance unique. All instance data is stored in [Docker volumes](https://docs.docker.com/storage/volumes/).
+
+ - `wikibase-image-data`: MediaWiki image and media file uploads
+ - `mysql-data`: MediaWiki/Wikibase MariaDB raw database
+ - `wdqs-data`: Wikidata Query Service raw database
+ - `elasticsearch-data`: Elasticsearch raw database
+ - `quickstatements-data`: generated Quickstatements OAuth binding for this MediaWiki instance
+ - `traefik-letsencrypt-data`: SSL certificates
+
+## Back up your data
+To back up your data, shut down the instance and dump the contents of all Docker volumes into `.tar.gz` files.
+
+```sh
+docker compose down
+
+for v in \
+    wbs-deploy_elasticsearch-data \
+    wbs-deploy_mysql-data \
+    wbs-deploy_quickstatements-data \
+    wbs-deploy_traefik-letsencrypt-data \
+    wbs-deploy_wdqs-data \
+    wbs-deploy_wikibase-image-data \
+    ; do
+  docker run --rm --volume $v:/backup debian:12-slim tar cz backup > $v.tar.gz
+done
+```
+
+## Restore from a backup
+
+To restore the volume backups, ensure your instance has been shut down by running `docker compose down` and populate the Docker volumes with data from your `.tar.gz` files.
+
+```sh
+docker compose down
+
+for v in \
+    wbs-deploy_elasticsearch-data \
+    wbs-deploy_mysql-data \
+    wbs-deploy_quickstatements-data \
+    wbs-deploy_traefik-letsencrypt-data \
+    wbs-deploy_wdqs-data \
+    wbs-deploy_wikibase-image-data \
+    ; do
+  docker volume rm $v 2> /dev/null
+  docker volume create $v
+  docker run -i --rm --volume $v:/backup debian:12-slim tar xz < $v.tar.gz
+done
+```
+