From b29bf64cdb9f1e7acc32b36bdad4d17cb11b004c Mon Sep 17 00:00:00 2001 From: Le Thuong Date: Fri, 21 Aug 2026 16:17:46 +0700 Subject: [PATCH 1/2] docs(hosting): explain SHOPWARE_ADMIN_ES_REFRESH_INDICES and align its default The environment variable reference only restated the variable name ("Refresh administration indices"), which reads as the Elasticsearch `_refresh` API rather than what it does: create missing administration indices and aliases on entity write. The admin setup snippet also set it to `1`, the only value in that block that diverges from the shipped default. `SHOPWARE_ADMIN_ES_ENABLED` is the switch you have to flip; every other line matches the default, so `=1` here silently opted readers into an alias check per indexer on every write, with the created index staying empty until a reindex. Align the snippet with the installer default and describe the trade-off so enabling it stays a deliberate choice. --- .../configurations/shopware/environment-variables.md | 2 +- .../infrastructure/elasticsearch/elasticsearch-setup.md | 6 +++++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/guides/hosting/configurations/shopware/environment-variables.md b/guides/hosting/configurations/shopware/environment-variables.md index 4e6e52b0f7..ff9a3abf33 100644 --- a/guides/hosting/configurations/shopware/environment-variables.md +++ b/guides/hosting/configurations/shopware/environment-variables.md @@ -46,7 +46,7 @@ This page lists all environment variables that can be used to configure Shopware | `SHOPWARE_ADMIN_ES_ENABLED` | (empty) | Enable Elasticsearch for administration | | `SHOPWARE_ADMIN_ES_INDEX_PREFIX` | `sw-admin` | Index prefix for administration Elasticsearch | | `SHOPWARE_ADMIN_ES_INDEXING_BATCH_SIZE` | `1000` | Batch size for administration Elasticsearch indexing (since 6.7.9.0) | -| `SHOPWARE_ADMIN_ES_REFRESH_INDICES` | (empty) | Refresh administration indices | +| `SHOPWARE_ADMIN_ES_REFRESH_INDICES` | (empty) | Automatically create missing administration indices and aliases when an indexed entity is written, instead of requiring `bin/console es:admin:index` (`1` to enable, `0` to disable). Costs one alias check per indexer on every write, and auto-created indices start empty until a full reindex. | | `SHOPWARE_ADMIN_ES_THROW_EXCEPTION` | `1` | Whether to throw exceptions on administration Elasticsearch errors (`1` to enable, `0` to disable). Mainly useful in local development for debugging (since 6.7.9.0) | | `SHOPWARE_ADMINISTRATION_PATH_NAME` | `admin` | Custom path name for administration interface | | `SHOPWARE_DBAL_TIMEZONE_SUPPORT_ENABLED` | `0` | Enable timezone support in DBAL | diff --git a/guides/hosting/infrastructure/elasticsearch/elasticsearch-setup.md b/guides/hosting/infrastructure/elasticsearch/elasticsearch-setup.md index 6e9f1ad219..d6cabba1b7 100644 --- a/guides/hosting/infrastructure/elasticsearch/elasticsearch-setup.md +++ b/guides/hosting/infrastructure/elasticsearch/elasticsearch-setup.md @@ -202,10 +202,14 @@ ADMIN_OPENSEARCH_URL=YOUR OPENSEARCH URL SHOPWARE_ADMIN_ES_ENABLED=1 SHOPWARE_ADMIN_ES_INDEX_PREFIX=sw-admin SHOPWARE_ADMIN_ES_INDEXING_BATCH_SIZE=1000 -SHOPWARE_ADMIN_ES_REFRESH_INDICES=1 +SHOPWARE_ADMIN_ES_REFRESH_INDICES=0 SHOPWARE_ADMIN_ES_THROW_EXCEPTION=1 ``` +::: info +`SHOPWARE_ADMIN_ES_REFRESH_INDICES=1` makes Shopware create missing administration indices and aliases on the fly when an indexed entity is written, instead of relying on `bin/console es:admin:index`. Enable it in environments where nobody runs CLI commands after installing an extension or replacing the search cluster. It adds one alias check per indexer to every write, and an index created this way stays empty until a full reindex, so prefer `0` together with `bin/console es:admin:index` in your deployment pipeline. +::: + Also, the CLI commands can be used as below: ```bash From 7b67480fb491da8df598b1e69f8fa6d277e03830 Mon Sep 17 00:00:00 2001 From: Vin Le Date: Fri, 21 Aug 2026 16:34:59 +0700 Subject: [PATCH 2/2] fix: grammar Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- .../hosting/infrastructure/elasticsearch/elasticsearch-setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/hosting/infrastructure/elasticsearch/elasticsearch-setup.md b/guides/hosting/infrastructure/elasticsearch/elasticsearch-setup.md index d6cabba1b7..fccc693521 100644 --- a/guides/hosting/infrastructure/elasticsearch/elasticsearch-setup.md +++ b/guides/hosting/infrastructure/elasticsearch/elasticsearch-setup.md @@ -207,7 +207,7 @@ SHOPWARE_ADMIN_ES_THROW_EXCEPTION=1 ``` ::: info -`SHOPWARE_ADMIN_ES_REFRESH_INDICES=1` makes Shopware create missing administration indices and aliases on the fly when an indexed entity is written, instead of relying on `bin/console es:admin:index`. Enable it in environments where nobody runs CLI commands after installing an extension or replacing the search cluster. It adds one alias check per indexer to every write, and an index created this way stays empty until a full reindex, so prefer `0` together with `bin/console es:admin:index` in your deployment pipeline. +`SHOPWARE_ADMIN_ES_REFRESH_INDICES=1` makes Shopware create missing administration indices and aliases on the fly when an indexed entity is written, instead of relying on `bin/console es:admin:index`. Enable it in environments where nobody runs CLI commands after installing an extension or replacing the search cluster. It adds one alias check per indexer on every write, and an index created this way stays empty until a full reindex, so prefer `0` together with `bin/console es:admin:index` in your deployment pipeline. ::: Also, the CLI commands can be used as below: