Skip to content

Version 1.7 of the documentation is no longer actively maintained. The site that you are currently viewing is an archived snapshot. For up-to-date documentation, see the latest version.

HugeGraph-PD Quick Start

1 HugeGraph-PD Overview

HugeGraph-PD (Placement Driver) is the metadata management component of HugeGraph’s distributed version, responsible for managing the distribution of graph data and coordinating storage nodes. It plays a central role in distributed HugeGraph, maintaining cluster status and coordinating HugeGraph-Store storage nodes.

2 Prerequisites

2.1 Requirements

  • Operating System: Linux or macOS (Windows has not been fully tested)
  • Java version: ≥ 11
  • Maven version: ≥ 3.5.0

3 Deployment

There are two ways to deploy the HugeGraph-PD component:

  • Method 1: Download the tar package
  • Method 2: Compile from source

3.1 Download the tar package

Download the latest version of HugeGraph-PD from the Apache HugeGraph official download page:

1# 1.7.0 is a historical release from the incubation period, so its file and directory names still include "incubating"
2wget https://downloads.apache.org/hugegraph/1.7.0/apache-hugegraph-incubating-1.7.0.tar.gz
3tar zxf apache-hugegraph-incubating-1.7.0.tar.gz
4cd apache-hugegraph-incubating-1.7.0/apache-hugegraph-pd-incubating-1.7.0

3.2 Compile from source

 1# 1. Clone the source code
 2git clone https://github.com/apache/hugegraph.git
 3
 4# 2. Build the project
 5cd hugegraph
 6mvn clean install -DskipTests=true
 7
 8# 3. After a successful build, the PD directory and complete distribution package are located at
 9#    hugegraph-pd/apache-hugegraph-pd-{version}
10#    target/apache-hugegraph-{version}.tar.gz

3.3 Docker Deployment

The HugeGraph-PD Docker image is available on Docker Hub as hugegraph/pd.

Note: The following steps assume you have already cloned or pulled the HugeGraph main repository locally, or at least have its docker/ directory available.

Use the docker compose setup to deploy the complete 3-node cluster (PD + Store + Server):

1cd hugegraph/docker
2# Keep the version aligned with the latest release, for example 1.x.0
3HUGEGRAPH_VERSION=1.7.0 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:

 1docker run -d \
 2  -p 8620:8620 \
 3  -p 8686:8686 \
 4  -p 8610:8610 \
 5  -e HG_PD_GRPC_HOST=<your-ip> \
 6  -e HG_PD_RAFT_ADDRESS=<your-ip>:8610 \
 7  -e HG_PD_RAFT_PEERS_LIST=<your-ip>:8610 \
 8  -e HG_PD_INITIAL_STORE_LIST=<store-ip>:8500 \
 9  -v /path/to/data:/hugegraph-pd/pd_data \
10  --name hugegraph-pd \
11  hugegraph/pd:1.7.0

Environment variable reference:

VariableRequiredDefaultDescription
HG_PD_GRPC_HOSTYes—This node’s hostname/IP for gRPC (e.g. pd0 in Docker, 192.168.1.10 on bare metal)
HG_PD_RAFT_ADDRESSYes—This node’s Raft address (e.g. pd0:8610)
HG_PD_RAFT_PEERS_LISTYes—All PD peers (e.g. pd0:8610,pd1:8610,pd2:8610)
HG_PD_INITIAL_STORE_LISTYes—Expected store gRPC addresses (e.g. store0:8500,store1:8500,store2:8500)
HG_PD_GRPC_PORTNo8686gRPC server port
HG_PD_REST_PORTNo8620REST API port
HG_PD_DATA_PATHNo/hugegraph-pd/pd_dataMetadata storage path
HG_PD_INITIAL_STORE_COUNTNo1Minimum 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.

To view runtime logs for a running PD container use docker logs <container-name> (e.g. docker logs hg-pd0).

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

 1spring:
 2  application:
 3    name: hugegraph-pd
 4
 5grpc:
 6  # gRPC port for cluster mode
 7  port: 8686
 8  host: 127.0.0.1
 9
