docs(hosting): explain SHOPWARE_ADMIN_ES_REFRESH_INDICES and align its default - #2467
Open
Vin Le (vienthuong) wants to merge 3 commits into
Open
docs(hosting): explain SHOPWARE_ADMIN_ES_REFRESH_INDICES and align its default#2467Vin Le (vienthuong) wants to merge 3 commits into
Vin Le (vienthuong) wants to merge 3 commits into
Conversation
…s 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.
Developer Docs healthcheckStatus: Completed with |
Vin Le (vienthuong)
added
Guide
Vin Le (vienthuong)
requested review from
Micha Hobert (Isengo1989)
and
a lite review from Copilot
August 21, 2026 09:28
Vin Le (vienthuong)
marked this pull request as ready for review
August 21, 2026 09:28
Contributor
📢 Developer Announcement RecommendationRecommendation: ❌ No Announcement Recommended No developer announcement signals were detected.
|
Contributor
There was a problem hiding this comment.
Pull request overview
This PR improves Shopware hosting documentation by clarifying what SHOPWARE_ADMIN_ES_REFRESH_INDICES actually does and by adjusting the admin Elasticsearch/OpenSearch setup snippet to avoid enabling a costly behavior by default when copy-pasted.
Changes:
- Set
SHOPWARE_ADMIN_ES_REFRESH_INDICES=0in the admin search setup example and added an info callout explaining when=1is appropriate and what tradeoffs it has. - Replaced the environment-variable reference description with a behavior-focused explanation (including operational cost/caveat).
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| guides/hosting/infrastructure/elasticsearch/elasticsearch-setup.md | Aligns the setup snippet with a safer default and adds an info block explaining the flag’s behavior and implications. |
| guides/hosting/configurations/shopware/environment-variables.md | Improves the env-var reference entry to describe the real behavior and tradeoffs of SHOPWARE_ADMIN_ES_REFRESH_INDICES. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
SHOPWARE_ADMIN_ES_REFRESH_INDICESis documented in two places, and neither says what it does._refreshAPI. What it actually controls isAdminSearchRegistry::refreshIndices(): on every write of an indexed entity, indexers whose alias is missing get a fresh index + alias, and theiradmin_elasticsearch_index_taskrow is re-inserted. Replaced with a description of the behaviour, its cost, and its caveat, following the format already used by theSHOPWARE_ADMIN_ES_THROW_EXCEPTIONrow.1. That is the only line in the block diverging from the shipped default —SHOPWARE_ADMIN_ES_ENABLED=1is the switch you must flip, andINDEX_PREFIX/INDEXING_BATCH_SIZE/THROW_EXCEPTIONall match their defaults. So a copy-paste opted readers into anexistsAliascall per indexer (17 in core) on every admin write, plus the possibility of an empty index behind a live alias, without a word of explanation — whilebin/console es:admin:index, the thing that makes it unnecessary, is documented three lines below. Set to0and added an info block on when1is the right call.Related links
AdminSearchRegistry::refresh()/refreshIndices()"":elasticsearch.yaml0:EnvConfigWriter,SystemSetupCommandChecklist
PageRefreferences where relevant..gitbook.yamlif pages were moved, renamed, or deleted. — n/a, no pages moved.wordlist.txt(and sorted it) if spellcheck flags new legitimate terms. — n/a, "indexer"/"indexers" already appear in checked prose (flags-reference.md,extensibility-events-messages.md)Notes
One open question for a reviewer who knows the history. I could find no recorded reason for
=1in the setup guide — no->info()on the config node, no comment onrefreshIndices(), and the introducing commit (105501782f8, NEXT-21467) shipped no changelog line about the flag. I read=1as an oversight given the rest of the block, but if it was deliberate — e.g. for managed hosting where nobody runs CLI after installing an extension — then the value should stay1and only the info block should land. Happy to drop the value change and keep the prose.Left as a draft pending that confirmation.