HugeGraph (OLTP)

• 1: HugeGraph Server Quick Start
• 2: HugeGraph-PD Quick Start
• 3: HugeGraph-Store Quick Start
• 4: Deploy HugeGraph with Helm
• 5: Operate HugeGraph on Kubernetes

1 - HugeGraph Server Quick Start

1 HugeGraph Server Overview

apache/hugegraph is the main repository for the HugeGraph graph database. Its top-level modules include hugegraph-server, hugegraph-pd, and hugegraph-store. This page describes the hugegraph-server module and the service it runs.

The hugegraph-server module contains hugegraph-core, hugegraph-api, hugegraph-dist, and storage adapters. Core implements the property graph model, transactions, and TinkerPop interfaces. API provides the HTTP service and delegates client requests to Core. Graph data is stored in RocksDB (the default standalone backend), HStore (distributed), or HBase.

Naming: HugeGraph means the overall project or main repository, hugegraph-server is its Server module, and HugeGraphServer is the Java service class. Server below means the running graph database service.

flowchart TD
    A{Choose installation source}
    A -->|Release| R["HugeGraph 1.7.0 archive"]
    R --> V[Verify SHA-512]
    V --> X[Extract and use bundled configuration]
    A -->|Development| M["master source"]
    M --> B["mvn package -DskipTests"]
    B --> C[Check RocksDB configuration in conf/graphs]
    C --> I[bin/init-store.sh]
    I --> S["bin/start-hugegraph.sh -p true"]
    S --> Q["Request /versions and graph vertices"]

The map uses short labels for the repository modules described above. server, core, api, dist, pd, and store refer to the corresponding hugegraph- modules; dist packages the distribution.

---
markmap:
  spacingHorizontal: 40
---
# HugeGraph
## server
- core
- api
- dist
## pd
## store

2 Dependency for Building/Running

2.1 Install Java 17 (JDK 17)

Starting with HugeGraph 1.8.0, use Java 17; 1.7.0 is the last release supporting Java 11. Build all modules with JDK 17 and Maven 3.6.3 or later, and run Server, PD and Store with JDK 17. Server security check (-s true) requires Java 17 to 23 and a readable conf/java-security.properties; on Java 24 or later, start Server with -s false (JDK 24+ dropped Security Manager via JEP 486).

Before continuing, run java -version to confirm your JDK version.

1# Bundled Driver and Console default to GraphBinary V1
2# - Schema results are standard maps
3# - Blob values are binary (including inside returned elements)
4serializer:
5  className: org.apache.tinkerpop.gremlin.util.ser.GraphBinaryMessageSerializerV1
6  config:
7    ioRegistries: [org.apache.hugegraph.structure.io.HugeGraphIoRegistry]

1# Default HTTP JSON uses untyped GraphSON V1
2# - Preserves the legacy Tree key/value array structure
3# - Typed GraphSON V1 is disabled for security (typed V2/V3 remain available for simple values and IDs)
4# - graph.schema() returns property keys, vertex labels, edge labels, and index labels

3 Deploy

There are four ways to deploy the Server service:

• Docker container Quickly start a Server service for testing or development.
• ASF release archive Download a released tarball and verify it before installation.
• master source Build the development branch; its output is not an ASF release archive.
• Legacy one-click deployment (outdated) Reference for the older deployment workflow.

3.1 Use Docker container (Convenient for Test/Dev)

You can refer to the Docker deployment guide.

You can use docker run -itd --name=server -p 8080:8080 -e PASSWORD=xxx hugegraph/hugegraph:1.7.0 to quickly start a Server instance using the RocksDB backend.

Optional:

1. You can use docker exec -it server bash to enter the container for troubleshooting or other maintenance operations.
2. You can use docker run -itd --name=server -p 8080:8080 -e PRELOAD="true" hugegraph/hugegraph:1.7.0 to preload a built-in sample graph at startup. You can verify it through the RESTful API. See 5.1.4 for details.
3. You can use -e PASSWORD=xxx to enable authentication mode and set the admin password. See Config Authentication for details.

If you use Docker Desktop, you can set the options as follows:

Use docker compose to manage multiple HugeGraph services from one configuration. Four Compose files are available in the docker/ directory:

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.yml up -d --wait

The standalone topology publishes the Server on port 8080 and Hubble on 127.0.0.1:8088. HUGEGRAPH_VERSION selects the Server, PD, and Store image tags; Hubble is selected separately with HUBBLE_IMAGE.

The standalone docker-compose.yml example uses hugegraph/hugegraph:1.7.0; its docker/conf/hubble/standalone.properties is bundled in source. Compose reads the administrator password from HUGEGRAPH_ADMIN_PASSWORD and JWT secret from HUGEGRAPH_AUTH_TOKEN_SECRET, normally in docker/.env. A nonempty password enables authentication, automatically detected by Hubble. With docker run, use -e PASSWORD=xxx. Master HStore Compose files cannot be combined with 1.7.0 PD/Store/Server release images.

JWT version differences: Master-built Server maps HUGEGRAPH_AUTH_TOKEN_SECRET to HG_SERVER_AUTH_TOKEN_SECRET and writes startup configuration; preserve the secret across recreation. The 1.7.0 entrypoint handles older variables such as PASSWORD, ignoring HG_SERVER_AUTH_TOKEN_SECRET. To keep a stable JWT secret in 1.7.0, persist auth.token_secret in that version’s conf/graphs/hugegraph.properties. With a randomly generated default, do not assume issued JWTs survive Server restarts.

See docker/README.md for the full setup guide.

Server service identity with PD

For a PD-backed Server, the Helm chart exposes server.serviceId and server.graphSpace. Both default to DEFAULT, which preserves the existing server.service_id and server.graphspace values in conf/rest-server.properties. A non-default chart value injects HG_SERVER_SERVICE_ID or HG_SERVER_GRAPHSPACE into the Server container. These service identity chart settings (server.serviceId, server.graphSpace, and server.testGraphAlias) apply to development 1.8.0+ builds and charts; older versions such as 1.7.0 do not support these options. Do not use this example with older chart or image versions lacking these features. Non-empty service IDs supplied through HG_SERVER_SERVICE_ID, SERVICE_ID, or server.serviceId must use printable ASCII; spaces and backslashes are supported, while deployment checks reject non-ASCII and control characters. This entrypoint restriction does not change Core Service naming or existing manually supplied properties. Helm preserves dollar signs in server.serviceId literally, including $(POD_IP); this field does not expand Kubernetes environment references. The full service ID, including / and -, is retained when service metadata is reloaded or its graph space is cleared. Set the identity through these chart values; Server extraEnv reserves both the new and legacy identity variable names. HG_SERVER_GRAPHSPACE, the effective GRAPH_SPACE fallback, and server.graphSpace accept DEFAULT or an existing space name of up to 48 lowercase letters, digits, and underscores, starting with a letter:

1helm upgrade --install hg ./helm/hugegraph \
2  --set-string server.serviceId=analytics \
3  --set-string server.graphSpace=team_a

Before deploying Servers assigned to team_a, create that graph space through an existing Server in DEFAULT, using an account with permission to create graph spaces. The chart and these environment variables do not create graph spaces; all replicas in the Server Deployment use the same identity.

To check a graph in that space with helm test, first create the target graph and set --set-string server.testGraphAlias=team_a-demo to its actual Gremlin binding. Creating the graph space does not create a hugegraph graph.

For container deployments, HG_SERVER_SERVICE_ID and HG_SERVER_GRAPHSPACE write the same two properties. The legacy SERVICE_ID and GRAPH_SPACE names remain accepted: a non-empty new variable wins over its legacy counterpart. If both names for a property are unset or empty, its existing value is preserved. Compose does not automatically forward these host variables; add explicit Server environment: entries in a Compose override. See the Helm chart documentation for details.

These settings select the Server’s PD service metadata. They do not move existing graphs or change server.path_graphspace for REST paths that omit the graph space. Use /graphspaces/team_a/... paths and select the matching graph space and service in Hubble. When authentication is enabled, explicit paths still require authorization.

server.testGraphAlias defaults to DEFAULT-hugegraph. The hook checks this existing local binding on every Server Pod; it does not derive the alias from server.graphSpace. A local binding may exist independently of the Server’s assigned PD graph space, so a successful default hook does not validate graphs in team_a. If Could not rebind appears, first check that the requested graph exists and that its alias is correct. A Pod restart cannot create a missing graph or correct an alias. Match the binding’s case: a local Demo.properties can bind DEFAULT-Demo, while REST-created graph names are lowercase.

Configuration rendering and entrypoint checks alone do not establish non-default Linux discovery, authentication, or isolation between graph spaces.

3.2 Download a Released Archive

This example uses HugeGraph 1.7.0. For other versions, confirm the release and filenames in the ASF download directory. A master source build is not a released binary.

1cd /path/to/downloads
2wget https://downloads.apache.org/hugegraph/1.7.0/apache-hugegraph-incubating-1.7.0.tar.gz
3wget https://downloads.apache.org/hugegraph/1.7.0/apache-hugegraph-incubating-1.7.0.tar.gz.sha512
4sha512sum -c apache-hugegraph-incubating-1.7.0.tar.gz.sha512
5tar zxf apache-hugegraph-incubating-1.7.0.tar.gz

Extract only after SHA-512 verification succeeds. You can also verify the PGP signature following Apache release procedures:

1wget https://downloads.apache.org/hugegraph/1.7.0/apache-hugegraph-incubating-1.7.0.tar.gz.asc
2wget https://downloads.apache.org/hugegraph/KEYS
3gpg --import KEYS
4gpg --verify apache-hugegraph-incubating-1.7.0.tar.gz.asc apache-hugegraph-incubating-1.7.0.tar.gz

Trust publisher keys only after verifying them through Apache project channels. Signature verification can complement SHA-512 checks.

