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    builder: org.apache.hugegraph.io.HugeGraphTypeSerializerRegistryBuilder
8    ioRegistries: [org.apache.hugegraph.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)

For complete container setup instructions, refer to the Docker deployment guide.

Run a standalone Server container with the RocksDB backend:

1docker run -itd --name=server -p 8080:8080 hugegraph/hugegraph:1.7.0

1# Preload the built-in sample graph at startup
2docker run -itd --name=server -p 8080:8080 -e PRELOAD="true" hugegraph/hugegraph:1.7.0

1# Enable authentication mode and set the admin password
2docker run -itd --name=server -p 8080:8080 -e PASSWORD="replace-with-your-password" hugegraph/hugegraph:1.7.0

Common container inspection operations:

• Inspect container shell: docker exec -it server bash
• Check startup logs: docker logs -f server
• Verify service health: curl -fsS http://127.0.0.1:8080/versions

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

1# Enter the extracted or built Server directory
2cd apache-hugegraph-*/apache-hugegraph-server-*
3bin/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

   Server images built from current master run as the non-root UID 10001, so a mounted script must be readable by that user.

   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

1# From within the Server directory
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

Choose a deployment method for the HugeGraph-PD component:

• Download released archive — Download the bundled official release package.
• Compile from source — Build the latest master PD module with Maven and Java 17.
• Docker deployment — Run containerized PD for local trials or cluster testing.

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. Clone the source code:

   1git clone https://github.com/apache/hugegraph.git
   2cd hugegraph

2. Build the PD module:

   1# Build only the PD distribution and its dependencies
   2mvn clean package -pl hugegraph-pd/hg-pd-dist -am -DskipTests

3. Locate the distribution output:

   1cd hugegraph-pd/apache-hugegraph-pd-*/
   2ls -la bin conf lib

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:

The mkdir -p and nonrecursive chown below are for a new empty directory. Before reusing data written by a root image, stop PD and run sudo chown -R 10001:10001 /path/to/data once, then start the UID 10001 image.

 1export HG_PD_AUTH_SECRET_KEY="$(openssl rand -hex 24)"
 2# Master-built images run as UID 10001; the host data directory must be writable by it
 3mkdir -p /path/to/data && sudo chown 10001:10001 /path/to/data
 4docker run -d \
 5  -p 8620:8620 -p 8686:8686 -p 8610:8610 \
 6  -e HG_PD_GRPC_HOST=192.168.1.10 \
 7  -e HG_PD_RAFT_ADDRESS=192.168.1.10:8610 \
 8  -e HG_PD_RAFT_PEERS_LIST=192.168.1.10:8610 \
 9  -e HG_PD_INITIAL_STORE_LIST=192.168.1.20:8500 \
10  -e HG_PD_AUTH_SECRET_KEY="$HG_PD_AUTH_SECRET_KEY" \
11  -v /path/to/data:/hugegraph-pd/pd_data \
12  --name hugegraph-pd \
13  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 list master configuration values and code defaults. See the PDConfig implementation for Raft timeouts. Use the original tagged configuration with 1.7.0 binaries and master configuration with master builds. Differences from 1.7.0 are noted below.

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

raft.rpc-connect-timeout and raft.rpc-install-snapshot-timeout exist only in versions after 1.7.0. In 1.7.0, raft.rpc-timeout is also the connect and install-snapshot timeout, and id allocation runs no ReadIndex wait.

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.

It also exposes Raft membership gauges for monitoring and alerting on quorum loss:

• hg_raft_leader: 1 if this PD node is the elected Raft leader, 0 otherwise.
• hg_raft_has_leader: 1 if this PD node observes an active Raft leader (i.e. is part of a quorum), 0 when quorum is lost.
• hg_raft_alive_peers: Number of active Raft peers (including itself) that the leader has heard from within the leader lease timeout; reported as NaN on non-leader follower nodes.

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.

7.6 Store Decommissioning and Drain Lifecycle

Decommissioning a Store node follows a state machine to safely drain partition replicas without service interruption:

