doc: add docker-compose guide and update deployment docs by bitflicker64 · Pull Request #455 · apache/hugegraph-doc

bitflicker64 · 2026-03-07T13:08:52Z

Purpose of the PR

Follow-up documentation update for apache/hugegraph#2952 which migrated Docker cluster setup from network_mode: host to Docker bridge networking.

Related PR: apache/hugegraph#2952

The doc repo had no wrong content — it simply never documented the Docker-based distributed cluster setup at all. This PR adds that missing documentation.

Main Changes

Create content/en/docs/guides/hugegraph-docker-cluster.md — new standalone Docker cluster guide covering single-node and 3-node setup, full HG_* env var reference tables, port reference, health checks, and troubleshooting
Create content/cn/docs/guides/hugegraph-docker-cluster.md — Chinese mirror
Update hugegraph-server.md (EN + CN) — fix Docker README URL, replace outdated inline compose yaml with references to new docker/ files, add 3-node cluster Docker quickstart inside section 5.1.1, add auth note
Update hugegraph-pd.md (EN + CN) — add section 3.3 Docker Deployment with HG_PD_* env var reference table
Update hugegraph-hstore.md (EN + CN) — add section 3.3 Docker Deployment with HG_STORE_* env var reference table, add section 6.3 Docker cluster quickstart

content/en/docs/guides/hugegraph-docker-cluster.md

imbajin · 2026-03-08T02:13:13Z

BTW, we could only update the EN version during the review-period, then sync the CN version in the final stage

…round

bitflicker64 · 2026-03-23T10:21:16Z

Updated all EN files pinned HUGEGRAPH_VERSION=1.7.0 on all compose commands, updated image references from :latest to 1.7.0, and removed the stale clone workaround notes. CN sync can be done in the final stage.

content/en/docs/guides/hugegraph-docker-cluster.md

Copilot

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 9 comments.

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

Copilot · 2026-03-25T04:45:45Z

content/en/docs/quickstart/hugegraph/hugegraph-pd.md

 #### 3.2 Compile from source

 ```bash
 # 1. Clone the source code


In “3.2 Compile from source”, step 1 says “Clone the source code” but the git clone https://github.com/apache/hugegraph.git command is missing, so the following cd hugegraph step can’t be followed as written. Please add the clone command back or adjust the steps.

Suggested change

# 1. Clone the source code

# 1. Clone the source code

git clone https://github.com/apache/hugegraph.git

content/en/docs/quickstart/hugegraph/hugegraph-server.md

content/cn/docs/quickstart/hugegraph/hugegraph-server.md

content/en/docs/quickstart/hugegraph/hugegraph-server.md

content/en/docs/guides/hugegraph-docker-cluster.md

content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md

content/en/docs/quickstart/hugegraph/hugegraph-hstore.md

content/cn/docs/quickstart/hugegraph/hugegraph-pd.md

content/cn/docs/guides/hugegraph-docker-cluster.md

imbajin · 2026-03-26T06:06:07Z

content/en/docs/quickstart/hugegraph/hugegraph-hstore.md

 #### 3.2 Compile from source

 ```bash
 # 1. Clone the source code


‼️ The source-build snippet says # 1. Clone the source code, but the actual git clone ... command was removed, so the later cd hugegraph and mvn ... steps are no longer runnable as written. Please restore the clone command or change the text to make the pre-cloned assumption explicit.

Suggested change

# 1. Clone the source code

git clone https://github.com/apache/hugegraph.git

content/en/docs/guides/hugegraph-docker-cluster.md

content/en/docs/quickstart/hugegraph/hugegraph-pd.md

content/en/docs/quickstart/hugegraph/hugegraph-server.md

imbajin · 2026-03-26T06:08:02Z

BTW, we could only update the EN version during the review-period, then sync the CN version in the final stage

Almost LGTM now, after all EN docs addressed comments, sync the CN doc together

…ctions, fix front matter typo

…git clone in source build

bitflicker64 · 2026-03-26T07:19:35Z

Synced all CN files to match EN pinned HUGEGRAPH_VERSION=1.7.0 on all compose commands, updated image references from :latest to 1.7.0, restored git clone in source build sections, and fixed docker-compose.dev.yml filename.

