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

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

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

Verifying these changes

Trivial rework / code cleanup without any test coverage. (No Need)

Does this PR potentially affect the following parts?

Documentation Status

Doc - Done

- 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

Copilot

Pull request overview

This PR updates repository documentation to reflect a Docker deployment approach intended for bridge networking (Docker Desktop-friendly) and HG_* environment-variable based configuration, and consolidates Docker Compose references under the root docker/ directory.

Changes:

Added a new root-level docker/README.md with Docker Compose quickstart, 3-node cluster guidance, env-var reference tables, and troubleshooting.
Updated multiple component docs (PD/Store/Server + root README/AGENTS) to point to docker/ compose files and describe bridge-network deployment guidance.
Revised Store deployment guide examples/manifests to use HG_* env var names instead of older variables.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 23 comments.

Show a summary per file

File	Description
hugegraph-store/docs/deployment-guide.md	Replaces outdated compose/K8s env var examples with `HG_*`-style docs and new compose references
hugegraph-store/README.md	Updates `docker run` example and compose references
hugegraph-store/AGENTS.md	Updates compose example paths to `docker/`
hugegraph-server/hugegraph-dist/docker/README.md	Updates trace compose invocation and adds distributed cluster pointer to root `docker/`
hugegraph-pd/docs/configuration.md	Adds bridge-network notes and `HG_PD_GRPC_HOST` guidance
hugegraph-pd/README.md	Adds bridge-network env-var examples and updates `docker run` snippet
hugegraph-pd/AGENTS.md	Updates bridge-network guidance and compose references
docker/README.md	New comprehensive Docker deployment guide and env-var reference
README.md	Updates top-level Docker links to root `docker/` and adds Docker Desktop note
AGENTS.md	Updates compose example paths to `docker/`

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

Copilot · 2026-03-09T11:03:41Z

docker/README.md

+> [!WARNING]
+> **Temporary workaround — source clone currently required.** The `docker-compose.yml` (quickstart) and `docker-compose-3pd-3store-3server.yml` compose files currently mount entrypoint scripts directly from the source tree because the published Docker Hub images do not yet include the updated entrypoints. This means these compose files currently require a full repository clone to run. This requirement will be removed in a follow-up image release once updated images are published to Docker Hub with the new entrypoints baked in. The `docker-compose-dev.yml` (dev build) is unaffected since it builds images from source.
+


The warning says the compose files mount updated entrypoint scripts from the source tree, but in the current repo the compose files mount config files under docker/configs/ (e.g. ./configs/application-pd0.yml:/hugegraph-pd/conf/application.yml) and don’t reference entrypoint script mounts. Please adjust this text (or update the compose files) so the workaround description matches what users actually need to mount.

Copilot · 2026-03-09T11:03:42Z

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

 1. Start Open-Telemetry-Collector

    ```bash
-    cd hugegraph-server/hugegraph-dist/docker/example
-    docker-compose -f docker-compose-trace.yaml -p hugegraph-trace up -d
+    docker compose -f hugegraph-server/hugegraph-dist/docker/example/docker-compose-trace.yaml -p hugegraph-trace up -d
    ```


These commands use a relative path (hugegraph-server/hugegraph-dist/docker/example/docker-compose-trace.yaml) but no longer cd into the repo root or the example/ directory. Please add an explicit note that the command must be run from the repository root (or keep the cd step) to avoid copy/paste failures.

Copilot · 2026-03-09T11:03:42Z

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

 3. Stop Open-Telemetry-Collector

    ```bash
-    cd hugegraph-server/hugegraph-dist/docker/example
-    docker-compose -f docker-compose-trace.yaml -p hugegraph-trace stop
+    docker compose -f hugegraph-server/hugegraph-dist/docker/example/docker-compose-trace.yaml -p hugegraph-trace stop
    ```


Same issue as above: this assumes the current working directory makes hugegraph-server/hugegraph-dist/docker/example/docker-compose-trace.yaml resolvable. Please clarify the required working directory (or restore the prior cd instruction).

