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

imbajin · 2026-03-08T02:11:24Z

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

+
+- Docker Engine 20.10+ or Docker Desktop 4.x+
+- Docker Compose v2
+- For the 3-node cluster: at least **12 GB** memory allocated to Docker Desktop (Settings → Resources → Memory)


maybe we need minimum the memory usage? (12G → 4G?)

PS: like 1~3 server + 3pd + 3 store is fine for a test?

During testing I hit OOM kills with 8GB in Docker Desktop which caused silent Raft failures so I bumped to 12GB and it worked, that's why I documented it. I haven't done any JVM heap tuning, containers are running with default settings. If the default heaps can be reduced for a test scenario that would help lower the requirement, happy to update the docs once we know a confirmed working lower limit.

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.

imbajin · 2026-03-23T13:05:14Z

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

@@ -1,4 +1,4 @@
---
+cl---


Copilot

Pull request overview

Adds missing documentation for running HugeGraph’s Docker-based distributed cluster (bridge networking), and updates existing deployment quickstarts to reference the new Docker/compose guidance introduced in apache/hugegraph#2952.

Changes:

Add new EN/CN “HugeGraph Docker Cluster Guide” pages with quickstarts, env var reference tables, ports, and troubleshooting.
Update EN/CN HugeGraph-Server quickstart Docker section to reference docker/ compose files and include a cluster quickstart.
Add Docker deployment sections (with HG_PD_* / HG_STORE_* env var tables) to the PD and Store quickstarts (EN/CN).

Reviewed changes

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

Show a summary per file

File	Description
content/en/docs/quickstart/hugegraph/hugegraph-server.md	Updates Docker links/compose guidance and adds a Docker cluster quickstart; removes inline compose example.
content/en/docs/quickstart/hugegraph/hugegraph-pd.md	Adds Docker deployment section and `HG_PD_*` env var reference.
content/en/docs/quickstart/hugegraph/hugegraph-hstore.md	Adds Docker deployment section and `HG_STORE_*` env var reference; adds Docker cluster quickstart notes.
content/en/docs/guides/hugegraph-docker-cluster.md	New EN standalone Docker cluster guide.
content/cn/docs/quickstart/hugegraph/hugegraph-server.md	CN mirror updates for Docker links/compose guidance plus cluster quickstart.
content/cn/docs/quickstart/hugegraph/hugegraph-pd.md	CN mirror Docker deployment section and env var reference.
content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md	CN mirror Docker deployment section and cluster quickstart notes.
content/cn/docs/guides/hugegraph-docker-cluster.md	New CN standalone Docker cluster guide.

Comments suppressed due to low confidence (2)

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

The “Compile from source” instructions mention cloning the repo, but the actual git clone command was removed. Please restore the clone step (or rewrite the section to clearly assume an existing working copy) so the build steps are complete.

```bash
# 1. Clone the source code

# 2. Build the project
cd hugegraph
mvn clean install -DskipTests=true

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

The “Compile from source” step says “# 1. Clone the source code” but no clone command is provided (it was removed), so the instructions can’t be followed as-is. Please add the appropriate git clone + cd steps or adjust the section text to match the intended workflow.

```bash
# 1. Clone the source code

# 2. Build the project
cd hugegraph
mvn clean install -DskipTests=true

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

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

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

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 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

@@ -38,7 +38,6 @@ cd apache-hugegraph-incubating-{version}/apache-hugegraph-pd-incubating-{version

 ```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

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

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

 When using Docker, we can use Cassandra as the backend storage. We highly recommend using docker-compose directly to manage both the server and Cassandra.

-The sample `docker-compose.yml` can be obtained on [GitHub](https://github.com/apache/hugegraph/blob/master/hugegraph-server/hugegraph-dist/docker/example/docker-compose-cassandra.yml), and you can start it with `docker-compose up -d`. (If using Cassandra 4.0 as the backend storage, it takes approximately two minutes to initialize. Please be patient.)
+The sample `docker-compose.yml` can be obtained on [GitHub](https://github.com/apache/hugegraph/blob/master/hugegraph-server/hugegraph-dist/docker/example/docker-compose-cassandra.yml), and you can start it with `HUGEGRAPH_VERSION=1.7.0 docker-compose up -d`. (If using Cassandra 4.0 as the backend storage, it takes approximately two minutes to initialize. Please be patient.)

 ```yaml


This section suggests starting the Cassandra compose with HUGEGRAPH_VERSION=1.7.0 ..., but the YAML shown below uses image: hugegraph/hugegraph (no ${HUGEGRAPH_VERSION} interpolation). As written, the env var won’t affect the compose run. Please either update the YAML to use ${HUGEGRAPH_VERSION} (or an explicit tag) or remove the HUGEGRAPH_VERSION=... prefix from the command.

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

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

+
+```bash
+cd docker
+docker compose up -d


中文文档这里直接使用 docker compose up -d，但英文版同一段落使用了 HUGEGRAPH_VERSION=1.7.0 docker compose up -d 来固定镜像版本。建议两种语言保持一致：要么都显式指定版本（推荐），要么都说明默认会使用哪个版本/标签。

Suggested change

docker compose up -d

HUGEGRAPH_VERSION=1.7.0 docker compose up -d

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

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

    ```

-    Use `docker-compose up -d` to start the container
+    Use `HUGEGRAPH_VERSION=1.7.0 docker-compose up -d` to start the container


In the PRELOAD docker-compose example, the YAML already pins image: hugegraph/hugegraph:1.7.0, so prefixing the startup command with HUGEGRAPH_VERSION=1.7.0 is misleading (it won’t change the image). Please remove the env var from the command or change the YAML to reference ${HUGEGRAPH_VERSION}.

Suggested change

Use `HUGEGRAPH_VERSION=1.7.0 docker-compose up -d` to start the container

Use `docker-compose up -d` to start the container

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

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

+
+## Single-Node Quickstart
+
+```bash


The quickstart assumes the compose files already exist locally (cd hugegraph/docker), but earlier the doc only links to the GitHub docker/ directory. Please add an explicit step to obtain those files (e.g., git clone https://github.com/apache/hugegraph.git or a download instruction) so the commands work from a clean machine.

Suggested change

```bash

```bash

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

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

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

+HugeGraph-Store Docker 镜像已发布在 Docker Hub，镜像名为 `hugegraph/store:latest`。
+
+使用 compose 文件部署完整的 3 节点集群（PD + Store + Server）：


这里示例使用 hugegraph/store:latest 会导致部署不可复现，且与英文文档使用固定版本标签（如 :1.7.0）不一致。建议改用明确的发布版本标签，或在文档中强调 latest 仅用于开发/体验用途。

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

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

@@ -39,7 +39,6 @@ cd apache-hugegraph-incubating-{version}/apache-hugegraph-hstore-incubating-{ver

 ```bash
 # 1. Clone the source code


In “3.2 Compile from source”, step 1 says “Clone the source code” but the actual git clone https://github.com/apache/hugegraph.git command is missing, making the subsequent cd hugegraph step invalid. Please restore the clone command or rewrite the steps accordingly.

Suggested change

# 1. Clone the source code

# 1. Clone the source code

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

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

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

+HugeGraph-PD Docker 镜像已发布在 Docker Hub，镜像名为 `hugegraph/pd:latest`。
+
+使用 compose 文件部署完整的 3 节点集群（PD + Store + Server）：


这里示例使用 hugegraph/pd:latest 会导致部署不可复现（不同时间拉取到的镜像内容可能不同），且与英文文档使用固定版本标签（如 :1.7.0）不一致。建议改用明确的发布版本标签，或至少说明 latest 仅用于体验开发版。

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

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

+
+**容器 OOM 被杀（退出码 137）**：将 Docker Desktop 内存增加到 12 GB 以上。
+
+**Raft 选举超时**：检查所有 PD 节点的 `HG_PD_RAFT_PEERS_LIST` 是否一致。验证连通性：`docker exec hg-pd0 ping pd1`


故障排查里使用了 docker exec hg-pd0 ping pd1，但文档没有说明容器名一定是 hg-pd0。为避免依赖 container_name 约定，建议改为 docker compose exec pd0 ping pd1，或在文档中明确 compose 文件中实际的容器名。

Suggested change

**Raft 选举超时**：检查所有 PD 节点的 `HG_PD_RAFT_PEERS_LIST` 是否一致。验证连通性：`docker exec hg-pd0 ping pd1`

**Raft 选举超时**：检查所有 PD 节点的 `HG_PD_RAFT_PEERS_LIST` 是否一致。验证连通性：`docker compose exec pd0 ping pd1`

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

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

24 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

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

Copilot AI reviewed Mar 23, 2026

View reviewed changes

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

		@@ -38,7 +38,6 @@ cd apache-hugegraph-incubating-{version}/apache-hugegraph-pd-incubating-{version

		```bash
		# 1. Clone the source code

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

	docker compose up -d
	HUGEGRAPH_VERSION=1.7.0 docker compose up -d

	Use `HUGEGRAPH_VERSION=1.7.0 docker-compose up -d` to start the container
	Use `docker-compose up -d` to start the container

		HugeGraph-Store Docker 镜像已发布在 Docker Hub，镜像名为 `hugegraph/store:latest`。

		使用 compose 文件部署完整的 3 节点集群（PD + Store + Server）：

		@@ -39,7 +39,6 @@ cd apache-hugegraph-incubating-{version}/apache-hugegraph-hstore-incubating-{ver

		```bash
		# 1. Clone the source code

		HugeGraph-PD Docker 镜像已发布在 Docker Hub，镜像名为 `hugegraph/pd:latest`。

		使用 compose 文件部署完整的 3 节点集群（PD + Store + Server）：


		容器 OOM 被杀（退出码 137）：将 Docker Desktop 内存增加到 12 GB 以上。

		Raft 选举超时：检查所有 PD 节点的 `HG_PD_RAFT_PEERS_LIST` 是否一致。验证连通性：`docker exec hg-pd0 ping pd1`

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!

imbajin Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

bitflicker64 Mar 8, 2026

Choose a reason for hiding this comment

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!

imbajin Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

bitflicker64 Mar 23, 2026

Choose a reason for hiding this comment

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!

Uh oh!

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!

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

bitflicker64 commented Mar 7, 2026 •

edited

Loading

imbajin commented Mar 8, 2026 •

edited

Loading