3.3 Build from master Source

These commands build the development branch, not the 1.7.0 release.

Install wget or curl before building.

Download HugeGraph source:

1git clone --branch master https://github.com/apache/hugegraph.git

Compile and package:

1cd hugegraph
2# (Optional) use "-P stage" param if you build failed with the latest code(during pre-release period)
3mvn package -DskipTests -ntp

A successful build logs:

1[INFO] BUILD SUCCESS

The build creates an aggregate master archive under repository-root target/ (the current source version property is 1.8.0):

1target/apache-hugegraph-1.8.0.tar.gz

The filename version comes from source revision; it does not make the build an ASF release artifact. The build also creates repository-root apache-hugegraph-1.8.0/, containing a Server directory named by that module’s final.name, currently apache-hugegraph-server-1.8.0. If retaining only the archive, first run tar zxf target/apache-hugegraph-1.8.0.tar.gz, then enter the Server directory.

Default builds bundle rocksdb, hbase, and hstore modules, listed in backends within backend.properties in the hugegraph-dist JAR. For a RocksDB-only distribution, add -Drocksdb-only:

1mvn package -DskipTests -ntp -Drocksdb-only

1# download toolchain binary package, it includes loader + tool + hubble
2# please check the latest version (e.g. here is 1.7.0)
3wget https://downloads.apache.org/hugegraph/1.7.0/apache-hugegraph-toolchain-incubating-1.7.0.tar.gz
4tar zxf *hugegraph-*.tar.gz
5
6# enter the tool's package
7cd *hugegraph*/*tool* 

1bin/hugegraph deploy -v {hugegraph-version} -p {install-path} [-u {download-path-prefix}]

4 Configuration

Server archives include conf/rest-server.properties, conf/gremlin-server.yaml, and conf/graphs/hugegraph.properties; source builds assemble them from hugegraph-server/hugegraph-dist/src/assembly/static/conf/. Edit them inside the extracted Server directory without a separate generation step. Defaults vary by release; the following defaults and startup behavior describe master.

For standalone RocksDB, confirm backend=rocksdb and serializer=binary in conf/graphs/hugegraph.properties. Normal Server initialization scans conf/graphs/ and loads local graphs without requiring graph.load_from_local_config=true. This option defaults to false and controls constructor preloading. Restart Server to apply graph configuration changes; do not use hot reload for maintenance.

See the configuration guide and option reference for details.

5 Startup

5.1 Use a startup script to startup

Startup is divided into “first startup” and “non-first startup”. On the first startup, you need to initialize the backend database before starting the service.

If the service was stopped manually, or needs to be started again for any other reason, you can usually start it directly because the backend database is persistent.

When HugeGraphServer starts, it connects to the backend storage and checks its version information. If the backend has not been initialized, or if it was initialized with an incompatible version (for example, old-version data), HugeGraphServer will fail to start and report an error.

If you need to access HugeGraphServer externally, modify the restserver.url configuration item in rest-server.properties (the default is http://127.0.0.1:8080) and change it to the machine name or IP address.

Since the configuration (hugegraph.properties) and startup steps required by various backends are slightly different, the following will introduce the configuration and startup of each backend one by one.

5.1.1 Distributed Storage (HStore)

First deploy PD and Store; see the PD Quick Start and Store Quick Start.

1backend=hstore
2serializer=binary
3
4# PD RPC addresses, separated by commas
5pd.peers=127.0.0.1:8686,127.0.0.1:8687,127.0.0.1:8688
6pd.cluster=hg

 1# Simple example with authentication
 2gremlin.graph=org.apache.hugegraph.auth.HugeFactoryAuthProxy
 3
 4# Required HStore backend
 5backend=hstore
 6serializer=binary
 7store=hugegraph
 8
 9# pd config
10pd.peers=127.0.0.1:8686
11pd.cluster=hg

1usePD=true
2# Use cluster hg, matching pd.cluster in graph configuration
3cluster=hg
4# Server process PD addresses; replace with actual PD RPC addresses
5pd.peers=127.0.0.1:8686,127.0.0.1:8687,127.0.0.1:8688
6
7# Optional in local tests; authentication is mandatory in production
8# auth.authenticator=org.apache.hugegraph.auth.StandardAuthenticator

 1usePD=true
 2restserver.url=http://127.0.0.1:8081
 3gremlinserver.url=http://127.0.0.1:8181
 4pd.peers=127.0.0.1:8686
 5
 6rpc.server_host=127.0.0.1
 7rpc.server_port=8091
 8
 9server.id=server-1
10server.role=master

 1usePD=true
 2restserver.url=http://127.0.0.1:8082
 3gremlinserver.url=http://127.0.0.1:8182
 4pd.peers=127.0.0.1:8686
 5
 6rpc.server_host=127.0.0.1
 7rpc.server_port=8092
 8
 9server.id=server-2
10server.role=worker

1host: 127.0.0.1
2port: 8181

1host: 127.0.0.1
2port: 8182

1bin/start-hugegraph.sh

1curl http://localhost:8081/graphspaces/DEFAULT/graphs
2# Expected: {"graphs":["hugegraph"]}

1bin/stop-hugegraph.sh

1# Run from the HugeGraph repository root
2docker build -f hugegraph-pd/Dockerfile -t hugegraph/pd:local .
3docker build -f hugegraph-store/Dockerfile -t hugegraph/store:local .
4docker build -f hugegraph-server/Dockerfile-hstore -t hugegraph/server:local .
5
6cd docker

 1(
 2  set -eu
 3  command -v openssl >/dev/null
 4  jwt_secret="$(openssl rand -hex 32)"
 5  pd_secret="$(openssl rand -hex 24)"
 6  umask 077
 7  test ! -e .env || {
 8    echo ".env already exists; edit it instead of overwriting it" >&2
 9    exit 1
10  }
11  printf "HUGEGRAPH_ADMIN_PASSWORD='%s'\nHUGEGRAPH_AUTH_TOKEN_SECRET='%s'\nHG_PD_AUTH_SECRET_KEY='%s'\n" \
12    'replace-with-your-password' "${jwt_secret}" "${pd_secret}" > .env
13  HG_PD_AUTH_SECRET_KEY="${pd_secret}" ./set-hubble-pd-password.sh hstore
14  HG_PD_AUTH_SECRET_KEY="${pd_secret}" ./set-hubble-pd-password.sh hstore-ha
15)

1set -a
2. ./.env
3set +a
4HUGEGRAPH_VERSION=local docker compose \
5  -f docker-compose-3pd-3store-3server.yml \
6  up -d --wait pd0 pd1 pd2 store0 store1 store2 server0 server1 server2 hubble

1curl -fsS http://localhost:8080/versions
2curl -fsS -u "hg:${HG_PD_AUTH_SECRET_KEY:?Load .env first}" \
3  http://localhost:8620/v1/stores

5.1.2 RocksDB / ToplingDB

The minimal standalone flow below uses a master build and preloads sample data to verify graph reads and writes.

1. Check Java against the master build requirements.
2. Build master source; the commands below use its nested Server directory.
3. Confirm RocksDB configuration, then enter the build output’s nested Server directory.
4. Initialize storage, then start the service with sample data using the commands below.
5. Request /versions and sample graph vertices, and check the actual response contents.

Master conf/graphs/hugegraph.properties already sets backend=rocksdb and serializer=binary. Keep the defaults if using default data directories; otherwise check your backend and paths before initialization.

Initialize storage on first startup or after adding graph configuration under conf/graphs/:

1cd apache-hugegraph-1.7.0/apache-hugegraph-server-1.7.0
2bin/init-store.sh

Start Server and preload the built-in sample graph:

1bin/start-hugegraph.sh -p true

The startup script polls /graphs at configured restserver.url and exits nonzero on timeout or process failure. Check service version, then read sample vertices:

1curl -fsS http://127.0.0.1:8080/versions
2curl --compressed -fsS \
3  http://127.0.0.1:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/vertices

The first response should contain versions; the second should contain vertices with sample names such as marko and lop. A process check or HTTP status alone does not prove backend and business request health.

ToplingDB (Beta): A high-performance RocksDB alternative; see the ToplingDB Quick Start.

5.1.3 HBase

 1backend=hbase
 2serializer=hbase
 3
 4# hbase backend config
 5hbase.hosts=localhost
 6hbase.port=2181
 7# Note: recommend to modify the HBase partition number by the actual/env data amount & RS amount before init store
 8# it may influence the loading speed a lot
 9#hbase.enable_partition=true
10#hbase.vertex_partitions=10
11#hbase.edge_partitions=30

1cd *hugegraph-${version}
2bin/init-store.sh

1bin/start-hugegraph.sh
2Starting HugeGraphServer in daemon mode...
3Connecting to HugeGraphServer (http://127.0.0.1:8080/graphs)....OK
4Started [pid 21614]

5.1.4 Create an example graph when startup

Pass the -p true argument when starting the script to enable preload, which creates a sample graph.

1bin/start-hugegraph.sh -p true
2Starting HugeGraphServer in daemon mode...
3Connecting to HugeGraphServer (http://127.0.0.1:8080/graphs)......OK

And use the RESTful API to request HugeGraphServer and get the following result:

1> curl "http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/vertices" | gunzip
2
3{"vertices":[{"id":"2:lop","label":"software","type":"vertex","properties":{"name":"lop","lang":"java","price":328}},{"id":"1:josh","label":"person","type":"vertex","properties":{"name":"josh","age":32,"city":"Beijing"}},{"id":"1:marko","label":"person","type":"vertex","properties":{"name":"marko","age":29,"city":"Beijing"}},{"id":"1:peter","label":"person","type":"vertex","properties":{"name":"peter","age":35,"city":"Shanghai"}},{"id":"1:vadas","label":"person","type":"vertex","properties":{"name":"vadas","age":27,"city":"Hongkong"}},{"id":"2:ripple","label":"software","type":"vertex","properties":{"name":"ripple","lang":"java","price":199}}]}

This indicates the successful creation of the sample graph.

5.1.5 Startup script options

bin/start-hugegraph.sh accepts the following options. Every one of them takes a value, so write -d false, not a bare -d.

bin/stop-hugegraph.sh accepts -m true|false (default true), which controls whether the cron monitor task is removed along with the service.

bin/hugegraph-server.sh puts -XX:+HeapDumpOnOutOfMemoryError, -XX:HeapDumpPath and -XX:ErrorFile first in JAVA_TOOL_OPTIONS, so, whether or not JAVA_OPTIONS is set and with the exceptions below, an out-of-memory heap dump (heapdump_<host>_<launch time>/java_pid<pid>.hprof) and a JVM crash log (hs_err_pid<pid>_<host>_<launch time>.log) land in logs/, where <launch time> is the local time as YYYYMMDD-HHMMSS. Each start gets its own heapdump_* directory, so the server and the JVMs it starts, such as computer jobs, write separate dumps (HotSpot names each dump and crash log after the JVM’s PID, so a JVM that reuses an earlier PID from the same start cannot write its dump, and its crash log replaces the earlier one’s). The host name keeps servers that share one log directory from picking the same name, and a counter (<launch time>-1, -2, …) is added when the same host already used that second. If the directory cannot be created, for example on a full disk, the server still starts and dumps go to logs/ itself, as a best effort: a full disk may have no room for the dump either. A heap dump can be as large as the heap. The launcher never deletes dumps or heapdump_* directories: each start that reaches Java leaves one, empty unless something ran out of memory, and the launcher keeps it because a computer-job JVM can go on using it after the server exits. Move or delete old ones once no HugeGraph JVM from that launch is running, but never the newest one of a running server; without it, the next dump is written as a file with that name. The JVM reads your own JAVA_TOOL_OPTIONS, JDK_JAVA_OPTIONS (including @argfiles), the command line (JAVA_OPTIONS, or -j when JAVA_OPTIONS is unset or empty) and _JAVA_OPTIONS after these defaults, so a value for one of these flags in any of them overrides the default. Only the environment variables reach the JVMs the server starts: to turn dumps off for all of them, set JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError, while -j or JAVA_OPTIONS turns them off for the server JVM only. Either way each start that reaches Java still creates its empty heapdump_* directory, unless creating it failed and dumps fell back to logs/. If the logs path contains a double quote or %, the launcher warns and heap dumps go to logs/ itself, with no per-launch directory and no crash log default; the JAVA_TOOL_OPTIONS opt-out still applies. A path with both quote characters gets no heap dump default at all. Because of the defaults, the JVM prints Picked up JAVA_TOOL_OPTIONS: ... on stderr at startup.

Version scope: this applies to current development/master builds. In 1.7.0 the heap dump flags are added only when JAVA_OPTIONS is unset, heap dumps go directly to logs/java_pid<pid>.hprof, and JVM crash logs go to the install directory.

5.2 Use Docker to startup

In 3.1 Use Docker container, we introduced how to deploy hugegraph-server with Docker. You can also switch storage backends or preload a sample graph by setting the corresponding parameters.

5.2.1 Create an example graph when starting a server

Set the environment variable PRELOAD=true when starting Docker so that sample data is loaded during startup.

1. Use docker run

   Use docker run -itd --name=server -p 8080:8080 -e PRELOAD=true hugegraph/hugegraph:1.7.0

2. Use docker-compose

   Create a docker-compose.yml file like the following and set PRELOAD=true in the environment. example.groovy is a predefined script used to preload sample data. If needed, you can mount a new example.groovy script to change the preload data.

    1version: '3'
    2services:
    3  server:
    4    image: hugegraph/hugegraph:1.7.0
    5    container_name: server
    6    environment:
    7      - PRELOAD=true
    8      - PASSWORD=xxx
    9    volumes:
   10      - /path/to/yourscript:/hugegraph-server/scripts/example.groovy
   11    ports:
   12      - 8080:8080

   Use docker compose up -d to start the container.

And use the RESTful API to request HugeGraphServer and get the following result:

1> curl "http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/vertices" | gunzip
2
3{"vertices":[{"id":"2:lop","label":"software","type":"vertex","properties":{"name":"lop","lang":"java","price":328}},{"id":"1:josh","label":"person","type":"vertex","properties":{"name":"josh","age":32,"city":"Beijing"}},{"id":"1:marko","label":"person","type":"vertex","properties":{"name":"marko","age":29,"city":"Beijing"}},{"id":"1:peter","label":"person","type":"vertex","properties":{"name":"peter","age":35,"city":"Shanghai"}},{"id":"1:vadas","label":"person","type":"vertex","properties":{"name":"vadas","age":27,"city":"Hongkong"}},{"id":"2:ripple","label":"software","type":"vertex","properties":{"name":"ripple","lang":"java","price":199}}]}

This indicates that the sample graph was created successfully.

6. Access server

6.1 Service startup status check

Use jps to see a service process

1jps
26475 HugeGraphServer

curl request RESTfulAPI

1curl -fsS http://127.0.0.1:8080/versions

HTTP 2xx with a JSON versions field confirms REST responsiveness. HugeGraphServer in jps confirms only process existence; verify backend health by preloading the sample graph and requesting vertices as above.

6.2 Request Server

The RESTful API of HugeGraphServer includes various types of resources, typically including graph, schema, gremlin, traverser and task.

• graph contains vertices、edges
• schema contains vertexlabels、 propertykeys、 edgelabels、indexlabels
• gremlin contains various Gremlin statements, such as g.v(), which can be executed synchronously or asynchronously
• traverser contains various advanced queries including shortest paths, intersections, N-step reachable neighbors, etc.
• task contains query and delete with asynchronous tasks

6.2.1 Get vertices and its related properties in hugegraph

1curl http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/vertices

explanation

1. Server can compress vertex, edge, and other list responses. Use curl --compressed for automatic decompression:

   1curl --compressed -fsS "http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/vertices"

2. The default listener is 127.0.0.1, inaccessible directly from other machines.

   1vim conf/rest-server.properties
   2
   3restserver.url=http://0.0.0.0:8080

response body:

 1{
 2    "vertices": [
 3        {
 4            "id": "2lop",
 5            "label": "software",
 6            "type": "vertex",
 7            "properties": {
 8                "price": [
 9                    {
10                        "id": "price",
11                        "value": 328
12                    }
13                ],
14                "name": [
15                    {
16                        "id": "name",
17                        "value": "lop"
18                    }
19                ],
20                "lang": [
21                    {
22                        "id": "lang",
23                        "value": "java"
24                    }
25                ]
26            }
27        },
28        {
29            "id": "1josh",
30            "label": "person",
31            "type": "vertex",
32            "properties": {
33                "name": [
34                    {
35                        "id": "name",
36                        "value": "josh"
37                    }
38                ],
39                "age": [
40                    {
41                        "id": "age",
42                        "value": 32
43                    }
44                ]
45            }
46        },
47        ...
48    ]
49}

For the detailed API, please refer to RESTful-API

You can also visit localhost:8080/swagger-ui/index.html to check the API.

When using Swagger UI to debug the API provided by HugeGraph, if HugeGraph Server turns on authentication mode, you can enter authentication information on the Swagger page.

Currently, HugeGraph supports setting authentication information in two forms: Basic and Bearer.

7 Stop Server

1cd apache-hugegraph-1.7.0/apache-hugegraph-server-1.7.0
2bin/stop-hugegraph.sh

8 Debug Server with IntelliJ IDEA

Please refer to Setup Server in IDEA

2 - 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.

PD keeps cluster metadata in an embedded RocksDB store under pd.data-path and replicates it across PD nodes with Raft, so a 3-node or 5-node PD cluster keeps serving while a minority of nodes is down. On top of that it registers and activates Store nodes, allocates and rebalances partitions, tracks Store heartbeats, and answers service discovery queries from Store and Server.

PD listens on three ports:

2 Prerequisites

2.1 Requirements

• Operating System: Linux or macOS (Windows has not been fully tested)
• Java version: Java 17 for HugeGraph 1.8.0+ (the Maven build accepts only JDK 17; the start script rejects older runtimes; 1.7.0 is the last release supporting Java 11)
• Maven version: ≥ 3.6.3 (for building from source)

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

Apache downloads currently provide the complete 1.7.0 binary bundle containing PD, Store, and Server, without a separate PD binary. Verify version, signatures, and SHA512 on the official download page. This historical incubating release retains incubating in archive and extracted directory names:

1# Historical release 1.7.0 retains incubating in filenames and directories
2curl -fLO --connect-timeout 10 --max-time 1800 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 packages are located at
 9#    hugegraph-pd/apache-hugegraph-pd-{version}          (unpacked PD distribution)
10#    hugegraph-pd/apache-hugegraph-pd-{version}.tar.gz   (PD only package, Linux build hosts only)
11#    target/apache-hugegraph-{version}.tar.gz            (PD + Store + Server package)

To build only the PD distribution and the modules it depends on:

1mvn clean package -pl hugegraph-pd/hg-pd-dist -am -DskipTests

The unpacked distribution contains just three directories: bin (start and stop scripts), conf (application.yml, application.yml.template, log4j2.xml, verify-license.json) and lib (the hg-pd-service jar).

3.3 Docker Deployment

HG_PD_* mappings and /v1/ready are features of current master; the Server 1.7.0 source tag lacks these Docker mappings and readiness API. The following examples require images built from current master and tagged local. For release 1.7.0 assets, use bundled configuration and version-specific instructions:

1# Run from the HugeGraph repository root
2docker build -f hugegraph-pd/Dockerfile -t hugegraph/pd:local .

To run master-built PD alone, first set a deployment-specific secret and replace example addresses with addresses reachable by the container:

 1export HG_PD_AUTH_SECRET_KEY="$(openssl rand -hex 24)"
 2docker run -d \
 3  -p 8620:8620 -p 8686:8686 -p 8610:8610 \
 4  -e HG_PD_GRPC_HOST=192.168.1.10 \
 5  -e HG_PD_RAFT_ADDRESS=192.168.1.10:8610 \
 6  -e HG_PD_RAFT_PEERS_LIST=192.168.1.10:8610 \
 7  -e HG_PD_INITIAL_STORE_LIST=192.168.1.20:8500 \
 8  -e HG_PD_AUTH_SECRET_KEY="$HG_PD_AUTH_SECRET_KEY" \
 9  -v /path/to/data:/hugegraph-pd/pd_data \
10  --name hugegraph-pd \
11  hugegraph/pd:local

The master entrypoint requires all five mandatory variables, builds SPRING_APPLICATION_JSON overrides, then starts PD. Other settings come from image conf/application.yml; JAVA_OPTS is passed to the JVM. Deprecated GRPC_HOST, RAFT_ADDRESS, RAFT_PEERS, and PD_INITIAL_STORE_LIST remain supported with warnings.

Docker HEALTHCHECK polls /v1/health every 15 seconds, confirming only REST listener liveness, not a Raft quorum. Compose uses the same liveness check; verify /v1/ready separately before starting Store. Containers run Java in the foreground and exit when Java exits; automatic restart requires a Docker restart policy. Inspect logs with docker logs <container-name>.

See the Store Docker section and docker/README.md for master Compose and the minimal topology. When starting the full topology with Hubble, first generate the untracked Hubble configuration described in that README.

4 Configuration

PD startup reads installation conf/application.yml. Match this file to the installed version: 1.7.0 configuration or master configuration. Master leaves auth.secret-key empty, causing protected REST calls to be rejected until configured. Startup does not read application.yml.template.

4.1 Configuration Reference

These tables were checked against hg-pd-dist configuration and Java defaults at Server master commit 2f827d6e8c9c62ae858f2fc122b3a192d015e2f4; they do not describe every 1.7.0 behavior. Use original tagged configuration with release binaries and master configuration with master builds.

gRPC and REST

application.yml.template also carries grpc.netty-server.max-inbound-message-size: 100MB, but PD sets the gRPC server’s inbound message limit to 1 GB in code, so that key has no effect.

Raft

PD core

Store management

Partitions

The initial partition count is derived from these two values and the size of pd.initial-store-list:

1initial partitions = store count * partition.store-max-shard-count / partition.default-shard-count

Discovery, license and metrics

Thread pools

4.2 Single-node configuration

For master-built distributions, start with conf/application.yml, adjust per-node gRPC/Raft addresses and data paths, and set auth.secret-key. The following values are for development and testing. One PD node provides no majority fault tolerance; partition.default-shard-count: 1 means one replica per partition.

 1grpc:
 2  host: 127.0.0.1
 3  port: 8686
 4server:
 5  port: 8620
 6raft:
 7  address: 127.0.0.1:8610
 8  peers-list: 127.0.0.1:8610
 9pd:
10  data-path: ./pd_data
11  initial-store-count: 1
12  initial-store-list: 127.0.0.1:8500
13partition:
14  default-shard-count: 1
15auth:
16  secret-key: replace-with-deployment-secret

Generate a deployment secret with openssl rand -hex 24; Docker supplies it through HG_PD_AUTH_SECRET_KEY. See REST API authentication for the different 1.7.0 behavior.

4.3 Three-node cluster configuration

For a production cluster run 3 or 5 PD nodes, an odd number so Raft always has a quorum. A 3-node cluster tolerates one node failure. raft.peers-list must list every node and must be byte-for-byte identical on all of them, while grpc.host and raft.address differ per node.

Node 1 (192.168.1.10):

 1grpc:
 2  host: 192.168.1.10
 3  port: 8686
 4server:
 5  port: 8620
 6raft:
 7  address: 192.168.1.10:8610
 8  peers-list: 192.168.1.10:8610,192.168.1.11:8610,192.168.1.12:8610
 9pd:
10  data-path: /data/pd
11  initial-store-count: 3
12  initial-store-list: 192.168.1.20:8500,192.168.1.21:8500,192.168.1.22:8500
13partition:
14  default-shard-count: 3

Node 2 (192.168.1.11) and node 3 (192.168.1.12) use the same file with grpc.host and raft.address changed to their own address:

 1# Node 2
 2grpc:
 3  host: 192.168.1.11
 4raft:
 5  address: 192.168.1.11:8610
 6  peers-list: 192.168.1.10:8610,192.168.1.11:8610,192.168.1.12:8610
 7
 8# Node 3
 9grpc:
10  host: 192.168.1.12
11raft:
12  address: 192.168.1.12:8610
13  peers-list: 192.168.1.10:8610,192.168.1.11:8610,192.168.1.12:8610

To put all three PD nodes on one machine for testing, give each node its own pd.data-path and its own ports, for example raft 8610/8611/8612, gRPC 8686/8687/8688 and REST 8620/8621/8622.

In Docker bridge networking the same configuration comes from environment variables and uses container hostnames instead of IP addresses:

 1# Share the same secret across PD nodes; inject it from private environment variables
 2HG_PD_AUTH_SECRET_KEY: ${HG_PD_AUTH_SECRET_KEY:?set HG_PD_AUTH_SECRET_KEY}
 3
 4# pd0
 5HG_PD_GRPC_HOST: pd0
 6HG_PD_RAFT_ADDRESS: pd0:8610
 7HG_PD_RAFT_PEERS_LIST: pd0:8610,pd1:8610,pd2:8610
 8HG_PD_INITIAL_STORE_LIST: store0:8500,store1:8500,store2:8500
 9HG_PD_INITIAL_STORE_COUNT: 3
10
11# pd1
12HG_PD_GRPC_HOST: pd1
13HG_PD_RAFT_ADDRESS: pd1:8610
14HG_PD_RAFT_PEERS_LIST: pd0:8610,pd1:8610,pd2:8610
15
16# pd2
17HG_PD_GRPC_HOST: pd2
18HG_PD_RAFT_ADDRESS: pd2:8610
19HG_PD_RAFT_PEERS_LIST: pd0:8610,pd1:8610,pd2:8610

5 Start and Stop

5.1 Start PD

In the PD installation directory, execute:

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

The script requires Java 17 or later on PATH or in JAVA_HOME (Java ≥ 11 on 1.7.0). It exits without doing anything if it finds a Java process already using this installation’s conf directory.

The lifecycle details below describe current master builds. The downloaded 1.7.0 launcher does not include those repairs. Supported flags, with GC version limits noted below:

Master builds accept g1, G1, zgc and ZGC. The downloaded 1.7.0 launcher accepts only zgc or ZGC as explicit choices; -g g1, -g G1 and other values abort startup. Omit -g for the default path. For rejected values, inspect logs/hugegraph-pd-stdout.log.

The -d flag controls 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 or 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.

Each flag also has an environment variable equivalent: DAEMON, GC_OPTION, USER_OPTION and OPEN_TELEMETRY. Setting JAVA_OPTIONS replaces the computed heap settings entirely; otherwise the script sizes the heap between 512 MB and 32 GB from available memory. Setting STDOUT_MODE=true leaves the JVM output on stdout instead of redirecting it to logs/hugegraph-pd-stdout.log, which is what the Docker image does.

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)

The process id is written to bin/pid.

5.2 Stop PD

In the PD installation directory, execute:

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

The script reads bin/pid, sends the process a termination signal, waits up to 30 seconds for it to exit, and removes the pid file. If bin/pid is missing it reports that and exits successfully.

6 Startup Order in a Distributed Cluster

Start the components in this order:

1. All PD nodes. Form the Raft group and elect a leader. Check GET /v1/ready on each node; start Store only after HTTP 200 with ready:true. /v1/health checks REST listener liveness only.
2. All Store nodes. Register with PD; wait for /v1/stores to show every target Store as Up.
3. All Server nodes. Start after PD and Store are ready.

sequenceDiagram
    participant Operator
    participant PD
    participant Store
    participant Server
    Operator->>PD: GET /v1/ready (check each PD)
    PD-->>Operator: HTTP 200 and ready=true
    Operator->>Store: Start Store
    Store->>PD: gRPC registration and heartbeat
    Operator->>PD: GET /v1/stores (Basic authentication)
    PD-->>Operator: Every target Store is Up
    Operator->>Server: Start Server
    Server->>PD: gRPC partitions and discovery
    Server->>Store: gRPC graph data access

Master Compose waits on PD /v1/health through Store depends_on: condition: service_healthy, and on Store REST liveness before Server. Server also polls PD /v1/stores for an Up Store before starting. Therefore, docker compose up --wait does not replace PD Raft readiness and Store registration checks.

PD is also the last component to stop: shut down Server, then Store, then PD.

7 Verification

7.1 REST API Authentication

Current master requires HTTP Basic Authorization for all PD REST paths except /actuator/*, /v1/health, /v1/ready, and /v1/prom/targets/*. Username must be hg, store, hubble, or vermeer, and password must equal auth.secret-key. A missing secret or wrong password returns HTTP 401. Query Stores using the same secret configured at PD startup:

1{"status": -1, "error": "Unauthorized"}

1curl -u "store:${HG_PD_AUTH_SECRET_KEY:?Set the PD deployment secret first}" \
2  http://localhost:8620/v1/stores

bin/wait-storage.sh uses the same credentials through PD_AUTH_USER and PD_AUTH_PASSWORD. Release 1.7.0 checks only internal service usernames and does not compare passwords; do not apply this older behavior to master builds.

7.2 Health Checks

Unauthenticated GET /v1/health returns 200 with an empty body, confirming only PD REST listener startup:

1curl -i http://localhost:8620/v1/health

Spring Boot Actuator also provides a readable health response:

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

Actuator {"status":"UP"} does not confirm an available PD Raft leader. Master GET /v1/ready returns HTTP 200 with ready:true when the PD Raft node is active and sees a leader; otherwise it returns HTTP 503 with ready:false:

1curl -i http://localhost:8620/v1/ready

7.3 Cluster and member status

Check the PD members and which node is the Raft leader:

1curl -u "store:${HG_PD_AUTH_SECRET_KEY:?Set the PD deployment secret first}" \
2  http://localhost:8620/v1/members

The response carries pdList, the elected pdLeader, numOfService, numOfNormalService and a stateCountMap. In a healthy 3-node PD cluster numOfService and numOfNormalService are both 3 and exactly one member has role: "Leader".

GET /v1/cluster returns the same member list together with the Store list, graph list and overall cluster state, and GET / returns a short summary (leader address, cluster state, member count, store count, graph count, partition count).

7.4 Store status

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

1curl -u "store:${HG_PD_AUTH_SECRET_KEY:?Set the PD deployment secret first}" \
2  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.7.0/apache-hugegraph-store-incubating-1.7.0/lib/hg-store-node-1.7.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}

7.5 Other REST endpoints

All paths below are relative to http://<pd-host>:8620 and need the Basic header from section 7.1 unless noted.

The two log endpoints take a time range as {"startTime": "...", "endTime": "..."}; yyyy-MM-dd HH:mm:ss and yyyy-MM-dd are among the accepted formats.

PD registers its own meters under the hg prefix, so /actuator/prometheus exposes hg_up, hg_graphs, hg_stores and hg_terms alongside the standard JVM metrics, plus per-graph partition and size meters once graphs exist.

In versions after 1.7.0, PD also exports, for each registered store, hg_store_state{store="<id>",state="<state>"}, which is 1 for the store’s current state (Unknown, Pending, Up, Offline, Exiting or Tombstone) and 0 for the others, and hg_store_leader_count{store="<id>"}, the number of shard groups whose leader is on that store. A rebuilt Store reports 0 leaders until leadership moves back to it. Every PD member reads the same replicated metadata, so select one instance before aggregating these series.

3 - HugeGraph-Store Quick Start

1 HugeGraph-Store Overview

HugeGraph-Store is the storage node component of HugeGraph’s distributed version, responsible for actually storing and managing graph data. It works in conjunction with HugeGraph-PD to form HugeGraph’s distributed storage engine, providing high availability and horizontal scalability.

Each Store node keeps graph data in RocksDB and replicates it with Raft (JRaft): every partition is a separate Raft group, so a partition survives the loss of a minority of its replicas. Store nodes do not know about each other directly. They register with PD, receive their partition assignment from PD, and report state back over a heartbeat. HugeGraph-Server reaches Store over gRPC after looking up partition locations in PD.

2 Prerequisites

2.1 Requirements

• Operating System: Linux or macOS (Windows has not been fully tested)
• Java version: Java 17 for HugeGraph 1.8.0+ (the Maven build accepts only JDK 17; the start script rejects older runtimes; 1.7.0 is the last release supporting Java 11)
• Maven version: ≥ 3.6.3 (for building from source)
• Deploy HugeGraph-PD first for multi-node deployment

3 Deployment

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

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

3.1 Download the tar package

Apache downloads currently provide the complete 1.7.0 binary bundle containing PD, Store, and Server, without a separate Store binary. Verify version, signatures, and SHA512 on the official download page. This historical incubating release retains incubating in archive and directory names:

1# Historical release 1.7.0 retains incubating in filenames and directories
2curl -fLO --connect-timeout 10 --max-time 1800 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-store-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 Store directory and complete distribution package are located at
 9#    hugegraph-store/apache-hugegraph-store-{version}
10#    target/apache-hugegraph-{version}.tar.gz

To build Store alone instead of the whole repository, build hugegraph-struct first, because Store depends on it:

1mvn install -pl hugegraph-struct -am -DskipTests
2mvn clean package -pl hugegraph-store/hg-store-dist -am -DskipTests

The assembled directory contains only bin/, conf/ and lib/hg-store-node-{version}.jar.

3.3 Docker Deployment

HG_STORE_* mappings are current master features, absent from Server tag 1.7.0. These Docker examples require PD, Store, and HStore Server images built from the same current master source with matching local tags:

1# Run from the HugeGraph repository root
2docker build -f hugegraph-pd/Dockerfile -t hugegraph/pd:local .
3docker build -f hugegraph-store/Dockerfile -t hugegraph/store:local .
4docker build -f hugegraph-server/Dockerfile-hstore -t hugegraph/server:local .

Before first startup, create .env in docker/ following the authentication environment instructions. The procedure uses umask 077 and refuses to overwrite existing files. Keep an existing .env and add missing entries. Never regenerate HG_PD_AUTH_SECRET_KEY for initialized data directories. Although .gitignore excludes this file, do not commit it. In every new shell, load the same file from docker/ before Compose or PD REST commands:

1# Run from the HugeGraph repository root
2cd docker
3set -a; . ./.env; set +a
4: "${HG_PD_AUTH_SECRET_KEY:?Set HG_PD_AUTH_SECRET_KEY in .env}"
5# Start PD, Store, and Server without optional Hubble
6HUGEGRAPH_VERSION=local HUGEGRAPH_PULL_POLICY=never \
7  docker compose -f docker-compose-hstore.yml \
8  up -d --wait pd store server

Load the same secret before subsequent restarts or PD REST calls; do not regenerate it for initialized directories. Explicitly include HUGEGRAPH_VERSION=local and HUGEGRAPH_PULL_POLICY=never in every Compose lifecycle command.

To start Hubble, use the topology-specific untracked configuration: minimal docker-compose-hstore.yml mounts conf/hubble/hstore.local.properties; HA docker-compose-3pd-3store-3server.yml mounts conf/hubble/hstore-ha.local.properties. The README initialization creates both files with the shared PD secret. If missing or requiring updates, load existing .env from docker/ and run:

1set -a; . ./.env; set +a
2./set-hubble-pd-password.sh hstore      # Minimal topology
3./set-hubble-pd-password.sh hstore-ha  # HA topology

Multi-node service names are pd0–pd2, store0–store2, and server0–server2. This master Compose file also requires matching locally built images; do not mix HUGEGRAPH_VERSION=1.7.0 release images with master Compose.

To run master-built Store alone, replace example addresses with actual routable Store and PD addresses:

1docker run -d \
2  -p 8520:8520 -p 8500:8500 -p 8510:8510 \
3  -e HG_STORE_PD_ADDRESS=192.168.1.10:8686 \
4  -e HG_STORE_GRPC_HOST=192.168.1.20 \
5  -e HG_STORE_RAFT_ADDRESS=192.168.1.20:8510 \
6  -v /path/to/storage:/hugegraph-store/storage \
7  --name hugegraph-store \
8  hugegraph/store:local

Current Master Docker Environment Variables:

The master entrypoint writes these values into SPRING_APPLICATION_JSON, overriding image conf/application.yml. Other options still come from that file and application-pd.yml; Java runs in the foreground. Deprecated PD_ADDRESS, GRPC_HOST, and RAFT_ADDRESS remain supported with warnings.

PD and Store Docker HEALTHCHECK use /v1/health, confirming only local REST responses. Compose depends_on uses the same startup gate; separately verify PD /v1/ready and Up Store state in /v1/stores. Store defaults to STDOUT_MODE=true; its Dockerfile declares only EXPOSE 8520, so publish gRPC 8500 and Raft 8510 separately if needed outside the Docker network.

4 Configuration

Store reads two files under conf/. Release 1.7.0 sources: application.yml, application-pd.yml. Master sources: application.yml, application-pd.yml. Master places RocksDB settings in the second file, included through spring.profiles.include: pd; startup selects application.yml.

• application.yml: Main PD address, ports, Raft, and data path settings.
• application-pd.yml: Included through spring.profiles.include: pd; RocksDB memory and Actuator exposure.

4.1 application.yml

The following tables were checked against distribution values and Java defaults at Server master commit 2f827d6e8c9c62ae858f2fc122b3a192d015e2f4. Use tagged configuration for release 1.7.0 without replacing it with another version’s files.

4.2 application-pd.yml

This file contains only rocksdb and Actuator exposure settings.

4.3 Configuration reference

“Master distribution value” comes from the two master files above. “Code default” is the fallback when a key is absent; rely on code defaults for options omitted from the distribution files.

Core

Raft

Storage and labels

RocksDB

Any other option defined in org/apache/hugegraph/rocksdb/access/RocksDBOptions.java can be added under the same rocksdb: block, for example rocksdb.max_background_jobs, rocksdb.level0_file_num_compaction_trigger or rocksdb.bloom_filter_bits_per_key.

Thread pools

gRPC callback queue (1.8.0)

Store uses an unbounded queue for gRPC callbacks so that a full queue does not discard cancellation or completion notifications and leave requests unfinished. You can keep thread.pool.grpc.queue in the configuration, but it no longer limits this queue.

thread.pool.grpc.core and thread.pool.grpc.max still configure the thread pool. Because callbacks can continue to queue, a backlog normally does not grow the pool from core to max; increasing max alone does not increase callback processing capacity.

Sustained overload can still grow the queue and increase memory usage. Limit client concurrency and size the scan and query worker pools for the node’s resources; do not rely on thread.pool.grpc.queue for load control. Version 1.7.0 still uses the configured gRPC queue capacity.

Query pushdown

Background jobs

Built-in PD mode

Only for single-node development and debugging, activated by app.fake-pd: true. The node then plays PD’s role itself and ignores pdserver.address.

Diagnostics

Starting with HugeGraph 1.8.0, Store HTTP activation (GET /v1/arthasstart) is disabled and returns 403. Legacy configuration fields are kept only for compatibility. Run the bundled script as the service OS user on the host to diagnose the running JVM (official container images include JDK 17):

1bin/arthas.sh

For multiple processes on one host, specify --pid <PID> --telnet-port 3659. For command options, authentication, and security practices, see Start the Arthas agent.

4.4 Per-node changes

For multi-node deployment, you need to modify the following configurations for each Store node:

1. grpc.host and grpc.port (the address other components dial)
2. raft.address (Raft protocol address)
3. server.port (REST port)
4. app.data-path (data storage path)

pdserver.address is the same on every node, it lists the whole PD cluster.

5 Start and Stop

5.1 Start Store

Ensure that the PD service is already started, then in the Store installation directory, execute:

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

The lifecycle and timeout details below describe master builds that include launcher script repairs. The downloaded 1.7.0 launcher does not include those repairs. The script accepts four flags, with GC version limits noted below:

Master builds accept g1, G1, zgc and ZGC. The downloaded 1.7.0 launcher accepts only zgc or ZGC as explicit choices; -g g1, -g G1 and other values abort startup. Omit -g for the default path. For rejected values, inspect logs/hugegraph-store-server.log.

Daemon mode:

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

JVM memory, unless you set JAVA_OPTIONS yourself: -Xms512m, and -Xmx set to half the free memory, clamped to the 512 MB to 2048 MB range. The script also adds -XX:MetaspaceSize=256M, a heap dump on out-of-memory into logs/, and a rolling GC log at logs/gc.log. Production nodes normally need a much larger heap, so pass one explicitly, for example -j "-Xmx32g -Xms32g".

The script refuses to start if ulimit -n or ulimit -u is below 1024, and it preloads jemalloc on x86_64 and arm64 when the shared object can be downloaded and verified.

In master builds, each optional jemalloc download allows 5 seconds to connect and 30 seconds in total. The 1.7.0 helper has no connection or total timeout. A timeout or failed verification follows the existing fallback: startup continues without preloading the downloaded library. Verified cached libraries can still be reused; partial downloads are removed.

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

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

5.2 Stop Store

In the Store installation directory, execute:

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

The script reads bin/pid, signals that process, and waits up to 30 seconds for it to exit before removing the pid file. If bin/pid is missing it exits without doing anything.

5.3 Restart Store

1./bin/restart-hugegraph-store.sh

It sources the stop script and then the start script, and forwards the flags from section 5.1.

5.4 Startup order

1. All PD nodes first. Each Store’s grpc.host:grpc.port must appear in PD pd.initial-store-list, or the node remains Pending instead of Up, blocking partition allocation. On master, verify HTTP 200 with ready:true from every PD /v1/ready first; /v1/health is liveness only.
2. Store next. Registration retries while PD is unreachable, logging store heartbeat error: PD UNREACHABLE.
3. Server last. Every Store should report Up; partitions must be ready before opening or initializing graphs.

Master Compose uses depends_on: condition: service_healthy for local liveness, but PD and Store Docker checks only call /v1/health; they do not confirm Raft quorum or Store registration. Server waits for PD to report at least one Up Store. Operators should still check PD /v1/ready and /v1/stores.

6 Multi-Node Deployment Example

Below is a configuration example for a three-node deployment:

6.1 Three-Node Configuration Reference

• 3 PD nodes
  • raft ports: 8610, 8611, 8612
  • rpc ports: 8686, 8687, 8688
  • rest ports: 8620, 8621, 8622
• 3 Store nodes
  • raft ports: 8510, 8511, 8512
  • rpc ports: 8500, 8501, 8502
  • rest ports: 8520, 8521, 8522

6.2 Store Node Configuration

For the three Store nodes, the main configuration differences are as follows:

Node A:

1grpc:
2  port: 8500
3raft:
4  address: 127.0.0.1:8510
5server:
6  port: 8520
7app:
8  data-path: ./storage-a

Node B:

1grpc:
2  port: 8501
3raft:
4  address: 127.0.0.1:8511
5server:
6  port: 8521
7app:
8  data-path: ./storage-b

Node C:

1grpc:
2  port: 8502
3raft:
4  address: 127.0.0.1:8512
5server:
6  port: 8522
7app:
8  data-path: ./storage-c

All nodes should point to the same PD cluster:

1pdserver:
2  address: 127.0.0.1:8686,127.0.0.1:8687,127.0.0.1:8688

And every PD node should list all three Store gRPC addresses:

1pd:
2  initial-store-list: 127.0.0.1:8500,127.0.0.1:8501,127.0.0.1:8502

6.3 Docker Distributed Cluster Configuration

The distributed Store cluster definition is included in docker/docker-compose-3pd-3store-3server.yml. Each Store node gets its own hostname and environment variables:

 1# store0, published as 8500 (gRPC), 8510 (Raft), 8520 (REST)
 2HG_STORE_PD_ADDRESS: pd0:8686,pd1:8686,pd2:8686
 3HG_STORE_GRPC_HOST: store0
 4HG_STORE_GRPC_PORT: "8500"
 5HG_STORE_REST_PORT: "8520"
 6HG_STORE_RAFT_ADDRESS: store0:8510
 7HG_STORE_DATA_PATH: /hugegraph-store/storage
 8
 9# store1, published as 8501, 8511, 8521
10HG_STORE_GRPC_HOST: store1
11HG_STORE_RAFT_ADDRESS: store1:8510
12
13# store2, published as 8502, 8512, 8522
14HG_STORE_GRPC_HOST: store2
15HG_STORE_RAFT_ADDRESS: store2:8510

The container ports stay 8500/8510/8520 on every node, only the published host ports differ. The PD nodes set HG_PD_INITIAL_STORE_LIST: store0:8500,store1:8500,store2:8500 to match.

Store nodes start only after all PD nodes pass healthchecks (/v1/health), enforced via depends_on: condition: service_healthy.

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

See docker/README.md for the full setup guide.

7 Verify Store Service

Confirm that the Store service is running properly:

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

Actuator {"status":"UP"} confirms local Store application health, without proving registration as Up in PD.

GET /v1/health is the lighter check used by the Docker image and the compose files. It answers HTTP 200 with an empty body, so use curl -fsS and check the exit code rather than the output:

1curl -fsS http://localhost:8520/v1/health && echo OK

7.1 Store REST endpoints

The Store node exposes these read-only endpoints on server.port:

Master Store configuration exposes all Actuator endpoints with management.endpoints.web.exposure.include: "*" and enables Prometheus. These endpoints lack PD REST Basic protection; restrict Store REST network access.

The node also serves maintenance endpoints that change state or run heavy work: PUT /-/state, GET /-/cleaner, GET /v1/partition/dump/{id}, GET /v1/partition/clean/{id}, POST /v1/compat?id=<partition>, POST /raft/options, and the /fix/* and /test/* groups. Use them only for troubleshooting, and keep the REST port off untrusted networks.

7.2 Check registration from PD

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

1curl -u "store:${HG_PD_AUTH_SECRET_KEY:?Set the PD deployment secret first}" \
2  http://localhost:8620/v1/stores

For master builds, PD REST usernames must be hg, store, hubble, or vermeer, and the password must equal PD auth.secret-key. HG_PD_AUTH_SECRET_KEY configures PD and Server in Compose. /v1/health, /v1/ready, /actuator/*, and /v1/prom/targets/* require no authentication. Release 1.7.0 checks only usernames, without comparing passwords; do not use that old behavior for master builds.

If Store is configured successfully, the response should include status information for the current node, and state: "Up" means the node is running normally. A node stuck at Pending is usually missing from PD’s pd.initial-store-list.

The example below shows a single Store node. If all three nodes are configured correctly and running, 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/hugegraph-store/apache-hugegraph-store-{version}/lib/hg-store-node-{version}.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}

7.3 Minimal Graph Read/Write Verification

After Store appears as Up in PD, start an HStore-backed Server connected to the same PD cluster. See the Server Quick Start. Once GET /versions responds and the default hugegraph graph is loaded, create a property key, vertex label, and vertex, then read it:

 1SERVER_URL=http://localhost:8080
 2GRAPH_URL="$SERVER_URL/graphspaces/DEFAULT/graphs/hugegraph"
 3
 4# Names must be unique within the graphspace; choose new names if they already exist
 5curl -fsS -X POST "$GRAPH_URL/schema/propertykeys" \
 6  -H 'Content-Type: application/json' \
 7  -d '{"name":"pd_store_demo_name","data_type":"TEXT","cardinality":"SINGLE","properties":[]}'
 8
 9curl -fsS -X POST "$GRAPH_URL/schema/vertexlabels" \
10  -H 'Content-Type: application/json' \
11  -d '{"name":"pd_store_demo_vertex","id_strategy":"CUSTOMIZE_STRING","properties":["pd_store_demo_name"],"primary_keys":[],"nullable_keys":[]}'
12
13curl -fsS -X POST "$GRAPH_URL/graph/vertices" \
14  -H 'Content-Type: application/json' \
15  -d '{"id":"pd-store-demo-1","label":"pd_store_demo_vertex","properties":{"pd_store_demo_name":"stored in HStore"}}'
16
17curl -fsS "$GRAPH_URL/graph/vertices/%22pd-store-demo-1%22"

The final response should contain vertex ID pd-store-demo-1 and property pd_store_demo_name. If Server authentication is enabled, add credentials to each request.

4 - Deploy HugeGraph with Helm

This guide covers HugeGraph 1.8.0 and later, using Helm 3.10+ with OCI support and Kubernetes (K8s) 1.23+. Install hugegraph-helm from GHCR or Docker Hub. Chart and HugeGraph versions are maintained separately: for example, a 0.2.x Chart can deploy a 1.8.x service.

Artifact Hub helps you find the Chart, browse versions and read installation instructions. The packages themselves are downloaded from GHCR or Docker Hub. See the chart README for settings and source-based development, and the operations reference for lifecycle procedures.

1 Install

Choose either registry; GHCR is recommended for public CI. For local lightweight testing, use the single-node preset.

1CHART=oci://ghcr.io/hugegraph/hugegraph-helm
2kubectl config current-context
3kubectl get nodes
4kubectl get storageclass
5helm install hugegraph "$CHART" --devel -n hugegraph \
6  --create-namespace --wait --timeout 15m

1CHART=oci://registry-1.docker.io/hugegraph/hugegraph-helm
2kubectl config current-context
3kubectl get nodes
4kubectl get storageclass
5helm install hugegraph "$CHART" --devel -n hugegraph \
6  --create-namespace --wait --timeout 15m

1# For local testing (Minikube, Kind): install the Chart downloaded below
2CHART=oci://ghcr.io/hugegraph/hugegraph-helm
3helm pull "$CHART" --devel --untar
4helm install hugegraph ./hugegraph-helm -n hugegraph \
5  -f ./hugegraph-helm/values-single.yaml \
6  --create-namespace --wait --timeout 10m

The single-node preset replaces the default installation with one replica per component and relaxed scheduling constraints.

2 Modes and entry points

The extracted package is rooted at hugegraph-helm/; the source directory remains helm/hugegraph/.

mode: easy is the default. Server and Hubble use automatic NodePorts; PD stays ClusterIP. HTTP works without a domain, certificate or acknowledgement. mode: strict defaults Server/Hubble to ClusterIP and enables NetworkPolicy. Both modes keep authentication and persistence. Explicit component parameters take priority over global parameters, which take priority over mode defaults; explicit false remains an override. The global parameters are persistence.enabled and global.imageRegistry. Strict mode is also available through values-strict.yaml.

1kubectl -n hugegraph get svc hugegraph-server hugegraph-hubble
2kubectl get nodes -o wide
3kubectl -n hugegraph get secret hugegraph-admin \
4  -o jsonpath='{.data.password}' | base64 --decode

Open Hubble on its assigned NodePort and log in as admin with this password. A node need not host the Pod with default externalTrafficPolicy: Cluster. The internal ClusterIP is a virtual Service address, not a node IP; a laptop normally cannot reach it directly. Use kubectl -n hugegraph port-forward svc/hugegraph-hubble 8088:8088 for a local browser at http://127.0.0.1:8088.

Each client Service supports externalTrafficPolicy, loadBalancerClass, loadBalancerIP, loadBalancerSourceRanges, externalIPs and allocateLoadBalancerNodePorts, subject to the cluster/controller’s capabilities. Use LoadBalancer fields with that Service type. NodePort omission or 0 means automatic allocation. Fixed ports are validated against the cluster’s configured range by Kubernetes; the chart does not force 30000–32767. Legacy HTTP acknowledgement fields remain accepted but no longer gate rendering.

Server service identity and graph space

Both server.serviceId and server.graphSpace default to DEFAULT. To register the Server with a specific service name or graph space in PD:

For configuration-only changes, keep the installed Chart version and values. Find the version with helm list and replace the placeholder below:

1helm list -n hugegraph
2CHART=oci://ghcr.io/hugegraph/hugegraph-helm
3CHART_VERSION='<installed-chart-version>'
4helm upgrade hugegraph "$CHART" --version "$CHART_VERSION" -n hugegraph --reuse-values \
5  --set-string server.serviceId=analytics \
6  --set-string server.graphSpace=team_a \
7  --set-string server.testGraphAlias=team_a-demo

A non-default graph space must be created through the PD API before starting its assigned Server. server.testGraphAlias specifies the Gremlin binding checked by helm test (case-sensitive) and does not auto-infer from graphSpace. Do not re-declare service ID or graph space in server.extraEnv.

3 Internal images and storage

Complete examples cover private registries, dynamic storage, seven local PVs, GitOps credentials, API-only deployment and a hostless HTTP Ingress.

Set global.imageRegistry to prefix unqualified image repositories; an explicit registry in a component repository takes precedence. The default mirror inventory is only hugegraph/pd, hugegraph/store, hugegraph/server and hugegraph/hubble, at the configured tags/digests. Store’s PD wait init container and the Helm test reuse Store and Server images respectively, which already contain curl. No separate curl image or runtime package installation is required. Explicit store.waitImage / server.waitImage overrides remain supported.

Storage configuration

For storage, empty storageClassName inherits the cluster default, while "-" explicitly selects no StorageClass. Local PVs require prepared host directories, matching capacities, nodeAffinity and a kubernetes.io/no-provisioner StorageClass; WaitForFirstConsumer binds with the Pod’s scheduling constraints. See the complete seven-volume example before creating resources. For a new temporary installation, set persistence.enabled=false to use emptyDir; component storage flags override it. The chart never replaces a failed PVC with temporary storage and rejects PD/Store storage-mode changes on initialized releases.

Offline installation and internal repositories

Select the latest version, download that Chart and move the .tgz into your network. Install it directly or upload it to an existing OCI or HTTP repository. In air-gapped environments, override the image registry with --set global.imageRegistry=..., see values-internal-registry.yaml.

1CHART=oci://ghcr.io/hugegraph/hugegraph-helm
2CHART_VERSION=$(helm show chart "$CHART" --devel | sed -n 's/^version: //p')
3helm pull "$CHART" --version "$CHART_VERSION"

1# Override the image registry in air-gapped clusters (or use -f values-internal-registry.yaml)
2helm install hugegraph "./hugegraph-helm-${CHART_VERSION}.tgz" -n hugegraph \
3  --set global.imageRegistry=registry.example.com \
4  --create-namespace --wait --timeout 15m

1helm registry login registry.example.com
2helm push "./hugegraph-helm-${CHART_VERSION}.tgz" oci://registry.example.com/charts
3helm install hugegraph oci://registry.example.com/charts/hugegraph-helm \
4  --version "$CHART_VERSION" -n hugegraph \
5  --set global.imageRegistry=registry.example.com \
6  --create-namespace --wait --timeout 15m

1# Upload the same .tgz using your repository's upload mechanism and update index.yaml.
2# For a static HTTP repository, use helm repo index. Native helm push only supports OCI.
3helm repo add hugegraph-internal https://charts.example.com
4helm repo update hugegraph-internal
5helm install hugegraph hugegraph-internal/hugegraph-helm \
6  --version "$CHART_VERSION" -n hugegraph \
7  --set global.imageRegistry=registry.example.com \
8  --create-namespace --wait --timeout 15m

Replace the example registry addresses with your own. The archive contains no container images: mirror all configured container images separately, then override their addresses.

4 Authentication and secrets

Normal Helm installations generate and reuse three credentials: <release>-admin (password), <release>-auth-token (token_secret) and <release>-pd-auth (secret-key). PD REST requires the shared PD secret, supplied to the PD container as HG_PD_AUTH_SECRET_KEY; Server’s storage wait and Hubble read the same credential. It is not a separate user password that must be invented for each Pod.

For GitOps, use fixed encrypted values or pre-created Secrets through pd.auth.existingSecret, server.auth.admin.existingSecret and server.auth.token.existingSecret. existingSecret wins over inline values and is not managed by the chart. The admin password must be printable ASCII without spaces, colons or backslashes; the PD secret must be printable ASCII without surrounding whitespace or backslashes; the JWT signing key must be at least 32 bytes. Offline renderers cannot reuse live generated Secrets through lookup.

The admin Secret is an initial credential. Updating it does not rotate an existing account. Change the password through PUT /graphspaces/DEFAULT/auth/users/admin with {"user_password":"<new-password>"} using the existing credential, update the Secret/source to that same password, then restart the Server Deployment to clear every replica’s auth cache.

Hubble is enabled by default and its current login requires Server authentication. Set hubble.enabled=false for API-only access; optionally also set server.auth.enabled=false for an unauthenticated API. Inactive credential settings may remain in your values file.

5 Upgrade and verification

Use native Helm value reuse to preserve an existing deployment’s UI, entry, storage and credentials:

1helm get values hugegraph -n hugegraph --all
2# Follow the latest version for testing; use --version with a reviewed stable version for production.
3helm upgrade hugegraph "$CHART" --devel -n hugegraph \
4  --reuse-values --wait --timeout 15m
5helm test hugegraph -n hugegraph --logs --timeout 5m

Existing explicit helper images also remain under --reuse-values; add --set-string store.waitImage= --set-string server.waitImage= to reuse component images. Adopt new defaults deliberately with --reset-values and a reviewed file retaining your image, credential, storage and topology settings. Do not treat PD membership, storage or credential changes as ordinary independent overrides; consult the lifecycle reference.

server.storageWaitTimeoutSeconds defaults to 300 and is passed as WAIT_STORAGE_TIMEOUT_S. An unspecified startup probe threshold is derived from that wait plus 150 seconds; an explicit threshold is preserved and must cover the storage wait plus at least 120 seconds of Server startup. A contradictory budget fails rendering with the relevant parameter names. Storage wait timeout is not a JVM memory setting.

The default helm test hook checks connectivity and reads. After installation or recovery, also test a new UI login and your application’s read/write queries. For scheduling, NetworkPolicy, rolling updates and recovery, see Kubernetes operations.

5 - Operate HugeGraph on Kubernetes

This guide accompanies Helm deployment. Detailed lifecycle checks and recovery notes are maintained in the operations reference; all parameters are commented in values.yaml. Commands assume release/namespace hugegraph; substitute the actual workload names if overridden.

1 Storage and private images

The default installation needs seven persistent volumes. Dynamic storage requires a working provisioner; static local storage requires prepared directories and matching PVs on the named nodes. Use the complete examples for all seven local PVs, WaitForFirstConsumer, registry mirrors and GitOps Secrets. An initially Pending PVC with WaitForFirstConsumer can be normal; persistent Pending needs PVC/Pod events and PV matching checks. A bound claim with a missing directory or permission mismatch can fail mounting. Do not replace failed PVCs with temporary data directories.

1kubectl -n hugegraph get pvc,pods
2kubectl -n hugegraph describe pvc <claim-name>
3kubectl -n hugegraph describe pod <pod-name>
4kubectl get pv,storageclass

For ImagePullBackOff, inspect Pod events and registry access/credentials. The default image inventory contains four component images; Store wait and Helm test reuse existing component images with curl already installed. Explicit helper-image overrides must also be mirrored.

2 Ports and health

PD listens on REST 8620, gRPC 8686 and Raft 8610; Store on REST 8520, gRPC 8500 and Raft 8510; Server HTTP on 8080; Hubble HTTP on 8088. Client Services hide individual Pod addresses. NodePort is a separate allocated port on reachable nodes, not the application listener port. PD /v1/ready requires a Raft leader; /v1/health only confirms the listener. Store startup waits for a majority of ready PD peers. Server waits up to server.storageWaitTimeoutSeconds (default 300) before its application startup; adjust it for slow storage bootstrap. No local Helm rendering verifies live cluster reachability, volumes or JVM capacity.

Helm test coverage

helm test validates graph binding on every Server Pod (DEFAULT-hugegraph by default, or configured via server.testGraphAlias), and requires currently visible associated indexes to be in CREATED state. Run it after index creation/rebuild jobs finish, with no schema changes during the test. On HStore, reading an unfinished index can cache its temporary status on other Pods; retries do not refresh that state. Indexed queries on those Pods may keep failing after the job succeeds; replace affected Server Pods only after the jobs finish. The hook does not fix cross-Server schema cache consistency. Its 150-second internal retry window allows transient elections to settle; Helm’s --timeout does not change that window. It reads indexes by ID without refreshing the full index cache; it does not prove index query results or complete schema consistency. For existing data, use --set-file server.testGremlin=assertions.groovy during Helm upgrade to add read-only business assertions on every Pod. The script must use assert or throw on unexpected results; returning false alone does not fail the request. See business query assertions for an example and coverage limits. Without a script, business assertions are reported as skipped. The default hook creates no schema or data. Custom scripts use the hook’s Server credential (admin with auth enabled); read-only execution is not enforced, so supply trusted, read-only assertions.

Server API responses negotiate compression through Accept-Encoding. Gzip-capable clients can request gzip or use curl --compressed; identity or no compression request keeps the response uncompressed. Build a new Server image from the updated source to include this behavior; updating the chart alone does not update an existing image.

PD REST authentication

PD REST uses HTTP Basic auth: hg, store, hubble and vermeer share the PD REST Secret password. Server’s admin account is not a PD REST account and receives 401. For the default release/Secret and a reachable PD REST address:

1PD_SECRET=$(kubectl -n hugegraph get secret hugegraph-pd-auth \
2  -o jsonpath='{.data.secret-key}' | base64 --decode)
3curl --user "hg:${PD_SECRET}" "http://<pd-rest-address>:8620/v1/stores"

The HTTP example assumes a trusted internal network. For other access paths, use an HTTPS gateway or optionally forward the PD Service: kubectl -n hugegraph port-forward service/hugegraph-pd-client 8620:8620, then query http://127.0.0.1:8620.

With pd.auth.existingSecret or a custom pd.auth.key, read the actual Secret and key. Do not use the Server admin password. Variables avoid literal passwords in shell history, but expanded credentials can briefly appear in process arguments. On shared terminals, use curl --user hg to prompt for the password or a private curl config with permissions 600; the credentials guide also covers password-update payloads. Keep credential files out of logs and version control.

3 Scheduling

The default preferred anti-affinity permits scheduling with fewer nodes than replicas. values-cluster.yaml sets required PD/Store anti-affinity, so it needs at least three schedulable nodes. Explicit affinity takes priority over presets. Local PV node affinity must match the workload’s placement constraints; PV capacity declarations do not enforce filesystem quotas. Do not change a persisted PD/Store Raft hostname or port as an ordinary upgrade: those addresses are recorded identities.

4 Partition sharding

At first bootstrap, the chart seeds three shard replicas when there are at least three Stores, and one otherwise. PD persists the partition settings; changing chart values after initialization does not rewrite that metadata. Use the PD configuration API and a coordinated partition patrol for an existing cluster. An explicit shard count must be odd and no greater than Store replicas. See the topology constraints before changing a live cluster; the chart does not migrate existing shard metadata.

5 NetworkPolicy

Easy mode, including the ordinary cluster preset, defaults policies off. Strict mode enables them; explicit networkPolicy.enabled wins in either mode. The cluster network plugin must enforce NetworkPolicy for these resources to have an effect. The generated policies admit component traffic and DNS. External clients and Ingress controllers need suitable networkPolicy.<component>.extraIngress rules; external discovery addresses may need matching extraEgress. An empty list is valid and can block external traffic. Native Kubernetes rules are accepted, including {} to allow all; there is no separate source-acknowledgement gate. Use your actual source addresses/selectors, considering NodePort SNAT and controller behavior.

 1networkPolicy:
 2  enabled: true
 3  server:
 4    extraIngress:
 5      - from:
 6          - ipBlock:
 7              cidr: 10.20.0.0/16
 8        ports:
 9          - protocol: TCP
10            port: 8080
11  hubble:
12    extraIngress:
13      - from:
14          - ipBlock:
15              cidr: 10.20.0.0/16
16        ports:
17          - protocol: TCP
18            port: 8088

6 Rolling Store images safely

Use store.updateStrategy.type=OnDelete for a controlled maintenance rollout, as the cluster preset does. Delete one Store Pod at a time. Before replacing the next, verify the previous Pod is Ready, has a fresh Store heartbeat and each shard group has its full membership and exactly one leader, read from the PD leader. PD’s Up status alone does not prove completed shard recovery. PDBs limit voluntary eviction, not StatefulSet controller disruption. Stop on missing members or leaders. The operations reference summarizes these rollout conditions; it does not provide a complete per-group diagnostic or disk-loss recovery procedure.

A single Store replacement can cause request errors or timeouts while Raft leadership and client routes converge, even with full replicas. There is no zero-error guarantee. Observe application errors as well as shard recovery before continuing; do not blindly retry writes.

PD patrol and leader balance

Partition patrol repairs shard membership; leader balance is a separate manual task and is not scheduled automatically. Before either task, identify the PD leader through authenticated /v1/members (data.pdLeader.restUrl) and confirm its /v1/ready reports isLeader: true. The GET tasks /v1/task/patrolPartitions and /v1/task/balanceLeaders change cluster state; target that confirmed leader with PD REST credentials. Wait for membership recovery and split/move tasks to finish before balancing leaders; Stores must have fresh heartbeats and groups full, healthy membership. A busy task returns body status: 1001. A follower may return empty success, and leader transfers are asynchronous: HTTP 200 or a transfer plan does not prove completion. Recheck /v1/partitions, /v1/stores and application errors before further maintenance. Follow the task procedure for the separate patrol and balance steps; do not loop task requests while maintenance is busy.

7 Disaster recovery

Preserve existing volumes, claim identities and PD membership. Do not delete RocksDB lock files to recover a deployment, or replace persisted membership with freshly generated nodes. A new empty PVC does not restore the data from a lost Store disk. Local disks cannot migrate their files automatically when a node fails. Take backups outside these PVs and test recovery separately. The chart does not implement backup or automatic recovery. The recovery notes describe constraints, not a complete recovery sequence. Before destructive changes, establish and validate a recovery plan for the deployed version and remaining replicas or backups.

8 Scaling

Server replicas are routinely mutable; an HPA also needs CPU requests. Store growth is a coordinated storage/shard operation. PD growth/shrink and Store shrink cannot be handled as ordinary replica changes, because persistent Raft/shard membership must be updated first. Chart upgrade checks reject unsupported identity/membership changes on initialized StatefulSets; fresh installs do not query StatefulSets for upgrade checks. Scale through the documented lifecycle procedure rather than kubectl scale, which can leave Hubble’s Store metrics configuration stale.

9 Running Hubble outside the cluster

Direct mode only needs an externally reachable Server URL. PD discovery also needs externally reachable PD gRPC, and Server addresses registered with PD must be reachable from that external Hubble. Set server.advertiseUrl to a shared reachable Server URL when needed; it affects all discovery clients, including in-cluster Hubble. In-chart Hubble already uses internal service discovery and needs no public PD entry point. HTTP is supported directly; TLS termination remains optional. Hubble remains single-replica and its current login requires Server authentication.

10 When Gremlin fails with Could not rebind

A Server can become Ready and serve REST while Gremlin binding failed during a PD rollout. Run helm test hugegraph -n hugegraph --logs --timeout 5m; the hook checks authenticated graph-bound Gremlin on every Server Pod. Once PD is stable, replace the failing Server Pod and verify again. A test that only calls /versions does not prove graph binding; also check fresh Hubble login and a graph query.

For ERROR: missing required env 'HG_PD_AUTH_SECRET_KEY', inspect the PD Pod’s Secret reference and the corresponding key, not the Secret value in logs. The chart normally injects this shared PD REST credential automatically. Custom containers/manifests must provide the same value to PD and its clients. In GitOps, create the external Secret before workload reconciliation; with ordinary Helm, retain the chart-generated release Secret.