Copilot commented on code in PR #2963:
URL: https://github.com/apache/hugegraph/pull/2963#discussion_r2904715530
##########
hugegraph-server/hugegraph-dist/docker/README.md:
##########
@@ -105,12 +104,27 @@ If you want to customize the preloaded data, please mount
the groovy scripts (no
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
```
Review Comment:
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).
##########
hugegraph-server/hugegraph-dist/docker/README.md:
##########
@@ -92,8 +92,7 @@ If you want to customize the preloaded data, please mount the
groovy scripts (no
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
```
Review Comment:
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.
##########
docker/README.md:
##########
@@ -0,0 +1,259 @@
+# HugeGraph Docker Deployment
+
+This directory contains Docker Compose files for running HugeGraph:
+
+| File | Description |
+|------|-------------|
+| `docker-compose.yml` | Single-node cluster using pre-built images from
Docker Hub |
+| `docker-compose-dev.yml` | Single-node cluster built from source (for
developers) |
+| `docker-compose-3pd-3store-3server.yml` | 3-node distributed cluster (PD +
Store + Server) |
+
+## Prerequisites
+
+- **Docker Engine** 20.10+ (or Docker Desktop 4.x+)
+- **Docker Compose** v2 (included in Docker Desktop)
+- **Memory**: Allocate at least **12 GB** to Docker Desktop (Settings →
Resources → Memory). The 3-node cluster runs 9 JVM processes (3 PD + 3 Store +
3 Server) which are memory-intensive. Insufficient memory causes OOM kills that
appear as silent Raft failures.
+
+> [!IMPORTANT]
+> The 12 GB minimum is for Docker Desktop (Mac/Windows). On Linux with native
Docker, ensure the host has at least 12 GB of free memory.
+
+> [!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.
+
Review Comment:
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.
##########
hugegraph-pd/AGENTS.md:
##########
@@ -247,7 +247,7 @@ store:
### Common Configuration Errors
1. **Raft peer discovery failure**: `raft.peers-list` must include all PD
nodes' `raft.address` values
-2. **Store connection issues**: `grpc.host` must be a reachable IP (not
`127.0.0.1`) for distributed deployments
+2. **Store connection issues**: `grpc.host` must be a reachable IP (not
`127.0.0.1`) for distributed deployments. In Docker bridge networking, use the
container hostname (e.g., `pd0`) set via `HG_PD_GRPC_HOST` env var.
Review Comment:
This suggests using `HG_PD_GRPC_HOST` for Docker bridge networking, but the
current PD code/entrypoint in this repo doesn’t consume `HG_PD_` variables.
Please ensure the docs reference the env var names that are actually supported
by the published images (or land the entrypoint changes that implement
`HG_PD_*`).
##########
hugegraph-store/README.md:
##########
@@ -356,11 +356,12 @@ 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 \
Review Comment:
The run example sets `HG_STORE_*` environment variables, but there’s no
corresponding support for `HG_STORE_` variables in the current repo (no
references in code, and the Store docker entrypoint just starts the process).
Unless the image/entrypoint is updated, these env vars won’t affect
configuration; please document the supported mechanism (e.g. mounting
`application.yml`) or land the entrypoint changes together with this doc update.
##########
docker/README.md:
##########
@@ -0,0 +1,259 @@
+# HugeGraph Docker Deployment
+
+This directory contains Docker Compose files for running HugeGraph:
+
+| File | Description |
+|------|-------------|
+| `docker-compose.yml` | Single-node cluster using pre-built images from
Docker Hub |
+| `docker-compose-dev.yml` | Single-node cluster built from source (for
developers) |
+| `docker-compose-3pd-3store-3server.yml` | 3-node distributed cluster (PD +
Store + Server) |
+
+## Prerequisites
+
+- **Docker Engine** 20.10+ (or Docker Desktop 4.x+)
+- **Docker Compose** v2 (included in Docker Desktop)
+- **Memory**: Allocate at least **12 GB** to Docker Desktop (Settings →
Resources → Memory). The 3-node cluster runs 9 JVM processes (3 PD + 3 Store +
3 Server) which are memory-intensive. Insufficient memory causes OOM kills that
appear as silent Raft failures.
+
+> [!IMPORTANT]
+> The 12 GB minimum is for Docker Desktop (Mac/Windows). On Linux with native
Docker, ensure the host has at least 12 GB of free memory.
+
+> [!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.
+
+## Why Bridge Networking (Not Host Mode)
+
+Previous versions used `network_mode: host`, which only works on Linux and is
incompatible with Docker Desktop on Mac/Windows. The cluster now uses a proper
Docker bridge network (`hg-net`) where services communicate via container
hostnames (`pd0`, `pd1`, `store0`, etc.) instead of `127.0.0.1`. This makes the
cluster portable across all platforms.
+
Review Comment:
This section states the cluster now uses a bridge network (`hg-net`) and
container hostnames, but the current `docker/docker-compose.yml` and
`docker/docker-compose-3pd-3store-3server.yml` still configure `network_mode:
host`. Please align the documentation with the actual compose files (or update
the compose files in the same PR) to avoid misleading Docker Desktop users.
##########
hugegraph-store/AGENTS.md:
##########
@@ -129,7 +129,7 @@ bin/restart-hugegraph-store.sh
2. HugeGraph Store cluster (3+ nodes)
3. Proper configuration pointing Store nodes to PD cluster
-See Docker Compose example: `hugegraph-server/hugegraph-dist/docker/example/`
+See Docker Compose examples: `docker/` directory. Single-node quickstart
(pre-built images): `docker/docker-compose.yml`. Single-node dev build (from
source): `docker/docker-compose-dev.yml`. 3-node cluster:
`docker/docker-compose-3pd-3store-3server.yml`. See `docker/README.md` for full
setup guide.
Review Comment:
This line references `docker/docker-compose-dev.yml`, but that file isn’t
present under `docker/` in the repo. Please add it or adjust the listed
examples to only point at existing compose files.
##########
AGENTS.md:
##########
@@ -231,7 +231,7 @@ For distributed development:
3. Build Store: `mvn clean package -pl hugegraph-store -am -DskipTests`
4. Build Server with HStore backend: `mvn clean package -pl hugegraph-server
-am -DskipTests`
-See Docker Compose example: `hugegraph-server/hugegraph-dist/docker/example/`
+See Docker Compose examples: `docker/` directory. Single-node quickstart
(pre-built images): `docker/docker-compose.yml`. Single-node dev build (from
source): `docker/docker-compose-dev.yml`. 3-node cluster:
`docker/docker-compose-3pd-3store-3server.yml`. See `docker/README.md` for full
setup guide.
Review Comment:
This paragraph references `docker/docker-compose-dev.yml`, but the `docker/`
directory in the repo doesn’t contain that file. Please add the missing compose
file or update this guidance to only reference existing compose files.
##########
hugegraph-store/docs/deployment-guide.md:
##########
@@ -669,149 +669,59 @@ curl http://localhost:8080/versions
### Docker Compose: Complete Cluster
-File: `docker-compose.yml`
+For a production-like 3-node distributed deployment, use the compose file at
`docker/docker-compose-3pd-3store-3server.yml` in the repository root. See
[docker/README.md](../../../docker/README.md) for the full setup guide.
+
+> **Prerequisites**: Allocate at least **12 GB** memory to Docker Desktop
(Settings → Resources → Memory). The cluster runs 9 JVM processes.
+
+```bash
+cd docker
+docker compose -f docker-compose-3pd-3store-3server.yml up -d
+```
+
+The compose file uses a Docker bridge network (`hg-net`) with container
hostnames for service discovery. Configuration is injected via environment
variables using the `HG_*` prefix:
+
Review Comment:
This section documents the 3-node compose as using bridge networking
(`hg-net`) and env-var injection (`HG_*`), but the current
`docker/docker-compose-3pd-3store-3server.yml` still uses `network_mode: host`
and mounts `docker/configs/application-*.yml`. Please reconcile this doc with
the actual compose file shipped in the repo (or include the compose changes
this doc depends on).
##########
docker/README.md:
##########
@@ -0,0 +1,259 @@
+# HugeGraph Docker Deployment
+
+This directory contains Docker Compose files for running HugeGraph:
+
+| File | Description |
+|------|-------------|
+| `docker-compose.yml` | Single-node cluster using pre-built images from
Docker Hub |
+| `docker-compose-dev.yml` | Single-node cluster built from source (for
developers) |
+| `docker-compose-3pd-3store-3server.yml` | 3-node distributed cluster (PD +
Store + Server) |
+
+## Prerequisites
+
+- **Docker Engine** 20.10+ (or Docker Desktop 4.x+)
+- **Docker Compose** v2 (included in Docker Desktop)
+- **Memory**: Allocate at least **12 GB** to Docker Desktop (Settings →
Resources → Memory). The 3-node cluster runs 9 JVM processes (3 PD + 3 Store +
3 Server) which are memory-intensive. Insufficient memory causes OOM kills that
appear as silent Raft failures.
+
+> [!IMPORTANT]
+> The 12 GB minimum is for Docker Desktop (Mac/Windows). On Linux with native
Docker, ensure the host has at least 12 GB of free memory.
+
+> [!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.
+
+## Why Bridge Networking (Not Host Mode)
+
+Previous versions used `network_mode: host`, which only works on Linux and is
incompatible with Docker Desktop on Mac/Windows. The cluster now uses a proper
Docker bridge network (`hg-net`) where services communicate via container
hostnames (`pd0`, `pd1`, `store0`, etc.) instead of `127.0.0.1`. This makes the
cluster portable across all platforms.
+
+---
+
+## Single-Node Setup
+
+Two compose files are available for running a single-node cluster (1 PD + 1
Store + 1 Server):
+
+### 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: `/` (root)
+- Single PD, single Store (`HG_PD_INITIAL_STORE_LIST: store:8500`), single
Server
+- No `STORE_REST` or `wait-partition.sh` — simpler startup
+
+### Option B: Development Build (build from source)
+
+Builds images locally from source Dockerfiles. Best for **developers** who
want to test local changes.
+
+```bash
+cd docker
+docker compose -f docker-compose-dev.yml up -d
+```
+
+- Images: built from source via `build: context: ..` with Dockerfiles
+- No `pull_policy` — builds locally, doesn't pull
+- Entrypoint scripts are baked into the built image (no volume mounts)
+- PD healthcheck endpoint: `/v1/health`
+- Otherwise identical env vars and structure to the quickstart file
+
+### Key Differences
+
+| | `docker-compose.yml` (quickstart) | `docker-compose-dev.yml` (dev build) |
+|---|---|---|
+| **Images** | Pull from Docker Hub | Build from source |
+| **Who it's for** | End users | Developers |
+| **pull_policy** | `always` | not set (build) |
+
+**Verify** (both options):
+```bash
+curl http://localhost:8080/versions
+```
+
+---
+
+## 3-Node Cluster Quickstart
+
+```bash
+cd docker
+docker compose -f docker-compose-3pd-3store-3server.yml up -d
+```
+
+**Startup ordering** is enforced via `depends_on` with `condition:
service_healthy`:
+
+1. **PD nodes** start first and must pass healthchecks (`/v1/health`)
+2. **Store nodes** start after all PD nodes are healthy
+3. **Server nodes** start after all Store nodes are healthy
+
+This ensures Raft leader election and partition assignment complete before
dependent services attempt connections.
+
+**Verify the cluster is healthy**:
+
+```bash
+# Check PD health
+curl http://localhost:8620/v1/health
+
+# Check Store health
+curl http://localhost:8520/v1/health
+
+# Check Server (Graph API)
+curl http://localhost:8080/versions
+
+# List registered stores via PD
+curl http://localhost:8620/v1/stores
+
+# List partitions
+curl http://localhost:8620/v1/partitions
+```
+
+---
+
+## 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
+
+| Variable | Required | Default | Maps To (`application.yml`) | Description |
+|----------|----------|---------|-----------------------------|-------------|
+| `HG_PD_GRPC_HOST` | Yes | — | `grpc.host` | This node's hostname/IP for gRPC
|
+| `HG_PD_RAFT_ADDRESS` | Yes | — | `raft.address` | This node's Raft address
(e.g. `pd0:8610`) |
+| `HG_PD_RAFT_PEERS_LIST` | Yes | — | `raft.peers-list` | All PD peers (e.g.
`pd0:8610,pd1:8610,pd2:8610`) |
+| `HG_PD_INITIAL_STORE_LIST` | Yes | — | `pd.initial-store-list` | Expected
stores (e.g. `store0:8500,store1:8500,store2:8500`) |
+| `HG_PD_GRPC_PORT` | No | `8686` | `grpc.port` | gRPC server port |
+| `HG_PD_REST_PORT` | No | `8620` | `server.port` | REST API port |
+| `HG_PD_DATA_PATH` | No | `/hugegraph-pd/pd_data` | `pd.data-path` | Metadata
storage path |
+| `HG_PD_INITIAL_STORE_COUNT` | No | `1` | `pd.initial-store-count` | Min
stores for cluster availability |
+
+**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` |
+
Review Comment:
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.
##########
README.md:
##########
@@ -209,8 +209,11 @@ docker run -itd --name=hugegraph -e PASSWORD=your_password
-p 8080:8080 hugegrap
For advanced Docker configurations, see:
- [Docker
Documentation](https://hugegraph.apache.org/docs/quickstart/hugegraph-server/#3-deploy)
-- [Docker Compose Example](./hugegraph-server/hugegraph-dist/docker/example)
-- [Docker README](hugegraph-server/hugegraph-dist/docker/README.md)
+- [Docker Compose Examples](./docker/)
+- [Docker README](./docker/README.md)
+- [Server Docker README](hugegraph-server/hugegraph-dist/docker/README.md)
+
+> **Docker Desktop (Mac/Windows)**: The 3-node distributed cluster
(`docker/docker-compose-3pd-3store-3server.yml`) uses Docker bridge networking
and works on all platforms including Docker Desktop. Allocate at least 12 GB
memory to Docker Desktop.
Review Comment:
This note says the 3-node distributed cluster compose uses Docker bridge
networking and works on Docker Desktop, but the current
`docker/docker-compose-3pd-3store-3server.yml` still uses `network_mode: host`.
Please update this statement (or update the compose file) so the root README
doesn’t promise cross-platform behavior that the shipped compose file can’t
provide.
##########
hugegraph-store/README.md:
##########
@@ -356,11 +356,12 @@ 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
```
Review Comment:
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).
##########
hugegraph-pd/README.md:
##########
@@ -210,15 +240,18 @@ 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
```
Review Comment:
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").
##########
docker/README.md:
##########
@@ -0,0 +1,259 @@
+# HugeGraph Docker Deployment
+
+This directory contains Docker Compose files for running HugeGraph:
+
+| File | Description |
+|------|-------------|
+| `docker-compose.yml` | Single-node cluster using pre-built images from
Docker Hub |
+| `docker-compose-dev.yml` | Single-node cluster built from source (for
developers) |
+| `docker-compose-3pd-3store-3server.yml` | 3-node distributed cluster (PD +
Store + Server) |
Review Comment:
`docker-compose-dev.yml` is referenced in the file table, but it doesn't
exist under `docker/` in the repo. Either add the missing compose file or
remove/update these references so users don't follow a broken path.
##########
hugegraph-pd/docs/configuration.md:
##########
@@ -119,6 +119,31 @@ raft:
peers-list: 192.168.1.10:8610,192.168.1.11:8610,192.168.1.12:8610
```
+### Docker Bridge Network Deployment
+
+When deploying PD in Docker with bridge networking (e.g.,
`docker/docker-compose-3pd-3store-3server.yml`), container hostnames are used
instead of IP addresses. Configuration is injected via `HG_PD_*` environment
variables:
+
Review Comment:
This section references `docker/docker-compose-3pd-3store-3server.yml` as a
bridge-networking deployment, but in the current repo that compose file still
uses `network_mode: host`. Please adjust the wording (or update the compose
file) so readers don’t assume bridge networking is already in place.
##########
docker/README.md:
##########
@@ -0,0 +1,259 @@
+# HugeGraph Docker Deployment
+
+This directory contains Docker Compose files for running HugeGraph:
+
+| File | Description |
+|------|-------------|
+| `docker-compose.yml` | Single-node cluster using pre-built images from
Docker Hub |
+| `docker-compose-dev.yml` | Single-node cluster built from source (for
developers) |
+| `docker-compose-3pd-3store-3server.yml` | 3-node distributed cluster (PD +
Store + Server) |
+
+## Prerequisites
+
+- **Docker Engine** 20.10+ (or Docker Desktop 4.x+)
+- **Docker Compose** v2 (included in Docker Desktop)
+- **Memory**: Allocate at least **12 GB** to Docker Desktop (Settings →
Resources → Memory). The 3-node cluster runs 9 JVM processes (3 PD + 3 Store +
3 Server) which are memory-intensive. Insufficient memory causes OOM kills that
appear as silent Raft failures.
+
+> [!IMPORTANT]
+> The 12 GB minimum is for Docker Desktop (Mac/Windows). On Linux with native
Docker, ensure the host has at least 12 GB of free memory.
+
+> [!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.
+
+## Why Bridge Networking (Not Host Mode)
+
+Previous versions used `network_mode: host`, which only works on Linux and is
incompatible with Docker Desktop on Mac/Windows. The cluster now uses a proper
Docker bridge network (`hg-net`) where services communicate via container
hostnames (`pd0`, `pd1`, `store0`, etc.) instead of `127.0.0.1`. This makes the
cluster portable across all platforms.
+
+---
+
+## Single-Node Setup
+
+Two compose files are available for running a single-node cluster (1 PD + 1
Store + 1 Server):
+
+### 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: `/` (root)
+- Single PD, single Store (`HG_PD_INITIAL_STORE_LIST: store:8500`), single
Server
+- No `STORE_REST` or `wait-partition.sh` — simpler startup
+
+### Option B: Development Build (build from source)
+
+Builds images locally from source Dockerfiles. Best for **developers** who
want to test local changes.
+
+```bash
+cd docker
+docker compose -f docker-compose-dev.yml up -d
+```
+
+- Images: built from source via `build: context: ..` with Dockerfiles
+- No `pull_policy` — builds locally, doesn't pull
+- Entrypoint scripts are baked into the built image (no volume mounts)
+- PD healthcheck endpoint: `/v1/health`
+- Otherwise identical env vars and structure to the quickstart file
+
+### Key Differences
+
+| | `docker-compose.yml` (quickstart) | `docker-compose-dev.yml` (dev build) |
+|---|---|---|
+| **Images** | Pull from Docker Hub | Build from source |
+| **Who it's for** | End users | Developers |
+| **pull_policy** | `always` | not set (build) |
+
+**Verify** (both options):
+```bash
+curl http://localhost:8080/versions
+```
+
+---
+
+## 3-Node Cluster Quickstart
+
+```bash
+cd docker
+docker compose -f docker-compose-3pd-3store-3server.yml up -d
+```
+
+**Startup ordering** is enforced via `depends_on` with `condition:
service_healthy`:
+
+1. **PD nodes** start first and must pass healthchecks (`/v1/health`)
+2. **Store nodes** start after all PD nodes are healthy
+3. **Server nodes** start after all Store nodes are healthy
+
+This ensures Raft leader election and partition assignment complete before
dependent services attempt connections.
+
+**Verify the cluster is healthy**:
+
+```bash
+# Check PD health
+curl http://localhost:8620/v1/health
+
+# Check Store health
+curl http://localhost:8520/v1/health
+
+# Check Server (Graph API)
+curl http://localhost:8080/versions
+
+# List registered stores via PD
+curl http://localhost:8620/v1/stores
+
+# List partitions
+curl http://localhost:8620/v1/partitions
+```
+
+---
+
+## 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
Review Comment:
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.
##########
hugegraph-pd/docs/configuration.md:
##########
@@ -119,6 +119,31 @@ raft:
peers-list: 192.168.1.10:8610,192.168.1.11:8610,192.168.1.12:8610
```
+### Docker Bridge Network Deployment
+
+When deploying PD in Docker with bridge networking (e.g.,
`docker/docker-compose-3pd-3store-3server.yml`), container hostnames are used
instead of IP addresses. Configuration is injected via `HG_PD_*` environment
variables:
+
+```yaml
+# pd0 — set via HG_PD_RAFT_ADDRESS and HG_PD_RAFT_PEERS_LIST env vars
+raft:
+ address: pd0:8610
+ peers-list: pd0:8610,pd1:8610,pd2:8610
+
+# pd1
+raft:
+ address: pd1:8610
+ peers-list: pd0:8610,pd1:8610,pd2:8610
+
+# pd2
+raft:
+ address: pd2:8610
+ peers-list: pd0:8610,pd1:8610,pd2:8610
+```
Review Comment:
The YAML example shows three separate `raft:` mappings in a single code
block; if copy/pasted, only the last one would take effect (and the snippet
isn’t valid as a single config). Consider splitting into separate per-node
snippets or using comments/headers to make it clear these are different nodes’
configs.
##########
hugegraph-store/docs/deployment-guide.md:
##########
@@ -669,149 +669,59 @@ curl http://localhost:8080/versions
### Docker Compose: Complete Cluster
-File: `docker-compose.yml`
+For a production-like 3-node distributed deployment, use the compose file at
`docker/docker-compose-3pd-3store-3server.yml` in the repository root. See
[docker/README.md](../../../docker/README.md) for the full setup guide.
+
+> **Prerequisites**: Allocate at least **12 GB** memory to Docker Desktop
(Settings → Resources → Memory). The cluster runs 9 JVM processes.
+
+```bash
+cd docker
+docker compose -f docker-compose-3pd-3store-3server.yml up -d
+```
+
+The compose file uses a Docker bridge network (`hg-net`) with container
hostnames for service discovery. Configuration is injected via environment
variables using the `HG_*` prefix:
+
+**PD environment variables** (per node):
Review Comment:
This claims configuration is injected via `HG_*` environment variables, but
the current docker entrypoints in the repo (PD/Store/Server) don’t read `HG_*`
variables and just start the processes. Please either keep the docs aligned
with the current config-mount approach, or include the entrypoint changes this
documentation depends on.
##########
hugegraph-store/docs/deployment-guide.md:
##########
@@ -886,11 +796,11 @@ spec:
valueFrom:
fieldRef:
fieldPath: metadata.name
- - name: PD_ADDRESS
+ - 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
Review Comment:
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.
##########
hugegraph-pd/README.md:
##########
@@ -154,6 +154,36 @@ raft:
For detailed configuration options and production tuning, see [Configuration
Guide](docs/configuration.md).
+#### Docker Bridge Network Example
+
+When running PD in Docker with bridge networking (e.g.,
`docker/docker-compose-3pd-3store-3server.yml`), configuration is injected via
environment variables instead of editing `application.yml` directly. Container
hostnames are used instead of IP addresses:
+
Review Comment:
This section says PD configuration is injected via `HG_PD_*` environment
variables in Docker bridge mode, but the current
`hugegraph-pd/hg-pd-dist/docker/docker-entrypoint.sh` doesn’t process these env
vars (it just starts PD). Please adjust the doc to match the current image
behavior, or land the entrypoint changes that implement `HG_PD_*` parsing
alongside this doc update.
##########
docker/README.md:
##########
@@ -0,0 +1,259 @@
+# HugeGraph Docker Deployment
+
+This directory contains Docker Compose files for running HugeGraph:
+
+| File | Description |
+|------|-------------|
+| `docker-compose.yml` | Single-node cluster using pre-built images from
Docker Hub |
+| `docker-compose-dev.yml` | Single-node cluster built from source (for
developers) |
+| `docker-compose-3pd-3store-3server.yml` | 3-node distributed cluster (PD +
Store + Server) |
+
+## Prerequisites
+
+- **Docker Engine** 20.10+ (or Docker Desktop 4.x+)
+- **Docker Compose** v2 (included in Docker Desktop)
+- **Memory**: Allocate at least **12 GB** to Docker Desktop (Settings →
Resources → Memory). The 3-node cluster runs 9 JVM processes (3 PD + 3 Store +
3 Server) which are memory-intensive. Insufficient memory causes OOM kills that
appear as silent Raft failures.
+
+> [!IMPORTANT]
+> The 12 GB minimum is for Docker Desktop (Mac/Windows). On Linux with native
Docker, ensure the host has at least 12 GB of free memory.
+
+> [!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.
+
+## Why Bridge Networking (Not Host Mode)
+
+Previous versions used `network_mode: host`, which only works on Linux and is
incompatible with Docker Desktop on Mac/Windows. The cluster now uses a proper
Docker bridge network (`hg-net`) where services communicate via container
hostnames (`pd0`, `pd1`, `store0`, etc.) instead of `127.0.0.1`. This makes the
cluster portable across all platforms.
+
+---
+
+## Single-Node Setup
+
+Two compose files are available for running a single-node cluster (1 PD + 1
Store + 1 Server):
+
+### 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: `/` (root)
+- Single PD, single Store (`HG_PD_INITIAL_STORE_LIST: store:8500`), single
Server
+- No `STORE_REST` or `wait-partition.sh` — simpler startup
+
+### Option B: Development Build (build from source)
+
+Builds images locally from source Dockerfiles. Best for **developers** who
want to test local changes.
+
+```bash
+cd docker
+docker compose -f docker-compose-dev.yml up -d
+```
+
+- Images: built from source via `build: context: ..` with Dockerfiles
+- No `pull_policy` — builds locally, doesn't pull
+- Entrypoint scripts are baked into the built image (no volume mounts)
+- PD healthcheck endpoint: `/v1/health`
+- Otherwise identical env vars and structure to the quickstart file
+
+### Key Differences
+
+| | `docker-compose.yml` (quickstart) | `docker-compose-dev.yml` (dev build) |
+|---|---|---|
+| **Images** | Pull from Docker Hub | Build from source |
+| **Who it's for** | End users | Developers |
+| **pull_policy** | `always` | not set (build) |
+
+**Verify** (both options):
+```bash
+curl http://localhost:8080/versions
+```
+
+---
+
+## 3-Node Cluster Quickstart
+
+```bash
+cd docker
+docker compose -f docker-compose-3pd-3store-3server.yml up -d
+```
+
+**Startup ordering** is enforced via `depends_on` with `condition:
service_healthy`:
+
+1. **PD nodes** start first and must pass healthchecks (`/v1/health`)
+2. **Store nodes** start after all PD nodes are healthy
+3. **Server nodes** start after all Store nodes are healthy
+
+This ensures Raft leader election and partition assignment complete before
dependent services attempt connections.
+
+**Verify the cluster is healthy**:
+
+```bash
+# Check PD health
+curl http://localhost:8620/v1/health
+
+# Check Store health
+curl http://localhost:8520/v1/health
+
+# Check Server (Graph API)
+curl http://localhost:8080/versions
+
+# List registered stores via PD
+curl http://localhost:8620/v1/stores
+
+# List partitions
+curl http://localhost:8620/v1/partitions
+```
+
+---
+
+## 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.
+
Review Comment:
This states `docker/configs/application-pd*.yml` and
`docker/configs/application-store*.yml` are no longer used, but
`docker/docker-compose-3pd-3store-3server.yml` still mounts those files into
the PD/Store containers. Please correct the documentation or update the compose
files to actually stop using `docker/configs/`.
##########
hugegraph-pd/docs/configuration.md:
##########
@@ -53,7 +53,7 @@ grpc:
| 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. |
Review Comment:
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.
##########
hugegraph-store/docs/deployment-guide.md:
##########
@@ -669,149 +669,59 @@ curl http://localhost:8080/versions
### Docker Compose: Complete Cluster
-File: `docker-compose.yml`
+For a production-like 3-node distributed deployment, use the compose file at
`docker/docker-compose-3pd-3store-3server.yml` in the repository root. See
[docker/README.md](../../../docker/README.md) for the full setup guide.
+
+> **Prerequisites**: Allocate at least **12 GB** memory to Docker Desktop
(Settings → Resources → Memory). The cluster runs 9 JVM processes.
+
+```bash
+cd docker
+docker compose -f docker-compose-3pd-3store-3server.yml up -d
+```
+
+The compose file uses a Docker bridge network (`hg-net`) with container
hostnames for service discovery. Configuration is injected via environment
variables using the `HG_*` prefix:
+
+**PD environment variables** (per node):
+
+```yaml
+environment:
+ HG_PD_GRPC_HOST: pd0 # maps to grpc.host
+ HG_PD_GRPC_PORT: "8686" # maps to grpc.port
+ HG_PD_REST_PORT: "8620" # maps to server.port
+ HG_PD_RAFT_ADDRESS: pd0:8610 # maps to raft.address
+ HG_PD_RAFT_PEERS_LIST: pd0:8610,pd1:8610,pd2:8610 # maps to raft.peers-list
+ HG_PD_INITIAL_STORE_LIST: store0:8500,store1:8500,store2:8500 # maps to
pd.initial-store-list
+ HG_PD_DATA_PATH: /hugegraph-pd/pd_data # maps to pd.data-path
+ HG_PD_INITIAL_STORE_COUNT: 3 # maps to
pd.initial-store-count
+```
+
+**Store environment variables** (per node):
+
+```yaml
+environment:
+ HG_STORE_PD_ADDRESS: pd0:8686,pd1:8686,pd2:8686 # maps to
pdserver.address
+ HG_STORE_GRPC_HOST: store0 # maps to grpc.host
+ HG_STORE_GRPC_PORT: "8500" # maps to grpc.port
+ HG_STORE_REST_PORT: "8520" # maps to server.port
+ HG_STORE_RAFT_ADDRESS: store0:8510 # maps to raft.address
+ HG_STORE_DATA_PATH: /hugegraph-store/storage # maps to app.data-path
+```
+
+**Server environment variables**:
```yaml
-version: '3.8'
-
-services:
- # PD Cluster (3 nodes)
- pd1:
- image: hugegraph/hugegraph-pd:1.7.0
- container_name: hugegraph-pd1
- ports:
- - "8686:8686"
- - "8620:8620"
- - "8610:8610"
- environment:
- - GRPC_HOST=pd1
- - RAFT_ADDRESS=pd1:8610
- - RAFT_PEERS=pd1:8610,pd2:8610,pd3:8610
- networks:
- - hugegraph-net
-
- pd2:
- image: hugegraph/hugegraph-pd:1.7.0
- container_name: hugegraph-pd2
- ports:
- - "8687:8686"
- environment:
- - GRPC_HOST=pd2
- - RAFT_ADDRESS=pd2:8610
- - RAFT_PEERS=pd1:8610,pd2:8610,pd3:8610
- networks:
- - hugegraph-net
-
- pd3:
- image: hugegraph/hugegraph-pd:1.7.0
- container_name: hugegraph-pd3
- ports:
- - "8688:8686"
- environment:
- - GRPC_HOST=pd3
- - RAFT_ADDRESS=pd3:8610
- - RAFT_PEERS=pd1:8610,pd2:8610,pd3:8610
- networks:
- - hugegraph-net
-
- # Store Cluster (3 nodes)
- store1:
- image: hugegraph/hugegraph-store:1.7.0
- container_name: hugegraph-store1
- ports:
- - "8500:8500"
- - "8510:8510"
- - "8520:8520"
- environment:
- - PD_ADDRESS=pd1:8686,pd2:8686,pd3:8686
- - GRPC_HOST=store1
- - RAFT_ADDRESS=store1:8510
- volumes:
- - store1-data:/hugegraph-store/storage
- depends_on:
- - pd1
- - pd2
- - pd3
- networks:
- - hugegraph-net
-
- store2:
- image: hugegraph/hugegraph-store:1.7.0
- container_name: hugegraph-store2
- ports:
- - "8501:8500"
- environment:
- - PD_ADDRESS=pd1:8686,pd2:8686,pd3:8686
- - GRPC_HOST=store2
- - RAFT_ADDRESS=store2:8510
- volumes:
- - store2-data:/hugegraph-store/storage
- depends_on:
- - pd1
- - pd2
- - pd3
- networks:
- - hugegraph-net
-
- store3:
- image: hugegraph/hugegraph-store:1.7.0
- container_name: hugegraph-store3
- ports:
- - "8502:8500"
- environment:
- - PD_ADDRESS=pd1:8686,pd2:8686,pd3:8686
- - GRPC_HOST=store3
- - RAFT_ADDRESS=store3:8510
- volumes:
- - store3-data:/hugegraph-store/storage
- depends_on:
- - pd1
- - pd2
- - pd3
- networks:
- - hugegraph-net
-
- # Server (2 nodes)
- server1:
- image: hugegraph/hugegraph:1.7.0
- container_name: hugegraph-server1
- ports:
- - "8080:8080"
- environment:
- - BACKEND=hstore
- - PD_PEERS=pd1:8686,pd2:8686,pd3:8686
- depends_on:
- - store1
- - store2
- - store3
- networks:
- - hugegraph-net
-
- server2:
- image: hugegraph/hugegraph:1.7.0
- container_name: hugegraph-server2
- ports:
- - "8081:8080"
- environment:
- - BACKEND=hstore
- - PD_PEERS=pd1:8686,pd2:8686,pd3:8686
- depends_on:
- - store1
- - store2
- - store3
- networks:
- - hugegraph-net
-
-networks:
- hugegraph-net:
- driver: bridge
-
-volumes:
- store1-data:
- store2-data:
- store3-data:
+environment:
+ HG_SERVER_BACKEND: hstore # maps to backend
+ HG_SERVER_PD_PEERS: pd0:8686,pd1:8686,pd2:8686 # maps to pd.peers
+ STORE_REST: store0:8520 # used by
wait-partition.sh
```
+**Startup ordering** is enforced via `depends_on` with `condition:
service_healthy`:
+1. PD nodes start first and must pass healthchecks (`/v1/health`)
+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.
Review Comment:
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.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