10server:
11  # REST service port
12  port: 8620
13
14pd:
15  # Storage path
16  data-path: ./pd_data
17  # Auto-expansion check cycle (seconds)
18  patrol-interval: 1800
19  # Minimum number of Store nodes required for cluster availability
20  initial-store-count: 1
21  # Store configuration information, format is IP:gRPC port
22  initial-store-list: 127.0.0.1:8500
23
24raft:
25  # Cluster mode
26  address: 127.0.0.1:8610
27  # Raft addresses of all PD nodes in the cluster
28  peers-list: 127.0.0.1:8610
29
30store:
31  # Store offline time (seconds). After this time, the store is considered permanently unavailable
32  max-down-time: 172800
33  # Whether to enable store monitoring data storage
34  monitor_data_enabled: true
35  # Monitoring data interval
36  monitor_data_interval: 1 minute
37  # Monitoring data retention time
38  monitor_data_retention: 1 day
39  initial-store-count: 1
40
41partition:
42  # Default number of replicas per partition
43  default-shard-count: 1
44  # Default maximum number of replicas per machine
45  store-max-shard-count: 12

For multi-node deployment, you need to modify the port and address configurations for each node to ensure proper communication between nodes.

5 Start and Stop

5.1 Start PD

In the PD installation directory, execute:

1./bin/start-hugegraph-pd.sh

The startup script supports a -d flag to control daemon mode:

  • -d true (default): run as a background daemon; the script returns immediately.
  • -d false: run in foreground — the script execs Java, so the container/supervisor process IS Java. Use this when running under Docker or a process supervisor (systemd, supervisord) so crashes are detected and the service is restarted automatically.

After successful startup, you can see logs similar to the following in logs/hugegraph-pd-stdout.log:

1YYYY-mm-dd xx:xx:xx [main] [INFO] o.a.h.p.b.HugePDServer - Started HugePDServer in x.xxx seconds (JVM running for x.xxx)

5.2 Stop PD

In the PD installation directory, execute:

1./bin/stop-hugegraph-pd.sh

6 Verification

Confirm that the PD service is running properly:

1curl http://localhost:8620/actuator/health

If it returns {"status":"UP"}, it indicates that the PD service has been successfully started.

You can also verify Store node status through the PD API:

1curl http://localhost:8620/v1/stores

If the response shows state as Up, the corresponding Store node is running normally. The example below shows a single Store node. In a healthy 3-node deployment, the storeId list should contain three IDs, and stateCountMap.Up, numOfService, and numOfNormalService should all be 3.

 1{
 2  "message": "OK",
 3  "data": {
 4    "stores": [
 5      {
 6        "storeId": 8319292642220586694,
 7        "address": "127.0.0.1:8500",
 8        "raftAddress": "127.0.0.1:8510",
 9        "version": "",
10        "state": "Up",
11        "deployPath": "/Users/{your_user_name}/hugegraph/apache-hugegraph-incubating-1.5.0/apache-hugegraph-store-incubating-1.5.0/lib/hg-store-node-1.5.0.jar",
12        "dataPath": "./storage",
13        "startTimeStamp": 1754027127969,
14        "registedTimeStamp": 1754027127969,
15        "lastHeartBeat": 1754027909444,
16        "capacity": 494384795648,
17        "available": 346535829504,
18        "partitionCount": 0,
19        "graphSize": 0,
20        "keyCount": 0,
21        "leaderCount": 0,
22        "serviceName": "127.0.0.1:8500-store",
23        "serviceVersion": "",
24        "serviceCreatedTimeStamp": 1754027127000,
25        "partitions": []
26      }
27    ],
28    "stateCountMap": {
29      "Up": 1
30    },
31    "numOfService": 1,
32    "numOfNormalService": 1
33  },
34  "status": 0
35}
Last modified 2026-09-04 · docs: sync 1.7 documentation (4211f768b)