From 4d934af11568f27d3c917a40bb69dfe7df200586 Mon Sep 17 00:00:00 2001 From: Dat Date: Mon, 16 Feb 2026 12:09:30 +0100 Subject: [PATCH 1/6] Update dev-environment.md Bug: T416479 --- docs/dev-environment.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/dev-environment.md b/docs/dev-environment.md index 3be79c5e1..147cbcdd5 100644 --- a/docs/dev-environment.md +++ b/docs/dev-environment.md @@ -2,9 +2,9 @@ There is a [docker-compose file](../docker-compose.yml) in the root directory that allows for serving multiple development sites locally. -These are currently not using the real API but instead get their settings from the static JSON files included in the data folder. +These are currently not using the real API but instead get their settings from static JSON files in [docker-compose/fake-api](../docker-compose/fake-api/). -The fake API is served by the [server.php](test/server.php) script and reads the corresponding [subdomain](data/WikiInfo-site1.json) from each request. +The fake API is served by [index.php](../docker-compose/fake-api/index.php) and reads the JSON matching the requested subdomain (for example [WikiInfo-site1.json](../docker-compose/fake-api/WikiInfo-site1.json)). > [!NOTE] > You may find you have to refresh the page a few times before changes are reflected in Elasticsearch. Unlike [wmde/wbaas-deploy](https://github.com/wmde/wbaas-deploy/), this setup doesn't have a dedicated job runner. Jobs queued up, such as ones from CirrusSearch and WikibaseCirrusSearch, are completed as part of web requests (see [wbstack/src/Settings/LocalSettings.php#L147-L151](https://github.com/wbstack/mediawiki/blob/ebac07a4a4096d8fd973ebd43ebe342f34b87803/dist-persist/wbstack/src/Settings/LocalSettings.php#L147-L151)), so refreshing the page ensures that all jobs in the queue are run. From b0365620535e003eeceaf07a17500410cb49a1b8 Mon Sep 17 00:00:00 2001 From: Dat Date: Mon, 16 Feb 2026 12:20:22 +0100 Subject: [PATCH 2/6] Update dev-environment.md --- docs/dev-environment.md | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/docs/dev-environment.md b/docs/dev-environment.md index 147cbcdd5..141f9ebda 100644 --- a/docs/dev-environment.md +++ b/docs/dev-environment.md @@ -6,8 +6,12 @@ These are currently not using the real API but instead get their settings from s The fake API is served by [index.php](../docker-compose/fake-api/index.php) and reads the JSON matching the requested subdomain (for example [WikiInfo-site1.json](../docker-compose/fake-api/WikiInfo-site1.json)). +In [wmde/wbaas-deploy](https://github.com/wmde/wbaas-deploy/) Elasticsearch is configured so all Wikis share the same indices. In contrast, this docker compose environment is configured so each wiki has its own indices. From Mediawiki's perspective, Elasticsearch does not distunguish between private and shared indices via an alias; the index configuration is invisible to Mediawiki. This keeps the setup simple and light to run. + +The index names are based on the MediaWiki database name (not the domain). This is why indices appear in the format `{db_name}_content_first` and `{db_name}_general_first`, for example `mwdb_somedb1_content_first`. + > [!NOTE] -> You may find you have to refresh the page a few times before changes are reflected in Elasticsearch. Unlike [wmde/wbaas-deploy](https://github.com/wmde/wbaas-deploy/), this setup doesn't have a dedicated job runner. Jobs queued up, such as ones from CirrusSearch and WikibaseCirrusSearch, are completed as part of web requests (see [wbstack/src/Settings/LocalSettings.php#L147-L151](https://github.com/wbstack/mediawiki/blob/ebac07a4a4096d8fd973ebd43ebe342f34b87803/dist-persist/wbstack/src/Settings/LocalSettings.php#L147-L151)), so refreshing the page ensures that all jobs in the queue are run. +> You may find you have to refresh the page a few time before changes are reflected in Elasticsearch. Unlike [wmde/wbaas-deploy](https://github.com/wmde/wbaas-deploy/), this setup doesn't have a dedicated job runner. Jobs queued up, such as ones from CirrusSearch and WikibaseCirrusSearch, are completed as part of web requests (see [wbstack/src/Settings/LocalSettings.php#L147-L151](https://github.com/wbstack/mediawiki/blob/ebac07a4a4096d8fd973ebd43ebe342f34b87803/dist-persist/wbstack/src/Settings/LocalSettings.php#L147-L151)), so refreshing the page ensures that all jobs in the queue are run. ### Start the dev environment @@ -32,8 +36,12 @@ Wait until both sites are accessible: Once the sites are accessible you can perform secondary setup (_The request takes a while to execute_): ```sh -curl -sS -H "Content-Type: application/json" -X POST -d '{}' "http://site1.localhost:8001/w/api.php?action=wbstackElasticSearchInit&format=json" | jq -curl -sS -H "Content-Type: application/json" -X POST -d '{}' "http://site2.localhost:8001/w/api.php?action=wbstackElasticSearchInit&format=json" | jq +curl -sS -H "Content-Type: application/json" -X POST -d '{}' "http://site1.localhost:8001/w/api.php?action=wbstackElasticSearchInit&format=json" +curl -sS -H "Content-Type: application/json" -X POST -d '{}' "http://site2.localhost:8001/w/api.php?action=wbstackElasticSearchInit&format=json" + +# You can use `jq` to "pretty-print" the JSON response +curl -sS -H "Content-Type: application/json" -X POST -d '{}' "http://site1.localhost:8001/w/api.php?action=wbstackElasticSearchInit&format=json" | jq . +curl -sS -H "Content-Type: application/json" -X POST -d '{}' "http://site2.localhost:8001/w/api.php?action=wbstackElasticSearchInit&format=json" | jq . ``` Removing the installation: @@ -46,13 +54,11 @@ Understanding special configuration for the `docker compose` environment: When `$wwDockerCompose` is set some special settings are used. It is set from the environment variable `WBSTACK_DOCKER_COMPOSE` and is always true in the `docker compose` environment. Examples of this include disabling captchas, disabling the normally required email confirmation and automatically granting sysop rights to all users. -### Elasticsearch +### Debugging Elastic + +#### General overview of the cluster: - Overall stats: http://localhost:9200/_stats - Indices: http://localhost:9200/_cat/indices - Aliases: http://localhost:9200/_aliases - Entries in the content index (Items, Lexemes) for `site1.localhost`: http://localhost:9200/mwdb_somedb1_content_first/_search - -In [wmde/wbaas-deploy](https://github.com/wmde/wbaas-deploy/) Elasticsearch is configured so all Wikis share the same indices. In contrast, this docker compose environment is configured so each wiki has its own indices. This is how Elasticsearch was configured when this docker composer development environment was created. As MediaWiki isn't creating new indices, whether Elasticsearch uses shared indices via aliases or not is inconsequential. Investing time to change this is likely not worth it and having separate indices is a simpler setup. - -The index names are based on the MediaWiki database name (not the domain). This is why indices appear in the format `{db_name}_content_first` and `{db_name}_general_first`, for example `mwdb_somedb1_content_first`. From 37b3574ae0fa21e142609fd9a1c44d327ddbc46e Mon Sep 17 00:00:00 2001 From: Dat Date: Mon, 16 Feb 2026 12:24:01 +0100 Subject: [PATCH 3/6] Revert "Update dev-environment.md" This reverts commit b0365620535e003eeceaf07a17500410cb49a1b8. --- docs/dev-environment.md | 22 ++++++++-------------- 1 file changed, 8 insertions(+), 14 deletions(-) diff --git a/docs/dev-environment.md b/docs/dev-environment.md index 141f9ebda..147cbcdd5 100644 --- a/docs/dev-environment.md +++ b/docs/dev-environment.md @@ -6,12 +6,8 @@ These are currently not using the real API but instead get their settings from s The fake API is served by [index.php](../docker-compose/fake-api/index.php) and reads the JSON matching the requested subdomain (for example [WikiInfo-site1.json](../docker-compose/fake-api/WikiInfo-site1.json)). -In [wmde/wbaas-deploy](https://github.com/wmde/wbaas-deploy/) Elasticsearch is configured so all Wikis share the same indices. In contrast, this docker compose environment is configured so each wiki has its own indices. From Mediawiki's perspective, Elasticsearch does not distunguish between private and shared indices via an alias; the index configuration is invisible to Mediawiki. This keeps the setup simple and light to run. - -The index names are based on the MediaWiki database name (not the domain). This is why indices appear in the format `{db_name}_content_first` and `{db_name}_general_first`, for example `mwdb_somedb1_content_first`. - > [!NOTE] -> You may find you have to refresh the page a few time before changes are reflected in Elasticsearch. Unlike [wmde/wbaas-deploy](https://github.com/wmde/wbaas-deploy/), this setup doesn't have a dedicated job runner. Jobs queued up, such as ones from CirrusSearch and WikibaseCirrusSearch, are completed as part of web requests (see [wbstack/src/Settings/LocalSettings.php#L147-L151](https://github.com/wbstack/mediawiki/blob/ebac07a4a4096d8fd973ebd43ebe342f34b87803/dist-persist/wbstack/src/Settings/LocalSettings.php#L147-L151)), so refreshing the page ensures that all jobs in the queue are run. +> You may find you have to refresh the page a few times before changes are reflected in Elasticsearch. Unlike [wmde/wbaas-deploy](https://github.com/wmde/wbaas-deploy/), this setup doesn't have a dedicated job runner. Jobs queued up, such as ones from CirrusSearch and WikibaseCirrusSearch, are completed as part of web requests (see [wbstack/src/Settings/LocalSettings.php#L147-L151](https://github.com/wbstack/mediawiki/blob/ebac07a4a4096d8fd973ebd43ebe342f34b87803/dist-persist/wbstack/src/Settings/LocalSettings.php#L147-L151)), so refreshing the page ensures that all jobs in the queue are run. ### Start the dev environment @@ -36,12 +32,8 @@ Wait until both sites are accessible: Once the sites are accessible you can perform secondary setup (_The request takes a while to execute_): ```sh -curl -sS -H "Content-Type: application/json" -X POST -d '{}' "http://site1.localhost:8001/w/api.php?action=wbstackElasticSearchInit&format=json" -curl -sS -H "Content-Type: application/json" -X POST -d '{}' "http://site2.localhost:8001/w/api.php?action=wbstackElasticSearchInit&format=json" - -# You can use `jq` to "pretty-print" the JSON response -curl -sS -H "Content-Type: application/json" -X POST -d '{}' "http://site1.localhost:8001/w/api.php?action=wbstackElasticSearchInit&format=json" | jq . -curl -sS -H "Content-Type: application/json" -X POST -d '{}' "http://site2.localhost:8001/w/api.php?action=wbstackElasticSearchInit&format=json" | jq . +curl -sS -H "Content-Type: application/json" -X POST -d '{}' "http://site1.localhost:8001/w/api.php?action=wbstackElasticSearchInit&format=json" | jq +curl -sS -H "Content-Type: application/json" -X POST -d '{}' "http://site2.localhost:8001/w/api.php?action=wbstackElasticSearchInit&format=json" | jq ``` Removing the installation: @@ -54,11 +46,13 @@ Understanding special configuration for the `docker compose` environment: When `$wwDockerCompose` is set some special settings are used. It is set from the environment variable `WBSTACK_DOCKER_COMPOSE` and is always true in the `docker compose` environment. Examples of this include disabling captchas, disabling the normally required email confirmation and automatically granting sysop rights to all users. -### Debugging Elastic - -#### General overview of the cluster: +### Elasticsearch - Overall stats: http://localhost:9200/_stats - Indices: http://localhost:9200/_cat/indices - Aliases: http://localhost:9200/_aliases - Entries in the content index (Items, Lexemes) for `site1.localhost`: http://localhost:9200/mwdb_somedb1_content_first/_search + +In [wmde/wbaas-deploy](https://github.com/wmde/wbaas-deploy/) Elasticsearch is configured so all Wikis share the same indices. In contrast, this docker compose environment is configured so each wiki has its own indices. This is how Elasticsearch was configured when this docker composer development environment was created. As MediaWiki isn't creating new indices, whether Elasticsearch uses shared indices via aliases or not is inconsequential. Investing time to change this is likely not worth it and having separate indices is a simpler setup. + +The index names are based on the MediaWiki database name (not the domain). This is why indices appear in the format `{db_name}_content_first` and `{db_name}_general_first`, for example `mwdb_somedb1_content_first`. From c235f2b7c0f80881c91601b79993e22d98205eb1 Mon Sep 17 00:00:00 2001 From: Dat Date: Mon, 16 Feb 2026 12:26:16 +0100 Subject: [PATCH 4/6] update docker-compose/fake-api/README.md --- docker-compose/fake-api/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docker-compose/fake-api/README.md b/docker-compose/fake-api/README.md index a7351341c..aef73298d 100644 --- a/docker-compose/fake-api/README.md +++ b/docker-compose/fake-api/README.md @@ -2,4 +2,4 @@ This is a fake platform API used during local docker-compose based development & also using some CI. -The docker image simply serves PHP, and server.php is a very simple fake of the `getWikiForDomain` API responses. +The docker image simply serves PHP, and [index.php](./index.php) is a very simple fake of the `getWikiForDomain` API responses. From d1c2dce67dab324d637035c195d9de50f5dbe696 Mon Sep 17 00:00:00 2001 From: Dat Date: Mon, 16 Feb 2026 12:43:10 +0100 Subject: [PATCH 5/6] Use "blob" URLs --- docs/dev-environment.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/dev-environment.md b/docs/dev-environment.md index 147cbcdd5..6bb13cdc6 100644 --- a/docs/dev-environment.md +++ b/docs/dev-environment.md @@ -1,10 +1,10 @@ ## Development Environment -There is a [docker-compose file](../docker-compose.yml) in the root directory that allows for serving multiple development sites locally. +There is a [docker-compose file](https://github.com/wbstack/mediawiki/blob/main/docker-compose.yml) in the root directory that allows for serving multiple development sites locally. -These are currently not using the real API but instead get their settings from static JSON files in [docker-compose/fake-api](../docker-compose/fake-api/). +These are currently not using the real API but instead get their settings from static JSON files in [docker-compose/fake-api](https://github.com/wbstack/mediawiki/blob/main/docker-compose/fake-api). -The fake API is served by [index.php](../docker-compose/fake-api/index.php) and reads the JSON matching the requested subdomain (for example [WikiInfo-site1.json](../docker-compose/fake-api/WikiInfo-site1.json)). +The fake API is served by [index.php](https://github.com/wbstack/mediawiki/blob/main/docker-compose/fake-api/index.php) and reads the JSON matching the requested subdomain (for example [WikiInfo-site1.json](https://github.com/wbstack/mediawiki/blob/main/docker-compose/fake-api/WikiInfo-site1.json)). > [!NOTE] > You may find you have to refresh the page a few times before changes are reflected in Elasticsearch. Unlike [wmde/wbaas-deploy](https://github.com/wmde/wbaas-deploy/), this setup doesn't have a dedicated job runner. Jobs queued up, such as ones from CirrusSearch and WikibaseCirrusSearch, are completed as part of web requests (see [wbstack/src/Settings/LocalSettings.php#L147-L151](https://github.com/wbstack/mediawiki/blob/ebac07a4a4096d8fd973ebd43ebe342f34b87803/dist-persist/wbstack/src/Settings/LocalSettings.php#L147-L151)), so refreshing the page ensures that all jobs in the queue are run. From 31d8a58f65d42188db69f073b1cde65e583a6162 Mon Sep 17 00:00:00 2001 From: Dat Date: Mon, 16 Feb 2026 12:45:05 +0100 Subject: [PATCH 6/6] Use "blob" URL in docker-compose/fake-api/README.md --- docker-compose/fake-api/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docker-compose/fake-api/README.md b/docker-compose/fake-api/README.md index aef73298d..c863cb73b 100644 --- a/docker-compose/fake-api/README.md +++ b/docker-compose/fake-api/README.md @@ -2,4 +2,4 @@ This is a fake platform API used during local docker-compose based development & also using some CI. -The docker image simply serves PHP, and [index.php](./index.php) is a very simple fake of the `getWikiForDomain` API responses. +The docker image simply serves PHP, and [index.php](https://github.com/wbstack/mediawiki/blob/main/docker-compose/fake-api/index.php) is a very simple fake of the `getWikiForDomain` API responses.