Copilot · 2026-03-09T11:03:42Z

hugegraph-store/README.md

 ### Build Docker Image

 From the project root:

 ```bash
 docker build -f hugegraph-store/Dockerfile -t hugegraph-store:latest .
 ```

 ### Run Container

 ```bash
 docker run -d \
  -p 8520:8520 \
  -p 8500:8500 \
  -p 8510:8510 \
-  -v /path/to/conf:/hugegraph-store/conf \
+  -e HG_STORE_PD_ADDRESS=<pd-ip>:8686 \
+  -e HG_STORE_GRPC_HOST=<your-ip> \
+  -e HG_STORE_RAFT_ADDRESS=<your-ip>:8510 \
  -v /path/to/storage:/hugegraph-store/storage \
-  -e PD_ADDRESS=192.168.1.10:8686,192.168.1.11:8686 \
  --name hugegraph-store \
-  hugegraph-store:latest
+  hugegraph/store:latest
 ```


In this Docker section, the build step tags the image as hugegraph-store:latest, but the subsequent docker run command uses hugegraph/store:latest (a different image name). Please make the build/run instructions consistent (either run hugegraph-store:latest after building locally, or change the build tag to match the hugegraph/store naming).

Copilot · 2026-03-09T11:03:42Z

hugegraph-pd/README.md

 Build PD Docker image:

 ```bash
 # From project root
 docker build -f hugegraph-pd/Dockerfile -t hugegraph-pd:latest .

 # Run container
 docker run -d \
  -p 8620:8620 \
  -p 8686:8686 \
  -p 8610:8610 \
-  -v /path/to/conf:/hugegraph-pd/conf \
+  -e HG_PD_GRPC_HOST=<your-ip> \
+  -e HG_PD_RAFT_ADDRESS=<your-ip>:8610 \
+  -e HG_PD_RAFT_PEERS_LIST=<your-ip>:8610 \
+  -e HG_PD_INITIAL_STORE_LIST=<store-ip>:8500 \
  -v /path/to/data:/hugegraph-pd/pd_data \
  --name hugegraph-pd \
-  hugegraph-pd:latest
+  hugegraph/pd:latest
 ```


The build command tags the image as hugegraph-pd:latest, but the docker run example uses hugegraph/pd:latest. Please align these so users who follow the build step can run the image they just built (or clearly separate "run pre-built image" vs "run locally built image").

Copilot · 2026-03-09T11:03:45Z

hugegraph-store/docs/deployment-guide.md

+        - name: HG_STORE_PD_ADDRESS
          value: "hugegraph-pd-0.hugegraph-pd:8686,hugegraph-pd-1.hugegraph-pd:8686,hugegraph-pd-2.hugegraph-pd:8686"
-        - name: GRPC_HOST
+        - name: HG_STORE_GRPC_HOST
          value: "$(POD_NAME).hugegraph-store"
-        - name: RAFT_ADDRESS
+        - name: HG_STORE_RAFT_ADDRESS


The Kubernetes manifest switches to HG_STORE_* env var names here, but the Store code/entrypoint in this repo doesn’t currently consume HG_STORE_ variables. If the runtime still expects the original env var names (or config file mounts), this change will break the manifest; please verify and update the manifest/docs to match the actually supported configuration mechanism.

Copilot · 2026-03-09T11:03:45Z

docker/README.md

+## Environment Variable Reference
+
+Configuration is injected via environment variables. The old `docker/configs/application-pd*.yml` and `docker/configs/application-store*.yml` files are no longer used.
+
+### PD Environment Variables


This section claims configuration is injected via HG_* env vars, but the current docker entrypoints in this repo (e.g. hugegraph-pd/hg-pd-dist/docker/docker-entrypoint.sh, hugegraph-store/hg-store-dist/docker/docker-entrypoint.sh, hugegraph-server/hugegraph-dist/docker/docker-entrypoint.sh) don’t read HG_* variables and just start the services. Please update the docs to match the current images/entrypoints, or include the corresponding entrypoint changes that implement HG_* injection.