1. State Machine Overview:

   • Up: The Store is online, healthy, and accepting new shard allocations and leader roles.
   • Exiting: The Store is actively draining. While in Exiting, the Store continues renewing its heartbeat lease, but PD excludes it from new replica allocation and partition migration targets.
   • Partition Migration: PD schedules background tasks to migrate all shard replicas off the draining store to other eligible active Stores.
   • Tombstone: The Store is permanently retired. Once marked Tombstone, management updates cannot return the Store to an active state.

2. Draining Invocation: Initiate store draining via:

   1curl -X POST http://<pd-host>:8620/v1/store/{storeId} \
   2  -H "Authorization: Basic <credentials>" \
   3  -H "Content-Type: application/json" \
   4  -d '{"storeState": "Exiting"}'

3. Capacity Constraints & Retirement Checks:

   • Capacity Check: Draining checks that remaining eligible active stores satisfy minStoreCount (pd.min-store-count). If remaining capacity is insufficient, PD blocks the transition and rejects the request before state changes. In this case, add eligible Store capacity and resubmit the request.
   • Retirement Criteria: PD keeps the Store in Exiting until its latest heartbeat reports 0 local partition engines AND PD has no remaining shard groups referencing that Store ID.
   • Pre-Deletion Verification: Before deleting the Store Pod or persistent volume, operators must verify remaining shard groups have full Raft membership, complete replicas, and fresh heartbeats.
   • Re-registration Intent Preservation: Re-registering an Exiting Store (e.g. after process restart) preserves the Exiting intent even if its address is in pd.initial-store-list.

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

Choose a deployment method for the HugeGraph-Store component:

• Download released archive — Download the bundled official release package.
• Compile from source — Build the latest master Store module with Maven and Java 17.
• Docker deployment — Run containerized Store nodes for cluster topologies.

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. Clone the source code:

   1git clone https://github.com/apache/hugegraph.git
   2cd hugegraph

2. Build dependent struct and Store module:

   1# Build hugegraph-struct dependency and Store distribution
   2mvn install -pl hugegraph-struct -am -DskipTests
   3mvn clean package -pl hugegraph-store/hg-store-dist -am -DskipTests

3. Locate the distribution output:

   1cd hugegraph-store/apache-hugegraph-store-*
   2ls -la bin conf lib

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:

The mkdir -p and nonrecursive chown below are for a new empty directory. Before reusing data written by a root image, stop Store and run sudo chown -R 10001:10001 /path/to/storage once, then start the UID 10001 image.

 1# Master-built images run as UID 10001; the host data directory must be writable by it
 2mkdir -p /path/to/storage && sudo chown 10001:10001 /path/to/storage
 3docker run -d \
 4  -p 8520:8520 -p 8500:8500 -p 8510:8510 \
 5  -e HG_STORE_PD_ADDRESS=192.168.1.10:8686 \
 6  -e HG_STORE_GRPC_HOST=192.168.1.20 \
 7  -e HG_STORE_RAFT_ADDRESS=192.168.1.20:8510 \
 8  -v /path/to/storage:/hugegraph-store/storage \
 9  --name hugegraph-store \
10  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. 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

RocksDB memory budget sizing rules

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:MaxDirectMemorySize equal to that heap, -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 together with a direct-memory cap, for example -j "-Xmx32g -Xms32g -XX:MaxDirectMemorySize=2g". Without the cap the JVM allows as much direct memory as the 32 GB heap, the RocksDB budget counts it, and on a host with less than about 66 GB it falls to the 256 MiB floor.

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:

GET /-/lifecycle reports the process lifecycle status as JSON, such as {"status":0,"text":"STARTED"}. The text field has four possible values:

• STARTING: Spring application context or gRPC service is still initializing;
• STARTED: Spring application is ready (ApplicationReadyEvent) and gRPC service is running;
• STOPPING: Process shutdown has initiated (ContextClosedEvent takes precedence);
• UNAVAILABLE: gRPC service stopped or terminated unexpectedly before shutdown.

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.4.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 selects 1 PD + 1 Store + 1 Server using HStore, plus Hubble, with relaxed scheduling constraints. It leaves SeaTunnel and Vermeer disabled.

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 full NetworkPolicy isolation. Enabled SeaTunnel and Vermeer native HTTP/UI default to NodePort in easy mode and ClusterIP in strict mode; both require login. Internal RPC, Worker HTTP and SeaTunnel member ports remain private. 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.

The base PD/Server/Hubble client Services support 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.

Optional engines: disabled by default

By default, the Chart provisions only the core graph services (PD + Store + Server + Hubble). For data migration and distributed memory graph computing, the Chart offers SeaTunnel and Vermeer as native optional engines, both disabled by default:

Enable either engine by setting its enabled key to true in values. Their administrator passwords are generated independently from Server. For seatunnel.service.type and vermeer.service.type, null inherits the mode default: NodePort in easy mode, ClusterIP in strict mode. An explicit ClusterIP stays private; an explicit NodePort, including in strict mode, exposes authenticated HTTP/UI. Clear an older explicit ClusterIP override to null to inherit easy mode. With service.nodePort omitted or null, Kubernetes assigns the port. The engines’ standalone / cluster topologies are independent of these access settings.

1helm install hugegraph ./hugegraph-helm -n hugegraph --create-namespace \
2  -f ./hugegraph-helm/values-single.yaml \
3  --set seatunnel.enabled=true --set seatunnel.mode=standalone \
4  --wait --timeout 30m

1helm install hugegraph ./hugegraph-helm -n hugegraph --create-namespace \
2  -f ./hugegraph-helm/values-single.yaml \
3  --set vermeer.enabled=true --set vermeer.mode=standalone \
4  --wait --timeout 20m

1hugegraph-helm/
2  examples/
3    values-vermeer-standalone.yaml # Standalone preset (Master and Worker combined in one Pod)
4    values-vermeer-cluster.yaml    # Cluster preset (1 dedicated Master Pod + 3 distributed Worker Pods)
5  docs/
6    vermeer.md                     # Advanced algorithm parameters, API mapping and operations

PD metadata namespace

The top-level metadataCluster parameter (default hg-test) specifies the PD metadata cluster prefix. The Chart injects this value into Server HG_SERVER_CLUSTER and Store PD_CLUSTER, ensuring Store correctly locates the Schema initialized by Server when processing Vermeer graph scans.

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.

Enabled SeaTunnel additionally needs its configured apache/seatunnel image; enabled Vermeer uses the published build pinned above. Vermeer reuses that image for Master, Worker and service-token initialization. Mirror every enabled image and explicit helper override. For a custom Vermeer image, also update vermeer.image.digest, or explicitly clear it when selecting by tag; a nonempty digest takes priority.

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.

Vermeer uses separate Master and Worker claims, even in its single-Pod mode: two additional volumes in standalone, or one Master volume plus one per Worker in cluster mode. With the default base topology this means 9 or 11 volumes respectively. The small HugeGraph preset plus standalone Vermeer needs 5. The seven-volume local example covers only the base installation. SeaTunnel checkpoints remain temporary local files.

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.

Enabled optional engines always require native login, including in easy mode. Newly generated administrator passwords use 6 random alphanumeric characters in easy mode or 16 in strict mode. SeaTunnel uses HTTP Basic, while Vermeer uses Secret <release>-vermeer-admin and its Admin credential login. Upgrades retain existing passwords, including when changing mode; mode changes do not rotate them automatically. Vermeer password sources are vermeer.auth.admin.password or vermeer.auth.admin.existingSecret/key; only Master reads that password. Access native administration according to the final Service type: NodePort connects via the node IP and assigned port, while ClusterIP uses port-forwarding. Hubble service credentials are automatic.

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.

PD, Store and Server images built from current master run as UID/GID 10001. The chart gives the PD and Store pods fsGroup: 10001 (with fsGroupChangePolicy: OnRootMismatch) unless their podSecurityContext sets fsGroup, also when --reuse-values keeps an older release’s empty value, so they can write PVCs created by older images, which ran as root.

Switch PD and Store to images built from this version in the same rollout that first applies fsGroup, so the kubelet changes the volume ownership right before the 10001 image starts. Do not run images that still run as root with this chart first, for example a latest that has not moved to this version: files they create stay owned by root, and OnRootMismatch checks only the volume root, so it does not fix them later. Pin pd.image and store.image to a build from this version rather than relying on latest. A non-empty image.digest wins over image.tag, and --reuse-values keeps an existing digest, so a release pinned by digest must change the digest, not only the tag.