Copilot

Pull request overview

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

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

content/en/docs/quickstart/hugegraph/hugegraph-server.md

Copilot

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 15 comments.

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

content/cn/docs/quickstart/hugegraph/hugegraph-pd.md

content/en/docs/quickstart/hugegraph/hugegraph-hstore.md

content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md

content/en/docs/guides/hugegraph-docker-cluster.md

content/cn/docs/guides/hugegraph-docker-cluster.md

content/en/docs/quickstart/hugegraph/hugegraph-server.md

content/cn/docs/guides/hugegraph-docker-cluster.md

content/en/docs/guides/hugegraph-docker-cluster.md

content/cn/docs/quickstart/hugegraph/hugegraph-server.md

imbajin · 2026-04-05T02:24:35Z

I'll check the CN version ASAP

bitflicker64 · 2026-04-05T07:48:15Z

I'll check the CN version ASAP

EN files are all set, let me know if they look good and I'll sync the CN side.
edit - EN and CN are both synced now. Let me know if everything looks good

Revise Chinese and English docs for HugeGraph Docker deployment to standardize on Docker Compose wording and usage. Add notes that users should clone/pull the HugeGraph repo (or at least the docker/ directory), include a reminder to keep the HUGEGRAPH_VERSION aligned with releases, and adjust memory recommendations for Mac (3-node cluster ~12 GB) with platform guidance. Clarify compose file descriptions, emphasize container hostnames for HG_* env vars, change some example log years to 2026, reformat deprecated-alias lines, and number/troubleshooting items for clarity. Minor phrasing and section-title tweaks across hugegraph-docker-cluster.md, hugegraph-hstore.md, hugegraph-pd.md, and hugegraph-server.md (EN & CN). Signed-off-by: imbajin <jin@apache.org>

Copilot

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 13 comments.

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

content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md

content/cn/docs/quickstart/hugegraph/hugegraph-server.md

content/en/docs/guides/hugegraph-docker-cluster.md

content/cn/docs/guides/hugegraph-docker-cluster.md

content/en/docs/guides/hugegraph-docker-cluster.md

Copilot · 2026-04-07T11:54:49Z

content/en/docs/guides/hugegraph-docker-cluster.md

+1. PD nodes start first and must pass the `/v1/health` check
+2. Store nodes start only after all PD nodes are healthy
+3. Server nodes start last, after all PD and Store nodes are healthy
+
+Verify that the cluster is healthy:
+```bash
+curl http://localhost:8620/v1/health      # PD health
+curl http://localhost:8520/v1/health      # Store health
+curl http://localhost:8080/versions        # Server
+curl http://localhost:8620/v1/stores       # Registered stores
+curl http://localhost:8620/v1/partitions   # Partition assignment


This guide uses /v1/health for PD/Store health checks, but the existing quickstart docs for PD/Store verification use /actuator/health (e.g. content/en/docs/quickstart/hugegraph/hugegraph-pd.md:186 and hugegraph-hstore.md:270). Please clarify which endpoint is correct for Docker deployments (and/or document both) to avoid confusion.

Suggested change

1. PD nodes start first and must pass the `/v1/health` check

2. Store nodes start only after all PD nodes are healthy

3. Server nodes start last, after all PD and Store nodes are healthy

Verify that the cluster is healthy:

```bash

curl http://localhost:8620/v1/health # PD health

curl http://localhost:8520/v1/health # Store health

curl http://localhost:8080/versions # Server

curl http://localhost:8620/v1/stores # Registered stores

curl http://localhost:8620/v1/partitions # Partition assignment

1. PD nodes start first and must pass the Docker Compose health check (`/v1/health` in this guide)

2. Store nodes start only after all PD nodes are healthy

3. Server nodes start last, after all PD and Store nodes are healthy

> **Health endpoint note**: In the Docker Compose deployment documented here, PD and Store are checked via `/v1/health`. Some other HugeGraph quickstart documents use `/actuator/health` for PD/Store verification. If you are comparing guides or using a different image/version, verify which endpoint your deployment exposes; for the compose files in this guide, start with `/v1/health`.

Verify that the cluster is healthy:

```bash

curl http://localhost:8620/v1/health # PD health (Docker Compose in this guide)

curl http://localhost:8620/actuator/health # PD health (seen in some other docs/images)

curl http://localhost:8520/v1/health # Store health (Docker Compose in this guide)

curl http://localhost:8520/actuator/health # Store health (seen in some other docs/images)

curl http://localhost:8080/versions # Server

curl http://localhost:8620/v1/stores # Registered stores

curl http://localhost:8620/v1/partitions # Partition assignment

content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md

content/cn/docs/guides/hugegraph-docker-cluster.md

content/cn/docs/quickstart/hugegraph/hugegraph-pd.md

content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md

Cleanup and wording/formatting improvements across HugeGraph quickstart docs (CN/EN) for hugegraph-hstore, hugegraph-pd and hugegraph-server. Changes include: normalize “macOS” and Docker/Docker Hub terminology; clarify Java 11/JDK guidance and authentication requirements; rephrase HugeGraph-Server naming and startup/preload descriptions for clarity; update PD config comment for initial-store-count; add/standardize PD API curl example and expanded Store JSON example; improve Docker/Docker Compose examples (including mounting example.groovy and notes about Docker Desktop memory); fix punctuation, grammar and minor layout issues. Signed-off-by: imbajin <jin@apache.org>

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

Demote the "Docker Distributed Cluster" section heading from H4 to H6 in both English and Chinese quickstart pages to correct the document hierarchy and formatting (files updated: content/en/docs/quickstart/hugegraph/hugegraph-server.md and content/cn/docs/quickstart/hugegraph/hugegraph-server.md). Signed-off-by: imbajin <jin@apache.org>

Copilot

Pull request overview

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

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

content/en/docs/quickstart/hugegraph/hugegraph-pd.md

content/en/docs/quickstart/hugegraph/hugegraph-hstore.md

content/cn/docs/quickstart/hugegraph/hugegraph-pd.md

content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md

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

imbajin

Enhanced some desc & merge it now

Revise Chinese and English docs for HugeGraph Docker deployment to standardize on Docker Compose wording and usage. Add notes that users should clone/pull the HugeGraph repo (or at least the docker/ directory), include a reminder to keep the HUGEGRAPH_VERSION aligned with releases, and adjust memory recommendations for Mac (3-node cluster ~12 GB) with platform guidance. Clarify compose file descriptions, emphasize container hostnames for HG_* env vars, change some example log years to 2026, reformat deprecated-alias lines, and number/troubleshooting items for clarity. Minor phrasing and section-title tweaks across hugegraph-docker-cluster.md, hugegraph-hstore.md, hugegraph-pd.md, and hugegraph-server.md (EN & CN). --------- Signed-off-by: imbajin <jin@apache.org> Co-authored-by: imbajin <jin@apache.org> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> 1fda07c

bitflicker64 added 2 commits March 7, 2026 18:30

doc: add Docker bridge networking guide and update deployment docs

25a7086

doc: add PASSWORD auth note to Docker quickstart section

6b07431

imbajin reviewed Mar 8, 2026

View reviewed changes

content/en/docs/guides/hugegraph-docker-cluster.md Outdated Show resolved Hide resolved

imbajin changed the title ~~Doc: add Docker bridge networking guide and update deployment docs~~ doc: add docker-compose guide and update deployment docs Mar 8, 2026

bitflicker64 mentioned this pull request Mar 18, 2026

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

Merged

25 tasks

docs: pin HUGEGRAPH_VERSION, fix image tags, remove stale clone worka…

445988e

…round

bitflicker64 requested a review from imbajin March 23, 2026 10:29

imbajin reviewed Mar 23, 2026

View reviewed changes

content/en/docs/guides/hugegraph-docker-cluster.md Outdated Show resolved Hide resolved

imbajin requested review from Copilot and imbajin March 23, 2026 13:05

Copilot started reviewing on behalf of imbajin March 23, 2026 13:06 View session

This comment was marked as outdated.

Sign in to view

docs: fix front matter typo, restore Way2 clone command

42f7476

bitflicker64 requested a review from Copilot March 25, 2026 04:41

Copilot started reviewing on behalf of bitflicker64 March 25, 2026 04:42 View session

Copilot AI reviewed Mar 25, 2026

View reviewed changes

imbajin reviewed Mar 26, 2026

View reviewed changes

content/en/docs/guides/hugegraph-docker-cluster.md Outdated Show resolved Hide resolved

imbajin reviewed Mar 26, 2026

View reviewed changes

content/en/docs/quickstart/hugegraph/hugegraph-pd.md Show resolved Hide resolved

imbajin reviewed Mar 26, 2026

View reviewed changes

content/en/docs/quickstart/hugegraph/hugegraph-server.md Outdated Show resolved Hide resolved

bitflicker64 added 2 commits March 26, 2026 12:40

docs: fix compose filename typo, restore git clone in source build se…

8d30efa

…ctions, fix front matter typo

docs: sync CN files - pin HUGEGRAPH_VERSION, fix image tags, restore …

bf9de46

…git clone in source build

docs: restore git clone in CN source build sections

e970bbc

bitflicker64 requested a review from Copilot March 26, 2026 07:26

Copilot started reviewing on behalf of bitflicker64 March 26, 2026 07:27 View session

Copilot AI reviewed Mar 26, 2026

View reviewed changes

content/en/docs/quickstart/hugegraph/hugegraph-server.md Outdated Show resolved Hide resolved

docs: revert HUGEGRAPH_VERSION prefix from deprecated Cassandra section

989b639

bitflicker64 requested a review from Copilot March 26, 2026 08:15

Copilot started reviewing on behalf of bitflicker64 March 26, 2026 08:16 View session

bitflicker64 requested a review from imbajin March 26, 2026 08:16

Copilot AI reviewed Mar 26, 2026

View reviewed changes

imbajin requested a review from VGalaxies March 26, 2026 08:24

bitflicker64 mentioned this pull request Apr 5, 2026

[Bug] Docker setup broken on macOS/Windows — network_mode: host replaced with bridge networking (single-node + 3-node cluster) apache/hugegraph#2951

Closed

20 tasks

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

0ed1498

dosubot bot added the size:XL This PR changes 500-999 lines, ignoring generated files. label Apr 5, 2026

bitflicker64 added 2 commits April 5, 2026 13:04

docs: add docker logs tip to Docker deployment sections

ae63fce

docs: unify compose cd path to hugegraph/docker across all EN docs

d1fbee8

bitflicker64 and others added 2 commits April 5, 2026 13:23

docs: sync CN files with EN updates

d04a001

imbajin force-pushed the docs/hugegraph-doc-docker-bridge branch from 5a2373b to f454c8c Compare April 7, 2026 11:45

imbajin requested a review from Copilot April 7, 2026 11:49

Copilot started reviewing on behalf of imbajin April 7, 2026 11:49 View session

Copilot AI reviewed Apr 7, 2026

View reviewed changes

imbajin and others added 3 commits April 7, 2026 19:56

Apply suggestions from code review

fa53ee2

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

imbajin requested a review from Copilot April 7, 2026 12:17

Copilot started reviewing on behalf of imbajin April 7, 2026 12:18 View session

Copilot AI reviewed Apr 7, 2026

View reviewed changes

Apply suggestions from code review

9f45510

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

imbajin approved these changes Apr 7, 2026

View reviewed changes

dosubot bot added the lgtm This PR has been approved by a maintainer label Apr 7, 2026

imbajin merged commit 1fda07c into apache:master Apr 7, 2026
1 check passed

	# 1. Clone the source code
	# 1. Clone the source code
	git clone https://github.com/apache/hugegraph.git

Conversation

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

Uh oh!

Purpose of the PR

Main Changes

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

bitflicker64 commented Mar 23, 2026

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

imbajin Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

imbajin commented Mar 26, 2026

Uh oh!

bitflicker64 commented Mar 26, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

imbajin commented Apr 5, 2026

Uh oh!

bitflicker64 commented Apr 5, 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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bitflicker64 commented Mar 7, 2026 •

edited

Loading

imbajin commented Mar 8, 2026 •

edited

Loading

bitflicker64 commented Apr 5, 2026 •

edited

Loading