Copilot · 2026-03-09T11:03:46Z

hugegraph-pd/docs/configuration.md

 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `grpc.host` | String | `127.0.0.1` | **IMPORTANT**: Must be set to actual IP address (not `127.0.0.1`) for distributed deployments. Store and Server nodes connect to this address. |
+| `grpc.host` | String | `127.0.0.1` | **IMPORTANT**: Must be set to actual IP address (not `127.0.0.1`) for distributed deployments. Store and Server nodes connect to this address. In Docker bridge networking, set this to the container hostname (e.g., `pd0`) via `HG_PD_GRPC_HOST` env var. |


This mentions setting grpc.host via HG_PD_GRPC_HOST, but there’s no support for HG_PD_ env vars in the current PD code/entrypoint. Please either document the env var name Spring actually binds to (e.g. GRPC_HOST) or include the entrypoint logic that maps HG_PD_GRPC_HOST to the PD config.

Copilot · 2026-03-09T11:03:46Z

docker/README.md

+**Deprecated aliases** (still work but log a warning):
+
+| Deprecated | Use Instead |
+|------------|-------------|
+| `GRPC_HOST` | `HG_PD_GRPC_HOST` |
+| `RAFT_ADDRESS` | `HG_PD_RAFT_ADDRESS` |
+| `RAFT_PEERS` | `HG_PD_RAFT_PEERS_LIST` |
+| `PD_INITIAL_STORE_LIST` | `HG_PD_INITIAL_STORE_LIST` |
+


These tables claim the deprecated env var aliases “still work but log a warning”, but there’s no deprecation/alias handling in the current docker entrypoint scripts in this repo (they don’t parse env vars at all). Please remove the warning claim or update it to match the actual behavior implemented by the images.

Copilot · 2026-03-09T11:03:46Z

hugegraph-store/docs/deployment-guide.md

+2. Store nodes start after all PD nodes are healthy
+3. Server nodes start after all Store nodes are healthy
+
+> **Note**: The deprecated env var names (`GRPC_HOST`, `RAFT_ADDRESS`, `RAFT_PEERS`, `PD_ADDRESS`, `BACKEND`, `PD_PEERS`) still work but log a warning. Use the `HG_*` prefixed names for new deployments.


This note says the deprecated env var names “still work but log a warning”. In the current repo, the docker entrypoints don’t implement alias migration/warnings, so this is likely inaccurate. Please either document the real compatibility behavior or drop the warning claim.

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

Copilot AI reviewed Mar 9, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: update Docker deployment docs for bridge networking migration#2963

docs: update Docker deployment docs for bridge networking migration#2963
bitflicker64 wants to merge 3 commits intoapache:masterfrom
bitflicker64:docs/docker-bridge-network

bitflicker64 commented Mar 7, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 9, 2026

Uh oh!

Copilot AI Mar 9, 2026

Uh oh!

Copilot AI Mar 9, 2026

Uh oh!

Copilot AI Mar 9, 2026

Uh oh!

Copilot AI Mar 9, 2026

Uh oh!

Copilot AI Mar 9, 2026

Uh oh!

Copilot AI Mar 9, 2026

Uh oh!

Copilot AI Mar 9, 2026

Uh oh!

Copilot AI Mar 9, 2026

Uh oh!

Copilot AI Mar 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		> [!WARNING]
		> Temporary workaround — source clone currently required. The `docker-compose.yml` (quickstart) and `docker-compose-3pd-3store-3server.yml` compose files currently mount entrypoint scripts directly from the source tree because the published Docker Hub images do not yet include the updated entrypoints. This means these compose files currently require a full repository clone to run. This requirement will be removed in a follow-up image release once updated images are published to Docker Hub with the new entrypoints baked in. The `docker-compose-dev.yml` (dev build) is unaffected since it builds images from source.

Conversation

bitflicker64 commented Mar 7, 2026

Purpose of the PR

Main Changes

Verifying these changes

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!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants