diff --git a/content/cn/docs/guides/hugegraph-docker-cluster.md b/content/cn/docs/guides/hugegraph-docker-cluster.md new file mode 100644 index 000000000..a73e2208d --- /dev/null +++ b/content/cn/docs/guides/hugegraph-docker-cluster.md @@ -0,0 +1,135 @@ +--- +title: "HugeGraph Docker 集群部署指南" +linkTitle: "Docker 集群" +weight: 5 +--- + +## 概述 + +HugeGraph 支持通过 Docker 桥接网络运行完整的分布式集群（PD + Store + Server）。该方式适用于 Linux 和 Mac（Docker Desktop）。 + +早期版本使用 `network_mode: host`，仅在 Linux 上可用。集群现在使用 Docker 桥接网络（`hg-net`），服务通过容器主机名而非 `127.0.0.1` 进行通信。 + +## 前置条件 + +- Docker Engine 20.10+ 或 Docker Desktop 4.x+ +- Docker Compose v2 +- 3 节点集群需为 Docker Desktop 分配至少 **12 GB** 内存（设置 → 资源 → 内存） +- 本地克隆仓库（在更新后的镜像发布到 Docker Hub 之前的临时要求） + +> **已测试平台**：Linux（原生 Docker）和 macOS（Docker Desktop，已在 Apple M4 上测试）。Windows Docker Desktop 未经测试。 + +## Compose 文件 + +[`docker/`](https://github.com/apache/hugegraph/tree/master/docker) 目录下提供了三个 compose 文件： + +| 文件 | 描述 | +|------|------| +| `docker-compose.yml` | 使用预构建镜像的单节点快速启动 | +| `docker-compose-dev.yml` | 从源码构建的单节点开发模式 | +| `docker-compose-3pd-3store-3server.yml` | 3 节点分布式集群 | + +## 单节点快速启动 + +```bash +git clone https://github.com/apache/hugegraph.git +cd hugegraph/docker +docker compose up -d +``` + +验证： +```bash +curl http://localhost:8080/versions +``` + +## 3 节点集群快速启动 + +```bash +cd hugegraph/docker +docker compose -f docker-compose-3pd-3store-3server.yml up -d +``` + +启动顺序自动强制执行： +1. PD 节点首先启动，必须通过 `/v1/health` 健康检查 +2. Store 节点在所有 PD 节点健康后启动 +3. Server 节点在所有 Store 节点健康后启动 + +验证集群： +```bash +curl http://localhost:8620/v1/health # PD 健康检查 +curl http://localhost:8520/v1/health # Store 健康检查 +curl http://localhost:8080/versions # Server +curl http://localhost:8620/v1/stores # 已注册的 Store +curl http://localhost:8620/v1/partitions # 分区分配 +``` + +## 环境变量参考 + +### PD 变量 + +| 变量 | 必填 | 默认值 | 映射配置 | +|------|------|--------|----------| +| `HG_PD_GRPC_HOST` | 是 | — | `grpc.host` | +| `HG_PD_RAFT_ADDRESS` | 是 | — | `raft.address` | +| `HG_PD_RAFT_PEERS_LIST` | 是 | — | `raft.peers-list` | +| `HG_PD_INITIAL_STORE_LIST` | 是 | — | `pd.initial-store-list` | +| `HG_PD_GRPC_PORT` | 否 | `8686` | `grpc.port` | +| `HG_PD_REST_PORT` | 否 | `8620` | `server.port` | +| `HG_PD_DATA_PATH` | 否 | `/hugegraph-pd/pd_data` | `pd.data-path` | +| `HG_PD_INITIAL_STORE_COUNT` | 否 | `1` | `pd.initial-store-count` | + +**已弃用的别名**：`GRPC_HOST` → `HG_PD_GRPC_HOST`、`RAFT_ADDRESS` → `HG_PD_RAFT_ADDRESS`、`RAFT_PEERS` → `HG_PD_RAFT_PEERS_LIST` + +### Store 变量 + +| 变量 | 必填 | 默认值 | 映射配置 | +|------|------|--------|----------| +| `HG_STORE_PD_ADDRESS` | 是 | — | `pdserver.address` | +| `HG_STORE_GRPC_HOST` | 是 | — | `grpc.host` | +| `HG_STORE_RAFT_ADDRESS` | 是 | — | `raft.address` | +| `HG_STORE_GRPC_PORT` | 否 | `8500` | `grpc.port` | +| `HG_STORE_REST_PORT` | 否 | `8520` | `server.port` | +| `HG_STORE_DATA_PATH` | 否 | `/hugegraph-store/storage` | `app.data-path` | + +**已弃用的别名**：`PD_ADDRESS` → `HG_STORE_PD_ADDRESS`、`GRPC_HOST` → `HG_STORE_GRPC_HOST`、`RAFT_ADDRESS` → `HG_STORE_RAFT_ADDRESS` + +### Server 变量 + +| 变量 | 必填 | 默认值 | 映射配置 | +|------|------|--------|----------| +| `HG_SERVER_BACKEND` | 是 | — | `hugegraph.properties` 中的 `backend` | +| `HG_SERVER_PD_PEERS` | 是 | — | `pd.peers` | +| `STORE_REST` | 否 | — | `wait-partition.sh` 使用 | +| `PASSWORD` | 否 | — | 启用鉴权模式 | + +**已弃用的别名**：`BACKEND` → `HG_SERVER_BACKEND`、`PD_PEERS` → `HG_SERVER_PD_PEERS` + +## 端口参考 + +| 服务 | 宿主机端口 | 用途 | +|------|-----------|------| +| 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 | + +## 故障排查 + +**容器 OOM 被杀（退出码 137）**：将 Docker Desktop 内存增加到 12 GB 以上。 + +**Raft 选举超时**：检查所有 PD 节点的 `HG_PD_RAFT_PEERS_LIST` 是否一致。验证连通性：`docker exec hg-pd0 ping pd1` + +**分区分配未完成**：检查 `curl http://localhost:8620/v1/stores` — 所有 3 个 Store 必须显示 `"state":"Up"` 才能完成分区分配。 + +**连接被拒**：确保 `HG_*` 环境变量使用容器主机名（`pd0`、`store0`），而非 `127.0.0.1`。 diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md b/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md index 50d28d579..0447fadc3 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md @@ -50,6 +50,48 @@ mvn clean install -DskipTests=true # target/apache-hugegraph-incubating-{version}.tar.gz ``` +#### 3.3 Docker 部署 + +HugeGraph-Store Docker 镜像已发布在 Docker Hub，镜像名为 `hugegraph/store:latest`。 + +使用 compose 文件部署完整的 3 节点集群（PD + Store + Server）： + +```bash +git clone https://github.com/apache/hugegraph.git +cd hugegraph/docker +docker compose -f docker-compose-3pd-3store-3server.yml up -d +``` + +通过 `docker run` 运行单个 Store 节点： + +```bash +docker run -d \ + -p 8520:8520 \ + -p 8500:8500 \ + -p 8510:8510 \ + -e HG_STORE_PD_ADDRESS=:8686 \ + -e HG_STORE_GRPC_HOST= \ + -e HG_STORE_RAFT_ADDRESS=:8510 \ + -v /path/to/storage:/hugegraph-store/storage \ + --name hugegraph-store \ + hugegraph/store:latest +``` + +**环境变量参考：** + +| 变量 | 必填 | 默认值 | 描述 | +|------|------|--------|------| +| `HG_STORE_PD_ADDRESS` | 是 | — | PD gRPC 地址（如 `pd0:8686,pd1:8686,pd2:8686`） | +| `HG_STORE_GRPC_HOST` | 是 | — | 本节点的 gRPC 主机名/IP（如 `store0`） | +| `HG_STORE_RAFT_ADDRESS` | 是 | — | 本节点的 Raft 地址（如 `store0:8510`） | +| `HG_STORE_GRPC_PORT` | 否 | `8500` | gRPC 服务端口 | +| `HG_STORE_REST_PORT` | 否 | `8520` | REST API 端口 | +| `HG_STORE_DATA_PATH` | 否 | `/hugegraph-store/storage` | 数据存储路径 | + +> **注意**：在 Docker 桥接网络中，`HG_STORE_GRPC_HOST` 应使用容器主机名（如 `store0`）而非 IP 地址。 + +> **已弃用的别名**：`PD_ADDRESS`、`GRPC_HOST`、`RAFT_ADDRESS` 仍可使用，但会输出弃用警告。新部署请使用 `HG_STORE_*` 名称。 + ### 4 配置 Store 的主要配置文件为 `conf/application.yml`，以下是关键配置项： @@ -188,6 +230,34 @@ pdserver: address: 127.0.0.1:8686,127.0.0.1:8687,127.0.0.1:8688 ``` +#### 6.3 Docker 集群快速启动 + +3 节点 Store 集群包含在 `docker/docker-compose-3pd-3store-3server.yml` 中。每个 Store 节点拥有独立的主机名和环境变量： + +```yaml +# store0 +HG_STORE_PD_ADDRESS: pd0:8686,pd1:8686,pd2:8686 +HG_STORE_GRPC_HOST: store0 +HG_STORE_GRPC_PORT: "8500" +HG_STORE_REST_PORT: "8520" +HG_STORE_RAFT_ADDRESS: store0:8510 +HG_STORE_DATA_PATH: /hugegraph-store/storage + +# store1 +HG_STORE_PD_ADDRESS: pd0:8686,pd1:8686,pd2:8686 +HG_STORE_GRPC_HOST: store1 +HG_STORE_RAFT_ADDRESS: store1:8510 + +# store2 +HG_STORE_PD_ADDRESS: pd0:8686,pd1:8686,pd2:8686 +HG_STORE_GRPC_HOST: store2 +HG_STORE_RAFT_ADDRESS: store2:8510 +``` + +Store 节点仅在所有 PD 节点通过健康检查（`/v1/health`）后启动，通过 `depends_on: condition: service_healthy` 强制执行。 + +完整的部署指南请参阅 [docker/README.md](https://github.com/apache/hugegraph/blob/master/docker/README.md)。 + ### 7 验证 Store 服务 确认 Store 服务是否正常运行： diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md b/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md index 46d70c32f..5beba9065 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md @@ -49,6 +49,53 @@ mvn clean install -DskipTests=true # target/apache-hugegraph-incubating-{version}.tar.gz ``` +#### 3.3 Docker 部署 + +HugeGraph-PD Docker 镜像已发布在 Docker Hub，镜像名为 `hugegraph/pd:latest`。 + +使用 compose 文件部署完整的 3 节点集群（PD + Store + Server）： + +```bash +git clone https://github.com/apache/hugegraph.git +cd hugegraph/docker +docker compose -f docker-compose-3pd-3store-3server.yml up -d +``` + +通过 `docker run` 运行单个 PD 节点时，通过环境变量提供配置： + +```bash +docker run -d \ + -p 8620:8620 \ + -p 8686:8686 \ + -p 8610:8610 \ + -e HG_PD_GRPC_HOST= \ + -e HG_PD_RAFT_ADDRESS=:8610 \ + -e HG_PD_RAFT_PEERS_LIST=:8610 \ + -e HG_PD_INITIAL_STORE_LIST=:8500 \ + -v /path/to/data:/hugegraph-pd/pd_data \ + --name hugegraph-pd \ + hugegraph/pd:latest +``` + +**环境变量参考：** + +| 变量 | 必填 | 默认值 | 描述 | +|------|------|--------|------| +| `HG_PD_GRPC_HOST` | 是 | — | 本节点的 gRPC 主机名/IP（Docker 中使用 `pd0`，裸机使用 `192.168.1.10`） | +| `HG_PD_RAFT_ADDRESS` | 是 | — | 本节点的 Raft 地址（如 `pd0:8610`） | +| `HG_PD_RAFT_PEERS_LIST` | 是 | — | 所有 PD 节点的 Raft 地址（如 `pd0:8610,pd1:8610,pd2:8610`） | +| `HG_PD_INITIAL_STORE_LIST` | 是 | — | 预期的 Store gRPC 地址（如 `store0:8500,store1:8500,store2:8500`） | +| `HG_PD_GRPC_PORT` | 否 | `8686` | gRPC 服务端口 | +| `HG_PD_REST_PORT` | 否 | `8620` | REST API 端口 | +| `HG_PD_DATA_PATH` | 否 | `/hugegraph-pd/pd_data` | 元数据存储路径 | +| `HG_PD_INITIAL_STORE_COUNT` | 否 | `1` | 集群可用所需的最小 Store 数量 | + +> **注意**：在 Docker 桥接网络中，`HG_PD_GRPC_HOST` 和 `HG_PD_RAFT_ADDRESS` 应使用容器主机名（如 `pd0`）而非 IP 地址。 + +> **已弃用的别名**：`GRPC_HOST`、`RAFT_ADDRESS`、`RAFT_PEERS`、`PD_INITIAL_STORE_LIST` 仍可使用，但会输出弃用警告。新部署请使用 `HG_PD_*` 名称。 + +完整的集群部署指南请参阅 [docker/README.md](https://github.com/apache/hugegraph/blob/master/docker/README.md)。 + ### 4 配置 PD 的主要配置文件为 `conf/application.yml`，以下是关键配置项： diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md index 5b0610e16..7dbdc9c77 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md @@ -39,7 +39,7 @@ Core 模块是 Tinkerpop 接口的实现，Backend 模块用于管理数据存 #### 3.1 使用 Docker 容器 (便于**测试**) -可参考 [Docker 部署方式](https://github.com/apache/hugegraph/blob/master/hugegraph-server/hugegraph-dist/docker/README.md)。 +可参考 [Docker 部署方式](https://github.com/apache/hugegraph/blob/master/docker/README.md)。 我们可以使用 `docker run -itd --name=server -p 8080:8080 -e PASSWORD=xxx hugegraph/hugegraph:1.7.0` 去快速启动一个内置了 `RocksDB` 的 `Hugegraph server`. @@ -55,23 +55,23 @@ Core 模块是 Tinkerpop 接口的实现，Backend 模块用于管理数据存 -另外，如果我们希望能够在一个文件中管理除了 `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 +docker compose up -d ``` +如需开启鉴权，可在 compose 文件的环境变量中添加 `PASSWORD=xxx`，或在 `docker run` 命令中传入 `-e PASSWORD=xxx`。 + +完整的部署指南请参阅 [docker/README.md](https://github.com/apache/hugegraph/blob/master/docker/README.md)。 + > 注意： > > 1. hugegraph 的 docker 镜像是一个便捷版本，用于快速启动 hugegraph，并不是**官方发布物料包方式**。你可以从 [ASF Release Distribution Policy](https://infra.apache.org/release-distribution.html#dockerhub) 中得到更多细节。 @@ -307,6 +307,34 @@ curl http://localhost:8081/graphs ```bash bin/stop-hugegraph.sh ``` + +#### Docker 集群快速启动 + +通过 Docker 运行完整的分布式集群（3 PD + 3 Store + 3 Server）： + +> **前置条件**：为 Docker Desktop 分配至少 **12 GB** 内存（设置 → 资源 → 内存）。需要克隆仓库（在更新后的镜像发布之前的临时要求）。 + +```bash +git clone https://github.com/apache/hugegraph.git +cd hugegraph/docker +docker compose -f docker-compose-3pd-3store-3server.yml up -d +``` + +服务通过 `hg-net` 桥接网络上的容器主机名进行通信。配置通过环境变量注入： + +```yaml +# Server 配置 +HG_SERVER_BACKEND: hstore +HG_SERVER_PD_PEERS: pd0:8686,pd1:8686,pd2:8686 +``` + +验证集群： +```bash +curl http://localhost:8080/versions +curl http://localhost:8620/v1/stores +``` + +完整的环境变量参考、端口表和故障排查指南请参阅 [docker/README.md](https://github.com/apache/hugegraph/blob/master/docker/README.md)。 ##### 5.1.2 RocksDB / ToplingDB diff --git a/content/en/docs/guides/hugegraph-docker-cluster.md b/content/en/docs/guides/hugegraph-docker-cluster.md new file mode 100644 index 000000000..32edf2263 --- /dev/null +++ b/content/en/docs/guides/hugegraph-docker-cluster.md @@ -0,0 +1,135 @@ +--- +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) +- Repository cloned locally (temporary requirement until updated images are published to Docker Hub) + +> **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 +git clone https://github.com/apache/hugegraph.git +cd hugegraph/docker +docker compose up -d +``` + +Verify: +```bash +curl http://localhost:8080/versions +``` + +## 3-Node Cluster Quickstart + +```bash +cd hugegraph/docker +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` + +**Partition assignment not completing**: Check `curl http://localhost:8620/v1/stores` — all 3 stores must show `"state":"Up"` before partitions are assigned. + +**Connection refused**: Ensure `HG_*` env vars use container hostnames (`pd0`, `store0`), not `127.0.0.1`. diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md b/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md index 2d82a48d5..fc75d8d26 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md @@ -50,6 +50,48 @@ mvn clean install -DskipTests=true # target/apache-hugegraph-incubating-{version}.tar.gz ``` +#### 3.3 Docker Deployment + +The HugeGraph-Store Docker image is available on Docker Hub as `hugegraph/store:latest`. + +For a complete 3-node cluster with PD, Store, and Server, use the compose file: + +```bash +git clone https://github.com/apache/hugegraph.git +cd hugegraph/docker +docker compose -f docker-compose-3pd-3store-3server.yml up -d +``` + +To run a single Store node via `docker run`: + +```bash +docker run -d \ + -p 8520:8520 \ + -p 8500:8500 \ + -p 8510:8510 \ + -e HG_STORE_PD_ADDRESS=:8686 \ + -e HG_STORE_GRPC_HOST= \ + -e HG_STORE_RAFT_ADDRESS=:8510 \ + -v /path/to/storage:/hugegraph-store/storage \ + --name hugegraph-store \ + hugegraph/store:latest +``` + +**Environment variable reference:** + +| Variable | Required | Default | Description | +|----------|----------|---------|-------------| +| `HG_STORE_PD_ADDRESS` | Yes | — | PD gRPC addresses (e.g. `pd0:8686,pd1:8686,pd2:8686`) | +| `HG_STORE_GRPC_HOST` | Yes | — | This node's hostname/IP for gRPC (e.g. `store0`) | +| `HG_STORE_RAFT_ADDRESS` | Yes | — | This node's Raft address (e.g. `store0:8510`) | +| `HG_STORE_GRPC_PORT` | No | `8500` | gRPC server port | +| `HG_STORE_REST_PORT` | No | `8520` | REST API port | +| `HG_STORE_DATA_PATH` | No | `/hugegraph-store/storage` | Data storage path | + +> **Note**: In Docker bridge networking, use container hostnames (e.g. `store0`) for `HG_STORE_GRPC_HOST` instead of IP addresses. + +> **Deprecated aliases**: `PD_ADDRESS`, `GRPC_HOST`, `RAFT_ADDRESS` still work but log a deprecation warning. Use the `HG_STORE_*` names for new deployments. + ### 4 Configuration The main configuration file for Store is `conf/application.yml`. Here are the key configuration items: @@ -188,6 +230,34 @@ pdserver: address: 127.0.0.1:8686,127.0.0.1:8687,127.0.0.1:8688 ``` +#### 6.3 Docker Cluster Quickstart + +The 3-node Store cluster is included in `docker/docker-compose-3pd-3store-3server.yml`. Each Store node gets its own hostname and env vars: + +```yaml +# store0 +HG_STORE_PD_ADDRESS: pd0:8686,pd1:8686,pd2:8686 +HG_STORE_GRPC_HOST: store0 +HG_STORE_GRPC_PORT: "8500" +HG_STORE_REST_PORT: "8520" +HG_STORE_RAFT_ADDRESS: store0:8510 +HG_STORE_DATA_PATH: /hugegraph-store/storage + +# store1 +HG_STORE_PD_ADDRESS: pd0:8686,pd1:8686,pd2:8686 +HG_STORE_GRPC_HOST: store1 +HG_STORE_RAFT_ADDRESS: store1:8510 + +# store2 +HG_STORE_PD_ADDRESS: pd0:8686,pd1:8686,pd2:8686 +HG_STORE_GRPC_HOST: store2 +HG_STORE_RAFT_ADDRESS: store2:8510 +``` + +Store nodes start only after all PD nodes pass healthchecks (`/v1/health`), enforced via `depends_on: condition: service_healthy`. + +See [docker/README.md](https://github.com/apache/hugegraph/blob/master/docker/README.md) for the full setup guide. + ### 7 Verify Store Service Confirm that the Store service is running properly: diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-pd.md b/content/en/docs/quickstart/hugegraph/hugegraph-pd.md index c8b6cf401..e76330ef8 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-pd.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-pd.md @@ -49,6 +49,53 @@ mvn clean install -DskipTests=true # target/apache-hugegraph-incubating-{version}.tar.gz ``` +#### 3.3 Docker Deployment + +The HugeGraph-PD Docker image is available on Docker Hub as `hugegraph/pd:latest`. + +For a complete 3-node cluster with PD, Store, and Server, use the compose file: + +```bash +git clone https://github.com/apache/hugegraph.git +cd hugegraph/docker +docker compose -f docker-compose-3pd-3store-3server.yml up -d +``` + +To run a single PD node via `docker run`, configuration is provided via environment variables: + +```bash +docker run -d \ + -p 8620:8620 \ + -p 8686:8686 \ + -p 8610:8610 \ + -e HG_PD_GRPC_HOST= \ + -e HG_PD_RAFT_ADDRESS=:8610 \ + -e HG_PD_RAFT_PEERS_LIST=:8610 \ + -e HG_PD_INITIAL_STORE_LIST=:8500 \ + -v /path/to/data:/hugegraph-pd/pd_data \ + --name hugegraph-pd \ + hugegraph/pd:latest +``` + +**Environment variable reference:** + +| Variable | Required | Default | Description | +|----------|----------|---------|-------------| +| `HG_PD_GRPC_HOST` | Yes | — | This node's hostname/IP for gRPC (e.g. `pd0` in Docker, `192.168.1.10` on bare metal) | +| `HG_PD_RAFT_ADDRESS` | Yes | — | This node's Raft address (e.g. `pd0:8610`) | +| `HG_PD_RAFT_PEERS_LIST` | Yes | — | All PD peers (e.g. `pd0:8610,pd1:8610,pd2:8610`) | +| `HG_PD_INITIAL_STORE_LIST` | Yes | — | Expected store gRPC addresses (e.g. `store0:8500,store1:8500,store2:8500`) | +| `HG_PD_GRPC_PORT` | No | `8686` | gRPC server port | +| `HG_PD_REST_PORT` | No | `8620` | REST API port | +| `HG_PD_DATA_PATH` | No | `/hugegraph-pd/pd_data` | Metadata storage path | +| `HG_PD_INITIAL_STORE_COUNT` | No | `1` | Minimum stores required for cluster availability | + +> **Note**: In Docker bridge networking, use container hostnames (e.g. `pd0`) for `HG_PD_GRPC_HOST` and `HG_PD_RAFT_ADDRESS` instead of IP addresses. + +> **Deprecated aliases**: `GRPC_HOST`, `RAFT_ADDRESS`, `RAFT_PEERS`, `PD_INITIAL_STORE_LIST` still work but log a deprecation warning. Use the `HG_PD_*` names for new deployments. + +See [docker/README.md](https://github.com/apache/hugegraph/blob/master/docker/README.md) for the full cluster setup guide. + ### 4 Configuration The main configuration file for PD is `conf/application.yml`. Here are the key configuration items: diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-server.md b/content/en/docs/quickstart/hugegraph/hugegraph-server.md index ee70e6d2d..e3c2e8b7f 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-server.md @@ -42,7 +42,7 @@ There are four ways to deploy HugeGraph-Server components: #### 3.1 Use Docker container (Convenient for Test/Dev) -You can refer to the [Docker deployment guide](https://github.com/apache/hugegraph/blob/master/hugegraph-server/hugegraph-dist/docker/README.md). +You can refer to the [Docker deployment guide](https://github.com/apache/hugegraph/blob/master/docker/README.md). We can use `docker run -itd --name=server -p 8080:8080 -e PASSWORD=xxx hugegraph/hugegraph:1.7.0` to quickly start a `HugeGraph Server` with a built-in `RocksDB` backend. @@ -56,23 +56,23 @@ If you use docker desktop, you can set the option like: image -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 +docker compose up -d ``` +To enable authentication, add `PASSWORD=xxx` to the service environment in the compose file or pass `-e PASSWORD=xxx` to `docker run`. + +See [docker/README.md](https://github.com/apache/hugegraph/blob/master/docker/README.md) for the full setup guide. + > Note: > > 1. The docker image of the hugegraph is a convenient release to start it quickly, but not **official distribution** artifacts. You can find more details from [ASF Release Distribution Policy](https://infra.apache.org/release-distribution.html#dockerhub). @@ -323,6 +323,34 @@ The sequence to stop the services should be the reverse of the startup sequence: ```bash bin/stop-hugegraph.sh ``` + +#### Docker Cluster Quickstart + +For running the full distributed cluster (3 PD + 3 Store + 3 Server) via Docker: + +> **Prerequisites**: Allocate at least **12 GB** memory to Docker Desktop (Settings → Resources → Memory). Requires a cloned repository (temporary requirement until updated images are published). + +```bash +git clone https://github.com/apache/hugegraph.git +cd hugegraph/docker +docker compose -f docker-compose-3pd-3store-3server.yml up -d +``` + +Services communicate via container hostnames on the `hg-net` bridge network. Configuration is injected via environment variables: + +```yaml +# Server configuration +HG_SERVER_BACKEND: hstore +HG_SERVER_PD_PEERS: pd0:8686,pd1:8686,pd2:8686 +``` + +Verify the cluster: +```bash +curl http://localhost:8080/versions +curl http://localhost:8620/v1/stores +``` + +See [docker/README.md](https://github.com/apache/hugegraph/blob/master/docker/README.md) for the full environment variable reference, port table, and troubleshooting guide. ##### 5.1.2 Memory