HugeGraph Docker Cluster Guide

Overview

HugeGraph can quickly run a full distributed deployment (PD + Store + Server) with Docker Compose. This works on Linux and Mac.

Prerequisites

• Docker Engine 20.10+ or Docker Desktop 4.x+
• Docker Compose v2
• For a 3-node cluster on Mac: allocate at least 12 GB memory (Settings → Resources → Memory). Adjust this on other platforms as needed.

Tested environments: Linux (native Docker) and macOS (Docker Desktop with ARM M4).

Compose Files

Three compose files are available in the docker/ directory of the HugeGraph main repository:

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

Single-Node Quickstart

cd hugegraph/docker
# Keep the version aligned with the latest release, for example 1.x.0
HUGEGRAPH_VERSION=1.7.0 docker compose up -d

Verify:

curl http://localhost:8080/versions

3-Node Cluster Quickstart

cd hugegraph/docker
HUGEGRAPH_VERSION=1.7.0 docker compose -f docker-compose-3pd-3store-3server.yml up -d

Built-in startup ordering:

1. PD nodes start first and must pass the /v1/health check
2. Store nodes start only after all PD nodes are healthy
3. Server nodes start last, after all PD and Store nodes are healthy

Verify that the cluster is healthy:

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

Deprecated aliases: GRPC_HOST → HG_PD_GRPC_HOST, RAFT_ADDRESS → HG_PD_RAFT_ADDRESS, RAFT_PEERS → HG_PD_RAFT_PEERS_LIST

Store Variables

Deprecated aliases: PD_ADDRESS → HG_STORE_PD_ADDRESS, GRPC_HOST → HG_STORE_GRPC_HOST, RAFT_ADDRESS → HG_STORE_RAFT_ADDRESS

Server Variables

Deprecated aliases: BACKEND → HG_SERVER_BACKEND, PD_PEERS → HG_SERVER_PD_PEERS

Port Reference

Troubleshooting

1. Containers exit due to OOM (exit code 137): Increase Docker Desktop memory to at least 12 GB, or reduce the JVM heap settings for the process that is being killed.

2. Raft leader election timeout: Check that HG_PD_RAFT_PEERS_LIST is identical on all PD nodes. Verify connectivity with docker exec hg-pd0 ping pd1.

3. Partition assignment does not complete: Check curl http://localhost:8620/v1/stores and confirm that all 3 stores show "state":"Up" before partition assignment can finish.

4. Connection refused: Ensure HG_* environment variables use container hostnames (pd0, store0) instead of 127.0.0.1.

Viewing runtime logs: Use docker logs <container-name> (e.g. docker logs hg-pd0) to view logs directly without exec-ing into the container.