If a release already ran root images with fsGroup set, roll out the first 10001 image together with a one-time recursive ownership change. Set the images in the same command, so the recursive change runs for the 10001 image rather than for a pinned root image. The example clears any reused digest so the tag applies; a release pinned by digest sets pd.image.digest and store.image.digest to the digests of this version’s images instead:

1helm upgrade hugegraph "$CHART" --devel -n hugegraph --reuse-values \
2  --set pd.image.tag=<this-version> \
3  --set store.image.tag=<this-version> \
4  --set-string pd.image.digest= \
5  --set-string store.image.digest= \
6  --set pd.podSecurityContext.fsGroupChangePolicy=Always \
7  --set store.podSecurityContext.fsGroupChangePolicy=Always \
8  --wait --timeout 15m

Before switching the policy back, check that every PD and Store Pod runs the 10001 image you set, not an older root image:

1kubectl get pods -n hugegraph \
2  -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.containers[*].image}{"\n"}{end}'

--reuse-values keeps Always, which walks the whole volume on every Pod start, so set the policy back once those Pods are running:

1helm upgrade hugegraph "$CHART" --devel -n hugegraph --reuse-values \
2  --set pd.podSecurityContext.fsGroupChangePolicy=OnRootMismatch \
3  --set store.podSecurityContext.fsGroupChangePolicy=OnRootMismatch \
4  --wait --timeout 15m

Volumes whose CSI driver ignores fsGroup (for example many NFS drivers) and hostPath volumes need a one-time chown -R 10001:10001 instead.

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.

6 Deploy and Use SeaTunnel (Optional Engine)

SeaTunnel is an optional data integration engine supported by HugeGraph, disabled by default. When enabled, Helm provisions a persistent SeaTunnel Zeta engine alongside a task Web dashboard within the same release. The official apache/seatunnel:3.0.0 image comes with built-in HugeGraph connectors (Source and Sink), requiring no custom image builds or plugin installation.

 1helm/hugegraph/
 2  examples/
 3    values-seatunnel-standalone.yaml # Standalone preset (1 Hybrid node, lightweight for local/dev use)
 4    values-seatunnel-cluster.yaml    # Cluster preset (multiple Hybrid nodes for distributed parallelism)
 5    seatunnel/
 6      hugegraph-sink.conf            # Import sample: batch inserts test vertices into HugeGraph
 7      hugegraph-source.conf          # Export sample: reads graph data from HugeGraph to stdout/logs
 8      clone/                         # Full graph migration configs
 9        copy-schema.py               # Automated Schema synchronization script
10        person.conf / knows.conf     # Per-label vertex and edge migration job definitions

flowchart TB
    A["External Data Source / Remote Graph"] --> ST
    subgraph Release["Same Helm Release"]
        ST["SeaTunnel Zeta<br/>Hybrid Node"] -->|Read / Write| HG["HugeGraph<br/>Server + PD + Store"]
    end
    U["Operators"] -->|Web UI / REST (HTTP Basic)| ST

6.1 Choose Standalone or Cluster Mode

SeaTunnel uses a Hybrid node architecture where each node handles both job scheduling and execution:

• Standalone Mode: Starts 1 persistent node, minimizing memory footprint for development and lightweight jobs.
• Cluster Mode: Starts multiple uniform nodes forming a cluster for distributed high availability and higher throughput.

SeaTunnel scaling is fully decoupled from the HugeGraph cluster topology. Install from the extracted chart directory or repository root by combining presets:

1helm install hugegraph ./hugegraph-helm -n hugegraph --create-namespace \
2  -f ./hugegraph-helm/values-single.yaml \
3  -f ./hugegraph-helm/examples/values-seatunnel-standalone.yaml \
4  --wait --timeout 30m

1helm install hugegraph ./hugegraph-helm -n hugegraph --create-namespace \
2  -f ./hugegraph-helm/values-single.yaml \
3  -f ./hugegraph-helm/examples/values-seatunnel-cluster.yaml \
4  --wait --timeout 30m

6.2 Access Web UI and Authentication

