docs: compile ES→OpenSearch migration tester guide
@fabrizzio-dotCMS is already working on this.
Since Jul 27, 2026.
- Dominant language
- Java
- Stars
- 970
- Forks
- 486
- Avg merge
- 3d 33m
- Merged PRs (30d)
- 170
Description
Summary
Compile the existing ES → OpenSearch migration documentation into a single, tester-facing getting-started guide, and bring the two source docs it draws from into agreement with the current state of the migration.
The migration is close to end-to-end complete (Phase 3 included) and moving into broad QA, but the reference material was scattered across three internal docs (architecture, client configuration, test plan) written for engineers. This adds one entry point a customer/tester can follow from the outside — bring up the lab, understand the phases, exercise search and index endpoints — without reading source.
What was done
New: docs/backend/OPENSEARCH_MIGRATION_TESTER_GUIDE.md — a compilation/onboarding guide that distills the three existing docs into an observable, tester-oriented walkthrough:
- Objective and the four migration phases, in observable terms.
- Quickstart on the self-contained
single-node-os-migrationDocker stack (with the compose permalink as a starting point), services/ports/credentials, and how to get the files without a full checkout. - The configuration a tester actually touches, including the
.osindex-visibility role (OS_MIGRATION_INDEX_VISIBILITY_ROLE_KEY). - Verification helpers (list/count indices,
indiciestable, reading the phase, recognizing the automatic migration shutdown). - What to validate per phase, VTL viewTool regressions (
$estool/$sitesearch, aggregations, raw-Contentlet field shadowing), and the search / index-access REST endpoints. - Operational notes (Site Search crawl behavior, rollback/drift, restart-required on phase setup) and troubleshooting.
Updated for consistency with current behavior:
docs/backend/OPENSEARCH_MIGRATION.md— added a "restart required" note to Phase Transitions: the flag is live only for routing, but the one-time phase setup (validation, automatic shutdown, OS index bootstrap) runs only at startup.docs/backend/OPENSEARCH_MIGRATION_TEST_PLAN.md— updated the testable scope (all phases, including Phase 3, are now testable end-to-end), the same restart note, and corrected the verbatim automatic-shutdown log lines to match the code.
All claims were cross-checked against the codebase.
Scope / notes
- Documentation only — no code changes. QA not needed.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.