docs(server): add Docker with HBase validation runbook by vaijosh · Pull Request #3041 · apache/hugegraph

vaijosh · 2026-05-26T13:28:20Z

Description

While investigating issue #3030, the underlying bug could not be directly reproduced on the current master branch. However, during the investigation, I identified several improvements for docker/hbase/README.md that will be useful for verifying HBase-related issues in the future.

Specifically, this PR splits the local verification process into two clear paths (Standalone vs. Fully Containerized). It also enhances the HBase Docker artifacts by making hbase.master.hostname and hbase.regionserver.hostname fully configurable via environment variables.

Main Changes

1. Documentation Updates (`docker/hbase/README.md`)

Dual-Path Quick Start: Restructured the guide into two explicit validation paths:
- Option 1: Standalone HugeGraph engine backed by Dockerized HBase.
- Option 2: Fully containerized setup (Docker HugeGraph + Docker HBase) using a shared network.
Automated Setup Snippets: Added programmatic perl scripts to dynamically swap backend/serializer properties (rocksdb $\rightarrow$ hbase) and rewrite host configurations on the fly.
REST Verification Runbook: Checked in an explicit, end-to-end verification script utilizing the native /traversers/ REST APIs (kout, rays) to securely validate graph space persistence.
Troubleshooting Reference: Added a scannable table mapping common system errors (like UnknownHostException or port conflicts) directly to their respective resolutions.

2. Docker Environments (`docker/hbase/`)

Flexible Hostnames (docker-compose.hbase.yml): Replaced hardcoded hostnames with a configurable environment variable fallback (${HBASE_HOSTNAME:-hbase}).
Dynamic Property Injection (entrypoint.sh): Added a set_xml_property_value helper function inside the entrypoint sequence. This cleanly updates hbase.master.hostname and hbase.regionserver.hostname configurations inside hbase-site.xml at runtime based on the container environment.

Verifying of the issue

Verified the issue as follows

Verified issue ServerInfo is missing WARN floods logs continuously after startup with HBase backend #3030 using the updated setup runbook to ensure the environment is correctly configured.
Followed Option 1 by building the project locally (mvn clean package -DskipTests), initializing the store backend (init-store.sh), and running the sequential REST traversal scripts.
Followed Option 2 by building the hugegraph/server:dev target image and executing the one-shot store initializations inside an isolated container network.
Confirmed that the hugegraph-server logs were entirely clean of the targeted warnings during operation; specifically, no instances of the following log patterns were observed:

[WARN] o.a.h.t.ServerInfoManager - ServerInfo is missing: DEFAULT-aikg/server-1
[WARN] o.a.h.t.ServerInfoManager - ServerInfo is missing: DEFAULT-aikg/server-1, may be cleared before

Does this PR potentially affect the following parts?

Documentation Status

Doc - Done (The primary objective of this PR is introducing the HBase validation runbook docs)

…pache#3030) - improved `docker/hbase/README.md`. Added sections for "Standalone HugeGraph" and "Docker HugeGraph" and steps to verify the hbase backend -Used the steps in README.md file to verify the issue apache#3030. It its unreproducible in latest master branch.

Copilot

Pull request overview

Rewrites the docker/hbase/ HBase backend testing guide into a shorter dual-path runbook (standalone HugeGraph against Dockerized HBase, vs. fully containerized HugeGraph+HBase on a shared Docker network), and makes the HBase container's advertised hostname configurable so the same image works in both topologies. Originated from investigating issue #3030, which could not be reproduced on master; the underlying server change set is doc/operational only.

Changes:

Restructures docker/hbase/README.md around two explicit setup paths, adds REST traverser verification steps (/traversers/kout, /traversers/rays) and a troubleshooting table.
Adds HBASE_HOSTNAME/HBASE_MASTER_HOSTNAME/HBASE_REGIONSERVER_HOSTNAME env wiring in docker-compose.hbase.yml with a hbase fallback.
Adds a set_xml_property_value helper in entrypoint.sh that rewrites hbase.master.hostname and hbase.regionserver.hostname in hbase-site.xml at container start.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.

File	Description
docker/hbase/README.md	Replaces the long testing guide with a two-path runbook and adds REST verification + troubleshooting table.
docker/hbase/docker-compose.hbase.yml	Makes container hostname configurable and forwards HBase hostname env vars into the container.
docker/hbase/entrypoint.sh	Patches `hbase-site.xml` master/regionserver hostnames at runtime from env vars before starting daemons.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

imbajin

Found one runbook blocker in the standalone HugeGraph + Docker HBase path.

…pache#3030) -Addressed review comments.

Copilot

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

…pache#3030) -Addressed review comments by Copilot.

Copilot

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.

+escape_sed_replacement() {
+    printf '%s' "$1" | sed -e 's/[&|]/\\&/g'
+}


-## Manual Verification
+<details>
+<summary><b>Option 2: Docker HugeGraph (fully containerized)</b></summary>



+# 4) One-shot init-store
+docker rm -f hg-server-init >/dev/null 2>&1 || true
+docker run --rm --name hg-server-init \
+  --network "$HBASE_NETWORK" \
+  hugegraph/server:dev \
+  bash -lc '
+    set -euo pipefail
+    CONF=/hugegraph-server/conf/graphs/hugegraph.properties
+    perl -pi -e "s/^backend=.*/backend=hbase/" "$CONF"
+    perl -pi -e "s/^serializer=.*/serializer=hbase/" "$CONF"
+    perl -pi -e "s/^#(hbase\.hosts=.*)/\$1/" "$CONF"
+    perl -pi -e "s/^#(hbase\.port=.*)/\$1/" "$CONF"
+    perl -pi -e "s/^#(hbase\.znode_parent=.*)/\$1/" "$CONF"
+    perl -pi -e "s/^hbase\.hosts=.*/hbase.hosts=hbase/" "$CONF"
+    perl -pi -e "s/^hbase\.port=.*/hbase.port=2181/" "$CONF"
+    perl -pi -e "s|^hbase\.znode_parent=.*|hbase.znode_parent=/hbase|" "$CONF"
+    ./bin/init-store.sh
+  '


-# Initialize HBase tables (enter password 'pa' when prompted)
-printf 'pa\npa\n' | "$SERVER_DIR/bin/init-store.sh"
+Wipe any conflicting test records and data schema.



…pache#3030) -Addressed review comments by Copilot.

imbajin

Blocking: no. Summary: The cleanup command has a shell typo that prevents returning to the repository root. Evidence: bash -lc 'ROOT_DIR=$(mktemp -d); cd /; cd $"ROOT_DIR"' returns cd: ROOT_DIR: No such file or directory.

…pache#3030) -Addressed review comments by imbajin -Fixed other minor issues.

vaijosh · 2026-06-03T10:51:23Z

Blocking: no. Summary: The cleanup command has a shell typo that prevents returning to the repository root. Evidence: bash -lc 'ROOT_DIR=$(mktemp -d); cd /; cd $"ROOT_DIR"' returns cd: ROOT_DIR: No such file or directory.

Hi @imbajin ,
I have fixed this issue and some other minor issues in recent commit. I think its in better shape now. Thanks for your feedback.

codecov · 2026-06-03T11:38:59Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 0.07%. Comparing base (beb30ee) to head (ac7a9d8).
⚠️ Report is 2 commits behind head on master.

❗ There is a different number of reports uploaded between BASE (beb30ee) and HEAD (ac7a9d8). Click for more details.

HEAD has 2 uploads less than BASE

Flag BASE (beb30ee) HEAD (ac7a9d8)

3 1

Additional details and impacted files

@@             Coverage Diff              @@
##             master   #3041       +/-   ##
============================================
- Coverage     35.96%   0.07%   -35.89%     
+ Complexity      338      22      -316     
============================================
  Files           803     781       -22     
  Lines         68089   65574     -2515     
  Branches       8916    8468      -448     
============================================
- Hits          24489      51    -24438     
- Misses        40976   65521    +24545     
+ Partials       2624       2     -2622

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

imbajin

thanks for your contribution

vaijosh · 2026-06-03T13:19:28Z

Thanks @imbajin for reviewing and merging this PR.

dosubot Bot added the size:L This PR changes 100-499 lines, ignoring generated files. label May 26, 2026

imbajin requested a review from Copilot May 29, 2026 15:42

Copilot started reviewing on behalf of imbajin May 29, 2026 15:43 View session

Copilot AI reviewed May 29, 2026

View reviewed changes

Comment thread docker/hbase/README.md Outdated

Comment thread docker/hbase/README.md Outdated

Comment thread docker/hbase/README.md

Comment thread docker/hbase/entrypoint.sh

imbajin reviewed May 30, 2026

View reviewed changes

Comment thread docker/hbase/README.md

docs(hbase): add HugeGraph Docker + HBase validation runbook (issue a…

e1fb798

…pache#3030) -Addressed review comments.

dosubot Bot added size:XL This PR changes 500-999 lines, ignoring generated files. and removed size:L This PR changes 100-499 lines, ignoring generated files. labels Jun 1, 2026

docs(hbase): add HugeGraph Docker + HBase validation runbook (issue a…

d8b9d4e

…pache#3030) -Addressed review comments.

imbajin requested a review from Copilot June 2, 2026 04:44

Copilot started reviewing on behalf of imbajin June 2, 2026 04:44 View session

Copilot AI reviewed Jun 2, 2026

View reviewed changes

Comment thread docker/hbase/README.md Outdated

Comment thread docker/hbase/entrypoint.sh Outdated

docs(hbase): add HugeGraph Docker + HBase validation runbook (issue a…

0dc7e86

…pache#3030) -Addressed review comments by Copilot.

vaijosh requested review from Copilot and imbajin June 2, 2026 11:29

Copilot AI reviewed Jun 2, 2026

View reviewed changes

docs(hbase): add HugeGraph Docker + HBase validation runbook (issue a…

b61a2c1

…pache#3030) -Addressed review comments by Copilot.

imbajin reviewed Jun 2, 2026

View reviewed changes

Comment thread docker/hbase/README.md Outdated

docs(hbase): add HugeGraph Docker + HBase validation runbook (issue a…

04c5f6a

…pache#3030) -Addressed review comments by imbajin -Fixed other minor issues.

Merge branch 'apache:master' into 30300-ServerInfoMissing

ac7a9d8

imbajin approved these changes Jun 3, 2026

View reviewed changes

dosubot Bot added the lgtm This PR has been approved by a maintainer label Jun 3, 2026

imbajin changed the title ~~docs(hbase): add HugeGraph Docker + HBase validation runbook (issue #…3030)~~ docs(server): add Docker with HBase validation runbook Jun 3, 2026

imbajin merged commit a49bf66 into apache:master Jun 3, 2026
15 checks passed

Conversation

vaijosh commented May 26, 2026

Description

Main Changes

1. Documentation Updates (docker/hbase/README.md)

2. Docker Environments (docker/hbase/)

Verifying of the issue

Does this PR potentially affect the following parts?

Documentation Status

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

imbajin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

imbajin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

vaijosh commented Jun 3, 2026

Uh oh!

codecov Bot commented Jun 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

imbajin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

vaijosh commented Jun 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

1. Documentation Updates (`docker/hbase/README.md`)

2. Docker Environments (`docker/hbase/`)

codecov Bot commented Jun 3, 2026 •

edited

Loading