dotCMS / dotCMS/core

docs: compile ES→OpenSearch migration tester guide

Open
#36,734 1 comment 0 reactions 1 assignee View on GitHub

@fabrizzio-dotCMS is already working on this.

Since Jul 27, 2026.

QA : Not Needed Release : 26.07.27-01 Team : Scout Type : Documentation
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-migration Docker 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 .os index-visibility role (OS_MIGRATION_INDEX_VISIBILITY_ROLE_KEY).
  • Verification helpers (list/count indices, indicies table, 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.