Copilot commented on code in PR #455: URL: https://github.com/apache/hugegraph-doc/pull/455#discussion_r2974933211
########## content/en/docs/guides/hugegraph-docker-cluster.md: ########## @@ -0,0 +1,133 @@ +cl--- Review Comment: The front matter delimiter at the top of this page is malformed (`cl---`), which will likely break the docs site generator (it expects `---`). Please replace it with the standard `---` opening delimiter. ```suggestion --- ``` ########## content/cn/docs/quickstart/hugegraph/hugegraph-server.md: ########## @@ -55,23 +55,23 @@ Core 模块是 Tinkerpop 接口的实现，Backend 模块用于管理数据存 </div> -另外，如果我们希望能够在一个文件中管理除了 `server` 之外的其他 Hugegraph 相关的实例，我们也可以使用 `docker-compose`完成部署，使用命令 `docker-compose up -d`，（当然只配置 `server` 也是可以的）以下是一个样例的 `docker-compose.yml`: +> **注意**：Docker compose 文件使用桥接网络（`hg-net`），适用于 Linux 和 Mac（Docker Desktop）。如需运行 3 节点分布式集群，请为 Docker Desktop 分配至少 **12 GB** 内存（设置 → 资源 → 内存）。 -```yaml -version: '3' -services: - server: - image: hugegraph/hugegraph:1.7.0 - container_name: server - environment: - - PASSWORD=xxx - # - PASSWORD=xxx 为可选参数，设置的时候可以开启鉴权模式，并设置密码 - # - PRELOAD=true - # - PRELOAD=true 为可选参数，为 True 时可以在启动的时候预加载一个内置的样例图 - ports: - - 8080:8080 +另外，如果我们希望能够在一个文件中管理 HugeGraph 相关的实例，可以使用 `docker compose` 完成部署。 +[`docker/`](https://github.com/apache/hugegraph/tree/master/docker) 目录下提供了两个 compose 文件： + +- **单节点快速启动**（预构建镜像）：`docker/docker-compose.yml` +- **单节点开发构建**（从源码构建）：`docker/docker-compose-dev.yml` + +```bash +cd docker Review Comment: 这里的 compose 快速启动使用了 `cd docker`，会默认读者当前目录下已经有 `docker/` 目录（即已在 HugeGraph 仓库根目录）。建议补充明确的前置步骤（例如先 `git clone ...` 再 `cd hugegraph/docker`），或说明此处假设已在仓库根目录执行。 ```suggestion git clone https://github.com/apache/hugegraph/hugegraph.git cd hugegraph/docker ``` ########## content/en/docs/quickstart/hugegraph/hugegraph-server.md: ########## @@ -617,7 +641,7 @@ In [3.1 Use Docker container](#31-use-docker-container-convenient-for-testdev), 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 Review Comment: This section now mixes `docker compose` (Compose v2) with `docker-compose` (legacy v1) commands. Given the doc also mentions Compose v2 elsewhere, this inconsistency can confuse users. Please either standardize on one form (preferably `docker compose`) or explicitly note that both work and when to use each. ########## content/en/docs/guides/hugegraph-docker-cluster.md: ########## @@ -0,0 +1,133 @@ +cl--- +title: "HugeGraph Docker Cluster Guide" +linkTitle: "Docker Cluster" +weight: 5 +--- + +## Overview + +HugeGraph supports running a full distributed cluster (PD + Store + Server) via Docker using bridge networking. This works on Linux and Mac (Docker Desktop). + +Previous versions used `network_mode: host` which only worked on Linux. The cluster now uses a Docker bridge network (`hg-net`) where services communicate via container hostnames instead of `127.0.0.1`. + +## Prerequisites + +- 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) + +> **Tested platforms**: Linux (native Docker) and macOS (Docker Desktop, tested on Apple M4). Windows Docker Desktop is untested. + +## Compose Files + +Three compose files are available in the [`docker/`](https://github.com/apache/hugegraph/tree/master/docker) directory: + +| File | Description | +|------|-------------| +| `docker-compose.yml` | Single-node quickstart using pre-built images | +| `docker-compose-dev.yml` | Single-node dev build from source | +| `docker-compose-3pd-3store-3server.yml` | 3-node distributed cluster | + +## Single-Node Quickstart + +```bash +cd hugegraph/docker +HUGEGRAPH_VERSION=1.7.0 docker compose up -d +``` + +Verify: +```bash +curl http://localhost:8080/versions +``` + +## 3-Node Cluster Quickstart + +```bash +cd hugegraph/docker +HUGEGRAPH_VERSION=1.7.0 docker compose -f docker-compose-3pd-3store-3server.yml up -d +``` + +Startup ordering is enforced automatically: +1. PD nodes start first and must pass `/v1/health` +2. Store nodes start after all PD nodes are healthy +3. Server nodes start after all Store nodes are healthy + +Verify the cluster: +```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 +``` + +## Environment Variable Reference + +### PD Variables + +| Variable | Required | Default | Maps To | +|----------|----------|---------|---------| +| `HG_PD_GRPC_HOST` | Yes | — | `grpc.host` | +| `HG_PD_RAFT_ADDRESS` | Yes | — | `raft.address` | +| `HG_PD_RAFT_PEERS_LIST` | Yes | — | `raft.peers-list` | +| `HG_PD_INITIAL_STORE_LIST` | Yes | — | `pd.initial-store-list` | +| `HG_PD_GRPC_PORT` | No | `8686` | `grpc.port` | +| `HG_PD_REST_PORT` | No | `8620` | `server.port` | +| `HG_PD_DATA_PATH` | No | `/hugegraph-pd/pd_data` | `pd.data-path` | +| `HG_PD_INITIAL_STORE_COUNT` | No | `1` | `pd.initial-store-count` | + +**Deprecated aliases**: `GRPC_HOST` → `HG_PD_GRPC_HOST`, `RAFT_ADDRESS` → `HG_PD_RAFT_ADDRESS`, `RAFT_PEERS` → `HG_PD_RAFT_PEERS_LIST` + +### Store Variables + +| Variable | Required | Default | Maps To | +|----------|----------|---------|---------| +| `HG_STORE_PD_ADDRESS` | Yes | — | `pdserver.address` | +| `HG_STORE_GRPC_HOST` | Yes | — | `grpc.host` | +| `HG_STORE_RAFT_ADDRESS` | Yes | — | `raft.address` | +| `HG_STORE_GRPC_PORT` | No | `8500` | `grpc.port` | +| `HG_STORE_REST_PORT` | No | `8520` | `server.port` | +| `HG_STORE_DATA_PATH` | No | `/hugegraph-store/storage` | `app.data-path` | + +**Deprecated aliases**: `PD_ADDRESS` → `HG_STORE_PD_ADDRESS`, `GRPC_HOST` → `HG_STORE_GRPC_HOST`, `RAFT_ADDRESS` → `HG_STORE_RAFT_ADDRESS` + +### Server Variables + +| Variable | Required | Default | Maps To | +|----------|----------|---------|---------| +| `HG_SERVER_BACKEND` | Yes | — | `backend` in `hugegraph.properties` | +| `HG_SERVER_PD_PEERS` | Yes | — | `pd.peers` | +| `STORE_REST` | No | — | used by `wait-partition.sh` | +| `PASSWORD` | No | — | enables auth mode | + +**Deprecated aliases**: `BACKEND` → `HG_SERVER_BACKEND`, `PD_PEERS` → `HG_SERVER_PD_PEERS` + +## Port Reference + +| Service | Host Port | Purpose | +|---------|-----------|---------| +| pd0 | 8620 | REST API | +| pd0 | 8686 | gRPC | +| pd1 | 8621 | REST API | +| pd1 | 8687 | gRPC | +| pd2 | 8622 | REST API | +| pd2 | 8688 | gRPC | +| store0 | 8500 | gRPC | +| store0 | 8520 | REST API | +| store1 | 8501 | gRPC | +| store1 | 8521 | REST API | +| store2 | 8502 | gRPC | +| store2 | 8522 | REST API | +| server0 | 8080 | Graph API | +| server1 | 8081 | Graph API | +| server2 | 8082 | Graph API | + +## Troubleshooting + +**Containers OOM killed (exit code 137)**: Increase Docker Desktop memory to 12 GB+. + +**Raft leader election timeout**: Check `HG_PD_RAFT_PEERS_LIST` is identical on all PD nodes. Verify connectivity: `docker exec hg-pd0 ping pd1` Review Comment: This troubleshooting example uses `docker exec hg-pd0 ...`, but earlier in the doc the container hostnames are `pd0/pd1/pd2`. If the container name differs from the hostname, this is confusing and the command may not work. Please align the exec target with the actual container name used by the compose file (or explicitly explain the naming, e.g. container name `hg-pd0` with hostname `pd0`). ```suggestion **Raft leader election timeout**: Check `HG_PD_RAFT_PEERS_LIST` is identical on all PD nodes. Verify connectivity: `docker exec pd0 ping pd1` ``` ########## content/en/docs/quickstart/hugegraph/hugegraph-server.md: ########## @@ -56,23 +56,23 @@ If you use docker desktop, you can set the option like: <img src="/docs/images/images-server/31docker-option.jpg" alt="image" style="width:33%;"> </div> -Also, if we want to manage the other Hugegraph related instances in one file, we can use `docker-compose` to deploy, with the command `docker-compose up -d` (you can config only `server`). Here is an example `docker-compose.yml`: +> **Note**: The Docker compose files use bridge networking (`hg-net`) and work on Linux and Mac (Docker Desktop). For the 3-node distributed cluster, allocate at least **12 GB** memory to Docker Desktop (Settings → Resources → Memory). -```yaml -version: '3' -services: - server: - image: hugegraph/hugegraph:1.7.0 - container_name: server - environment: - - PASSWORD=xxx - # PASSWORD is an option to enable auth mode with the password you set. - # - PRELOAD=true - # PRELOAD is a option to preload a build-in sample graph when initializing. - ports: - - 8080:8080 +Also, if we want to manage HugeGraph-related instances in one file, we can use `docker compose` to deploy. +Two compose files are available in the [`docker/`](https://github.com/apache/hugegraph/tree/master/docker) directory: + +- **Single-node quickstart** (pre-built images): `docker/docker-compose.yml` +- **Single-node dev build** (build from source): `docker/docker-compose-dev.yml` + +```bash +cd docker Review Comment: The Docker compose quickstart uses `cd docker`, which assumes the current working directory already contains a `docker/` folder. Elsewhere in the doc (and in the cluster quickstart) you use `cd hugegraph/docker`. Please make this step self-contained by showing the expected repo root (e.g. `git clone ...` then `cd hugegraph/docker`, or clarify that the user must already be in the HugeGraph repo root). ```suggestion # Clone HugeGraph (skip if you already have the repo) git clone https://github.com/apache/hugegraph.git cd hugegraph/docker ``` ########## content/en/docs/quickstart/hugegraph/hugegraph-server.md: ########## @@ -110,7 +110,6 @@ shasum -a 512 apache-hugegraph-incubating-src-{version}.tar.gz curl https://downloads.apache.org/hugegraph/{version}/apache-hugegraph-incubating-{version}-src.tar.gz.sha512 # Way2 : clone the latest code by git way (e.g GitHub) Review Comment: The source build instructions list “Way2: clone the latest code …” but the actual `git clone` command was removed, leaving this path incomplete. Please add back the clone command (or remove the Way2 bullet entirely) so the steps are runnable. ```suggestion # Way2 : clone the latest code by git way (e.g GitHub) git clone https://github.com/apache/incubator-hugegraph.git cd incubator-hugegraph ``` -- 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] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
