Skip to content

Reconcile OpenSearch test-doc stack assumptions (ES/Kibana vs real stack) #37292

Description

@jcastro-dotcms

Related to #37126 (where this was originally scoped and partially fixed) and PR #37258.

Description

docs/backend/OPENSEARCH_MIGRATION_TEST_PLAN.md and docs/backend/OPENSEARCH_MIGRATION_TESTER_GUIDE.md disagree with each other on what the default OpenSearch migration test environment actually is, and TEST_PLAN.md's assumed baseline stack doesn't exist anywhere in the repo.

Already fixed, no action needed: TEST_PLAN.md's "limited-user stack" section (3 of an originally-flagged 7 path occurrences) — it referenced a docker-compose.limited-user.yml file that doesn't exist; turned out every credential/port/script detail in that section already matched the real single-node-os-migration/docker-compose.yml exactly, so it was a wrong filename, not missing infra. Fixed in PR #37258, along with an unrelated service-name typo (opensearch-provision → real opensearch3-provision) found in that same section.

What's left — the actual inconsistency, still unresolved:

  • TEST_PLAN.md assumes its baseline/default stack is real Elasticsearch 7.10 + Kibana ("old engine") migrating to OpenSearch 3.x ("new engine") — referenced throughout as living at docker/docker-compose-examples/os-migration/.
  • TESTER_GUIDE.md treats OpenSearch 1.x → OpenSearch 3.x (docker/docker-compose-examples/single-node-os-migration/) as the primary, self-contained default stack, and describes the ES+Kibana stack as an optional second stack "if you specifically need real Elasticsearch" — one that, per TESTER_GUIDE.md itself, "does not include dotCMS or the database."
  • docker/docker-compose-examples/os-migration/ does not exist anywhere in the repo. Checked git history: the migration stack has been OpenSearch 1.x → 3.x since its very first commit ((docs) OpenSearch 1.x to 3.x migration docker-compose stack #35864, "OpenSearch 1.x to 3.x migration docker-compose stack"). There's no evidence a real ES+Kibana stack was ever built.
  • "ES 7.10" / "Kibana" appear ~20+ times in TEST_PLAN.md alone.

This was raised in the team's Slack channel for a decision (as of this ticket, still awaiting a reply): is the ES+Kibana stack still planned and just not built yet, or was it never meant to be separate infra — in which case TEST_PLAN.md should be rewritten around the real OpenSearch-only stack, matching what TESTER_GUIDE.md already does.

Acceptance Criteria

  • Get a decision from the team on Slack: build the missing docker/docker-compose-examples/os-migration/ ES+Kibana stack, or rewrite TEST_PLAN.md to use single-node-os-migration/ (OpenSearch 1.x) as its baseline like TESTER_GUIDE.md does
  • If rewriting to OpenSearch-only: update the ~20+ "ES 7.10"/"Kibana" mentions in TEST_PLAN.md, including the "Environment" table (old engine (ES 7.10), Kibana @ :5601) and every path reference to docker/docker-compose-examples/os-migration/docker-compose.yml (lines 23, 124, 250 — the remaining 3 of the original 7 flagged path occurrences, now that PR fix(docs): correct contradictions and fabricated APIs in backend AI-context docs #37258 fixed the other 4)
  • If rewriting to OpenSearch-only: rework the Kibana-specific steps in the following test cases so they use OpenSearch Dashboards instead: TC-001, TC-003, TC-012, TC-013, TC-019, TC-020, TC-022, TC-023, TC-025, TC-046
  • If rewriting to OpenSearch-only: update TESTER_GUIDE.md's "Elasticsearch variant" callout (lines 197-201) to stop pointing at a stack that won't exist, or remove it
  • If building the real ES+Kibana stack instead: create the actual docker/docker-compose-examples/os-migration/ compose stack matching what TEST_PLAN.md already describes (ES 7.10 + Kibana on :9200/:5601, OpenSearch 3.x + Dashboards on :9201/:5602), then verify every existing TEST_PLAN.md claim against it
  • Either way: make TEST_PLAN.md and TESTER_GUIDE.md agree on which stack is the default, so a reader doesn't get two different answers depending on which doc they open first

Priority

Medium

Additional Context

Full background and the original audit trail: #37126 (see its two M0-linked comments in #37125 for citations), and PR #37258 (the already-merged/fixed portion).

Activity

  1. jcastro-dotcms commented on Sep 16, 2026

    @jcastro-dotcms
    MemberAuthor

    QA: PASSED ✅

    After human review and assistance from Claude, the changes made to the docs are precise and adhere to the current infrastructure.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions