docs: update Docker deployment docs for bridge networking migration by bitflicker64 · Pull Request #2963 · apache/hugegraph

bitflicker64 · 2026-03-07T11:44:30Z

Purpose of the PR

follow up refactor(docker): migrate single-node compose from host to bridge networking #2952

Update all Docker deployment documentation to reflect the bridge networking migration from PR #2952. The old docs referenced a dead directory, used wrong environment variable names, and had no guidance for Docker Desktop users on Mac/Windows.

Main Changes

Create docker/README.md (new file) — comprehensive setup guide covering single-node and 3-node cluster, full HG_* env var reference tables for PD/Store/Server, port reference, health verification commands, troubleshooting (OOM, Raft, partitions), and a note about the temporary entrypoint mount workaround until updated images are published
Fix hugegraph-store/docs/deployment-guide.md — replace Docker Compose section that used completely wrong env var names (GRPC_HOST, RAFT_ADDRESS, RAFT_PEERS, PD_ADDRESS, BACKEND, PD_PEERS) with correct HG_* names; also fix K8s manifest env var names
Fix 7 files pointing to dead hugegraph-server/hugegraph-dist/docker/example/ directory — update to point to docker/ with correct file names (docker-compose.yml, docker-compose-dev.yml, docker-compose-3pd-3store-3server.yml)
Add Docker bridge network notes to hugegraph-pd/docs/configuration.md, hugegraph-pd/README.md, hugegraph-pd/AGENTS.md — clarify that grpc.host accepts container hostnames in bridge mode via HG_PD_GRPC_HOST
Add distributed cluster section to hugegraph-server/hugegraph-dist/docker/README.md
Update docker run examples in hugegraph-pd/README.md and hugegraph-store/README.md to use correct HG_* env var names

- Create docker/README.md with full setup guide, env var reference, port table, health checks, and troubleshooting - Fix hugegraph-store/docs/deployment-guide.md: replace wrong env vars (GRPC_HOST, RAFT_ADDRESS etc.) with correct HG_* names - Update K8s manifest in deployment-guide.md to use HG_* env vars - Fix 7 files pointing to dead docker/example/ directory - Add Docker bridge network notes to PD configuration docs - Add distributed cluster section to server Docker README Relates to: apache#2952

The 3-node and single-node quickstart compose files currently mount entrypoint scripts from source as a workaround until updated Docker images are published with the new entrypoints baked in. Add a clear note explaining this temporary requirement so users are not confused about needing a full source clone to run the cluster. Relates to: apache#2952

…el commands

hugegraph-pd/AGENTS.md

docker/README.md

imbajin · 2026-03-22T03:06:03Z

TODOs:

[Task] Improve Docker build cache efficiency for pd/store/server images #2977
image hugegraph/hugegraph should auto fwd to hugegraph/server if possible (same image?)
- currently, hugegraph/hugegraph used for standalone mode and server image for the dist mode
also need to update the README in the section https://github.com/apache/hugegraph#5-minutes-quick-start & https://github.com/apache/hugegraph#option-1-docker-fastest (for dist mode)
add info in https://github.com/apache/hugegraph/tree/master/hugegraph-server#readme
server image publish action should be replaced by pd/store/server (We also lack the Release action/tag for dist mode now, related PR refactor(workflows): consolidate pd-store-server publish flow hugegraph/actions#16)

…docker section

Copilot

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

README.md:181

The quick-start verification command uses curl http://localhost:8080/apis/version, but the server health/version endpoint in this repo is /versions (see VersionAPI and Docker healthchecks). Please update the README examples to use /versions so users don’t hit a 404 during verification.

# Start HugeGraph with Docker
docker run -itd --name=hugegraph -p 8080:8080 hugegraph/hugegraph:latest

# Verify server is running
curl http://localhost:8080/apis/version

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

Copilot · 2026-03-22T10:08:48Z

docker/README.md

+### Option A: Quick Start (pre-built images)
+
+Uses pre-built images from Docker Hub. Best for **end users** who want to run HugeGraph quickly.
+
+```bash
+cd docker
+docker compose up -d
+```
+
+- Images: `hugegraph/pd:latest`, `hugegraph/store:latest`, `hugegraph/server:latest`
+- `pull_policy: always` — always pulls the latest image
+- PD healthcheck endpoint: `/v1/health`
+- Single PD, single Store (`HG_PD_INITIAL_STORE_LIST: store:8500`), single Server
+- Server healthcheck endpoint: `/versions`
+


In “Option A: Quick Start (pre-built images)”, the docs imply the compose file works purely from Docker Hub images, but docker/docker-compose.yml currently relies on volume-mounting the new docker-entrypoint.sh scripts from the repository (see the ../hugegraph-*/.../docker-entrypoint.sh mounts). Please document this temporary workaround and that users must run compose from a checked-out repo until the images ship the updated entrypoints (or update the compose/docs to not require host mounts).

bitflicker64 · 2026-03-22T11:06:00Z

image hugegraph/hugegraph should auto fwd to hugegraph/server if possible (same image?)

currently, hugegraph/hugegraph used for standalone mode and server image for the dist mode

server image publish action should be replaced by pd/store/server (We also lack the Release action/tag for dist mode now)

Just wanted to confirm my understanding ,it looks like publish_latest_server_image.yml builds from Dockerfile (standalone) and publishes to hugegraph/hugegraph, but there's no automated workflow for Dockerfile-hstore → hugegraph/server. Is the goal to add that missing workflow and potentially consolidate the two images down the line?

imbajin · 2026-03-22T13:38:16Z

Just wanted to confirm my understanding ,it looks like publish_latest_server_image.yml builds from Dockerfile (standalone) and publishes to hugegraph/hugegraph, but there's no automated workflow for Dockerfile-hstore → hugegraph/server. Is the goal to add that missing workflow and potentially consolidate the two images down the line?

refer hugegraph/actions#16 & https://github.com/hugegraph/actions#core-design (I already refactored the ci flow), currently, we could build hugegraph/hugegraph & hugegraph/server + pd + store together

And also synced the latest & release ci flows (Update: already uploaded images like hugegraph/server:1.7.0, hugegraph/pd:1.7.0, hugegraph/store:1.7.0)

BTW, follow the ASF rules, we should use tag(1.x.x) rather than latest in doc by default (latest should be used in a test env)

bitflicker64 · 2026-03-22T21:55:01Z

And also synced the latest & release ci flows (Update: already uploaded images like hugegraph/server:1.7.0, hugegraph/pd:1.7.0, hugegraph/store:1.7.0)

BTW, follow the ASF rules, we should use tag(1.x.x) rather than latest in doc by default (latest should be used in a test env)

Thanks for the clarification! , I looked into the updated CI flow a bit and it makes sense now. I’ve aligned the docs with the current setup and switched to using the 1.7.0 tags.

Copilot

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated no new comments.

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

docker/README.md

hugegraph-pd/README.md

hugegraph-store/README.md

imbajin · 2026-03-23T02:19:20Z

hugegraph-server/hugegraph-dist/docker/README.md

maybe we should move related files out side of the legacy path (could do it in a separate PR)

BTW, a tracing system is important for the production env

got it, that makes sense , will keep this PR focused and handle those separately.

VGalaxies

A couple of doc consistency issues still look open to me before I’d approve:

The top-level README quick-start verification still uses curl http://localhost:8080/apis/version, but the actual endpoint is /versions, and the expected response shape there should be updated as well.
hugegraph-store/docs/deployment-guide.md still has a leftover hugegraph/hugegraph-store:1.7.0 image reference, while the rest of the updated Docker docs use hugegraph/store:1.7.0.
A few distributed compose examples still run without HUGEGRAPH_VERSION=1.7.0, so they still resolve to latest as written even though the docs now say release tags should be the default.

Once those are aligned, this looks close.

Documentation updates across README files to standardize Docker examples and reflect API changes. Replaced /apis/version with /versions and updated the example JSON response; prefixed docker compose invocations with HUGEGRAPH_VERSION=1.7.0; normalized image names/tags (e.g. hugegraph/pd:latest, hugegraph/hugegraph:1.7.0, hugegraph/store:1.7.0) and fixed build/run examples; clarified PRELOAD and OpenTelemetry wording; removed an outdated bridge networking note and made various wording/formatting improvements in multiple README files and the store deployment guide.

imbajin · 2026-03-23T07:53:56Z

Unify some desc & address comments in ea84dad

Copilot

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.

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

hugegraph-server/README.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

bitflicker64 · 2026-03-23T08:42:21Z

Unify some desc & address comments in ea84dad

Thanks for the cleanup! Let me know if there's anything else to address.

imbajin

Merge it first, we could enhance some desc later (like ↓)

and also the Linux machine doesn't need 12G RAM (only 3+3+3 dist mode may need more memory to preserve)

bitflicker64 · 2026-03-23T14:14:15Z

Merge it first, we could enhance some desc later (like ↓)

and also the Linux machine doesn't need 12G RAM (only 3+3+3 dist mode may need more memory to preserve)

Thanks for merging! Will clean up the duplicate links in README.md and clarify the 12 GB note (Linux native Docker doesn't need it, only the 3+3+3 distributed mode does) in a follow-up PR Later

bitflicker64 added 3 commits March 7, 2026 16:28

doc: fix PD healthcheck endpoint

8718611

imbajin requested a review from Copilot March 9, 2026 10:57

imbajin changed the title ~~Doc: update Docker deployment docs for bridge networking migration (#2952)~~ docs: update Docker deployment docs for bridge networking migration Mar 9, 2026

Copilot started reviewing on behalf of imbajin March 9, 2026 10:58 View session

This comment was marked as outdated.

Sign in to view

bitflicker64 mentioned this pull request Mar 18, 2026

refactor(docker): migrate single-node compose from host to bridge networking #2952

Merged

24 tasks

bitflicker64 added 3 commits March 22, 2026 00:18

Merge branch 'apache:master' into docs/docker-bridge-network

e6da3f6

docs: remove temporary entrypoint mount workaround note

5af0ab4

docs: fix relative paths and update docker compose v2 commands

a88e274

bitflicker64 requested a review from Copilot March 21, 2026 19:29

Copilot started reviewing on behalf of bitflicker64 March 21, 2026 19:30 View session

This comment was marked as outdated.

Sign in to view

docs: fix dev compose filename and add working directory notes for OT…

22b92b4

…el commands

bitflicker64 requested a review from Copilot March 21, 2026 19:49

Copilot started reviewing on behalf of bitflicker64 March 21, 2026 19:49 View session

This comment was marked as outdated.

Sign in to view

docs: fix relative path and add down -v note to docker README

a852cf5

bitflicker64 requested a review from Copilot March 21, 2026 20:05

Copilot started reviewing on behalf of bitflicker64 March 21, 2026 20:05 View session

This comment was marked as outdated.

Sign in to view

imbajin mentioned this pull request Mar 22, 2026

chore(docker): remove tmp volume mounts after image update #2976

Merged

7 tasks

imbajin requested review from Pengzna and VGalaxies March 22, 2026 02:59

imbajin reviewed Mar 22, 2026

View reviewed changes

hugegraph-pd/AGENTS.md Outdated Show resolved Hide resolved

imbajin reviewed Mar 22, 2026

View reviewed changes

docker/README.md Outdated Show resolved Hide resolved

docs: update docker examples to use latest tag and add server README …

d9cdf7d

…docker section

bitflicker64 requested a review from Copilot March 22, 2026 10:04

Copilot started reviewing on behalf of bitflicker64 March 22, 2026 10:04 View session

Copilot AI reviewed Mar 22, 2026

View reviewed changes

docs: use release tag (1.7.0) instead of latest for Docker images

39605ea

bitflicker64 requested a review from Copilot March 22, 2026 21:55

Copilot started reviewing on behalf of bitflicker64 March 22, 2026 21:55 View session

Copilot AI reviewed Mar 22, 2026

View reviewed changes

imbajin reviewed Mar 23, 2026

View reviewed changes

docker/README.md Outdated Show resolved Hide resolved

imbajin reviewed Mar 23, 2026

View reviewed changes

hugegraph-pd/README.md Outdated Show resolved Hide resolved

imbajin reviewed Mar 23, 2026

View reviewed changes

hugegraph-store/README.md Show resolved Hide resolved

imbajin reviewed Mar 23, 2026

View reviewed changes

docs: fix compose version pin, build/run tag consistency

d4cd290

VGalaxies reviewed Mar 23, 2026

View reviewed changes

imbajin requested a review from Copilot March 23, 2026 07:52

Copilot started reviewing on behalf of imbajin March 23, 2026 07:52 View session

Copilot AI reviewed Mar 23, 2026

View reviewed changes

hugegraph-server/README.md Outdated Show resolved Hide resolved

Update hugegraph-server/README.md

d632102

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

imbajin approved these changes Mar 23, 2026

View reviewed changes

imbajin merged commit 9126c80 into apache:master Mar 23, 2026
13 checks passed

Conversation

bitflicker64 commented Mar 7, 2026 • edited by imbajin Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Purpose of the PR

Main Changes

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

Uh oh!

Uh oh!

imbajin commented Mar 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

TODOs:

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Mar 22, 2026

Choose a reason for hiding this comment

Uh oh!

bitflicker64 commented Mar 22, 2026

Uh oh!

imbajin commented Mar 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bitflicker64 commented Mar 22, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

imbajin Mar 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bitflicker64 Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

VGalaxies left a comment

Choose a reason for hiding this comment

Uh oh!

imbajin commented Mar 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

bitflicker64 commented Mar 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

imbajin left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

bitflicker64 commented Mar 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

bitflicker64 commented Mar 7, 2026 •

edited by imbajin

Loading

imbajin commented Mar 22, 2026 •

edited

Loading

imbajin commented Mar 22, 2026 •

edited

Loading

imbajin Mar 23, 2026 •

edited

Loading

imbajin commented Mar 23, 2026 •

edited

Loading

bitflicker64 commented Mar 23, 2026 •

edited

Loading

imbajin left a comment •

edited

Loading