SeaTunnel inherits the global mode setting when seatunnel.service.type: null: easy defaults to NodePort, strict to ClusterIP. An explicit ClusterIP stays private; explicit NodePort, including in strict mode, exposes HTTP/UI with the same required login. Clear an older explicit ClusterIP override to null to inherit easy mode. Omit seatunnel.service.nodePort or use null for automatic allocation. The standalone / cluster topology does not change this access choice:

1kubectl -n hugegraph get svc hugegraph-seatunnel \
2  -o jsonpath='{.spec.ports[?(@.name=="http")].nodePort}{"\n"}'
3kubectl get nodes -o wide
4# Open browser: http://<NodeIP>:<NodePort>/#/overview

1kubectl -n hugegraph port-forward svc/hugegraph-seatunnel 8081:8080
2# Open locally: http://127.0.0.1:8081/#/overview

The Web dashboard and REST APIs require independent HTTP Basic authentication in both modes, distinct from HugeGraph Server credentials. The username is admin; newly generated passwords use 6 random alphanumeric characters in easy mode or 16 in strict mode. Upgrades and mode changes retain the existing password. Read it from the release Secret:

1kubectl -n hugegraph get secret hugegraph-seatunnel-auth \
2  -o jsonpath='{.data.password}' | base64 --decode

6.3 Run Pre-configured Example Jobs

The Chart mounts sample jobs inside the SeaTunnel Pod, pre-configured with environment variables referencing the in-release Server address, graph name, and credentials:

1. Prepare Graph: Ensure an empty target graph exists via Hubble or REST API (default DEFAULT/graph_a).

2. Run Import Job: Ingest 10 sample vertices under the seatunnel_demo_person label:

   1kubectl -n hugegraph exec sts/hugegraph-seatunnel -- \
   2  /opt/seatunnel/bin/seatunnel.sh --master cluster \
   3  --config /opt/seatunnel/config/hugegraph-sink.conf

3. Verify with Export Job: Run the Source sample job to read back the same vertices and print them to standard logs:

   1kubectl -n hugegraph exec sts/hugegraph-seatunnel -- \
   2  /opt/seatunnel/bin/seatunnel.sh --master cluster \
   3  --config /opt/seatunnel/config/hugegraph-source.conf

Inspect job status and DAG progress in real time on the Web dashboard. To use custom graphs or credentials, override environment variables under seatunnel.env or mount external configurations via seatunnel.config.

6.4 Full Migration and Topology Switches

• Topology Switch: Switch between standalone and cluster modes by updating values and running helm upgrade. Since the engine process restarts, complete all running batch jobs before switching.
• Full Graph Migration: Follow the sequence Schema metadata → Vertices → Edges. See examples/seatunnel/clone/ for automated migration scripts and configs. When migrating fields with DATE types, explicitly specify matching server timezones (e.g. timeZone = "UTC") in the Sink config to prevent timezone shift. See the SeaTunnel Source migration guide for details.

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 base 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. Enabled SeaTunnel adds its configured apache/seatunnel image. Enabled Vermeer uses hugegraph/vermeer:helm-30b67d93e7d0, pinned by digest and reused by Master, Worker and token initialization. Official publishing runs record the source and image digest; see the Vermeer deployment guide. Custom image overrides must also update vermeer.image.digest, or explicitly clear it to select by tag; digest takes priority. The base local-PV example omits Vermeer claims: standalone adds two, while cluster adds one Master claim plus one per Worker (four additional claims by default).

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.

Preserve the metadata namespace

metadataCluster: hg-test sets the PD metadata namespace prefix (injected into Server HG_SERVER_CLUSTER and Store PD_CLUSTER). It is not a Raft group name; changing it will not automatically migrate existing metadata. Never arbitrarily change this prefix on an initialized cluster to enable Vermeer. If Server REST queries succeed but Vermeer scanning Store fails with Schema missing or no such vertex label, check that the namespace prefix matches across all components.

If a legacy environment used a custom prefix, record it explicitly on the Server Deployment before upgrading:

1kubectl -n hugegraph annotate deployment hugegraph-server \
2  hugegraph.apache.org/metadata-cluster='<verified-existing-namespace>'

and ensure metadataCluster matches this value in your values file. For Store nodes using store.updateStrategy.type=OnDelete, follow the rolling upgrade procedure to recreate Pods one by one so the new settings take effect.

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"