From 4695976f09297aac87438b42133ef714fe8b941b Mon Sep 17 00:00:00 2001 From: imbajin Date: Sun, 8 Nov 2026 12:47:02 +0800 Subject: [PATCH 1/8] docs: streamline navigation and agent context --- .editorconfig | 5 +- .serena/README.md | 27 ++ .serena/memories/architecture_and_modules.md | 59 +-- .../memories/code_style_and_conventions.md | 28 -- .../ecosystem_and_related_projects.md | 24 - .../implementation_patterns_and_guidelines.md | 49 -- .serena/memories/key_file_locations.md | 59 +-- .serena/memories/project_overview.md | 37 +- .serena/memories/suggested_commands.md | 59 --- .serena/memories/task_completion_checklist.md | 37 -- AGENTS.md | 74 ++- README.md | 441 +++-------------- docs/README.md | 54 +++ helm/hugegraph/README.md | 446 +++--------------- helm/hugegraph/docs/README.md | 49 ++ 15 files changed, 371 insertions(+), 1077 deletions(-) create mode 100644 .serena/README.md delete mode 100644 .serena/memories/code_style_and_conventions.md delete mode 100644 .serena/memories/ecosystem_and_related_projects.md delete mode 100644 .serena/memories/implementation_patterns_and_guidelines.md delete mode 100644 .serena/memories/suggested_commands.md delete mode 100644 .serena/memories/task_completion_checklist.md create mode 100644 docs/README.md create mode 100644 helm/hugegraph/docs/README.md diff --git a/.editorconfig b/.editorconfig index 7e5f93a2f5..a275803cec 100644 --- a/.editorconfig +++ b/.editorconfig @@ -25,17 +25,16 @@ max_line_length = 120 ij_wrap_on_typing = true ij_visual_guides = 120 - [*.{java,xml,py}] indent_style = space indent_size = 4 [*.{java,xml}] -# Ignore the IDEA unsupported warning & it works well (indeed) continuation_indent_size = 8 [*.md] -max_line_length = off +max_line_length = 160 +ij_visual_guides = 160 ij_wrap_on_typing = false [*.java] diff --git a/.serena/README.md b/.serena/README.md new file mode 100644 index 0000000000..85a533d253 --- /dev/null +++ b/.serena/README.md @@ -0,0 +1,27 @@ +# Serena project context + +This directory is a compact navigation cache for coding agents. It is not an independent documentation set and must not duplicate product guides, option tables or release history. + +## Read order + +1. [`../AGENTS.md`](../AGENTS.md) for repository-wide constraints and validation expectations. +2. [`../docs/README.md`](../docs/README.md) for the authoritative documentation map. +3. The nearest module `AGENTS.md` and README for the code being changed. +4. A memory below only when a quick architecture or file-location map is useful. + +## Maintained memories + +| Memory | Purpose | +|---|---| +| [project_overview.md](memories/project_overview.md) | Stable product scope and authoritative entry points | +| [architecture_and_modules.md](memories/architecture_and_modules.md) | High-level module ownership and runtime relationships | +| [key_file_locations.md](memories/key_file_locations.md) | Search anchors for common work areas | + +Build commands, style rules, test selection and completion checks belong in `AGENTS.md`, module files and executable CI configuration. Keeping them there prevents this cache from drifting. + +## Maintenance policy + +- Store stable relationships and search anchors, not timestamps, onboarding status, pull-request links, commit hashes or copied release numbers. +- Link to the owning file instead of reproducing long procedures. +- Update or remove a memory in the same change when module ownership or a referenced path changes. +- Keep each memory small enough to load on demand; do not turn the cache into a second README tree. diff --git a/.serena/memories/architecture_and_modules.md b/.serena/memories/architecture_and_modules.md index 687ae2251f..7481a60db9 100644 --- a/.serena/memories/architecture_and_modules.md +++ b/.serena/memories/architecture_and_modules.md @@ -1,36 +1,23 @@ -# Architecture and Module Structure - -## Three-Tier Architecture - -### 1. Client Layer -- Gremlin/Cypher queries, REST APIs, Swagger UI - -### 2. Server Layer (hugegraph-server, 8 submodules) -- **REST API** (hugegraph-api): GraphAPI, SchemaAPI, GremlinAPI, CypherAPI, AuthAPI, GraphSpaceAPI (distributed only), ManagerAPI (distributed only) -- **Graph Engine** (hugegraph-core): Schema (with TTL update), traversal, task scheduling, GraphSpace multi-tenancy -- **Backend Interface**: Pluggable via `BackendStore` - -### 3. Storage Layer -- RocksDB (default/embedded), HStore (distributed/production) -- HBase (deprecated; planned for removal in 2.0) - -## Module Structure (7 top-level modules) - -### hugegraph-server (8 submodules) -`hugegraph-core`, `hugegraph-api` (includes `opencypher/`, `space/`), `hugegraph-dist`, `hugegraph-test`, `hugegraph-example`, plus backends: `hugegraph-rocksdb`, `hugegraph-hstore`, `hugegraph-hbase` - -### hugegraph-pd (8 submodules) -Placement Driver: `hg-pd-core`, `hg-pd-service`, `hg-pd-client`, `hg-pd-common`, `hg-pd-grpc`, `hg-pd-cli`, `hg-pd-dist`, `hg-pd-test` - -### hugegraph-store (9 submodules) -Distributed storage + Raft: `hg-store-core`, `hg-store-node`, `hg-store-client`, `hg-store-common`, `hg-store-grpc`, `hg-store-rocksdb`, `hg-store-cli`, `hg-store-dist`, `hg-store-test` - -### Others -- **hugegraph-commons**: Shared utilities, RPC framework -- **hugegraph-struct**: Data structures (must build before PD/Store) -- **install-dist**: Distribution packaging, license files -- **hugegraph-cluster-test**: Cluster integration tests - -## Distributed Deployment (BETA) -PD manages placement and metadata; Store owns partition data; Server serves graph queries. -Development and HA topologies differ; see `docker/README.md` for node counts and configuration. +# Architecture and module ownership + +```text +Clients and ecosystem tools + │ + ▼ +HugeGraph Server ─────► RocksDB (standalone) + │ + └───────────► PD ─────► HStore nodes (distributed) +``` + +## Top-level ownership + +- `hugegraph-server/`: graph engine, schema, tasks, traversers, REST/Gremlin/Cypher APIs and storage adapters. +- `hugegraph-pd/`: placement, metadata, cluster scheduling and PD clients. +- `hugegraph-store/`: partition storage, Store clients and Raft replication. +- `hugegraph-struct/`: shared graph structures, identifiers and serialization used across distributed modules. +- `hugegraph-commons/`: shared utilities and RPC infrastructure. +- `hugegraph-cluster-test/`: cross-component cluster validation. +- `install-dist/`: distribution assembly, dependency inventory and release metadata. +- `helm/hugegraph/` and `docker/`: Kubernetes and container deployment assets. + +Read the nearest module `AGENTS.md` before changing an implementation. For current submodule membership and dependency edges, inspect the root and module POMs rather than maintaining a copied count here. diff --git a/.serena/memories/code_style_and_conventions.md b/.serena/memories/code_style_and_conventions.md deleted file mode 100644 index ce3809cdf4..0000000000 --- a/.serena/memories/code_style_and_conventions.md +++ /dev/null @@ -1,28 +0,0 @@ -# Code Style and Conventions - -## Style Tools -- `.editorconfig` — Primary style definition -- `style/checkstyle.xml` — Enforcement (note: `hugegraph-style.xml` was removed) -- `.licenserc.yaml` + apache-rat-plugin + skywalking-eyes — License header validation - -## Core Rules -- **Line length**: 120 chars -- **Indent**: 4 spaces, continuation 8 spaces -- **Charset**: UTF-8, LF line endings, final newline -- **Imports**: Sorted `$*` → `java` → `javax` → `org` → `com` → `*`, no star imports (threshold 100) -- **Braces**: `if`/`while`/`for` forced if multiline, `do-while` always -- **Blank lines**: Max 1 in code/declarations -- **JavaDoc**: `

` on empty lines, no wrap if one line - -## Naming -- Packages: `org.apache.hugegraph.*` (lowercase dot-separated) -- Classes: PascalCase, Methods/Variables: camelCase, Constants: UPPER_SNAKE_CASE - -## License -- All source files require Apache 2.0 header -- gRPC generated code excluded from checks -- Validate: `mvn apache-rat:check -ntp` + `mvn editorconfig:check` - -## Build -- Java 17 release target, `-Xlint:unchecked`, Lombok 1.18.30 (provided/optional) -- Swagger: `io.swagger.core.v3:swagger-jaxrs2-jakarta` for REST API docs diff --git a/.serena/memories/ecosystem_and_related_projects.md b/.serena/memories/ecosystem_and_related_projects.md deleted file mode 100644 index b5bd9c1eeb..0000000000 --- a/.serena/memories/ecosystem_and_related_projects.md +++ /dev/null @@ -1,24 +0,0 @@ -# HugeGraph Ecosystem and Related Projects - -## This Repo: apache/hugegraph (server, OLTP) - -## Ecosystem -| Repo | Purpose | -|------|---------| -| hugegraph-toolchain | Loader, Hubble (visualization), Tools CLI, Java Client | -| hugegraph-computer | OLAP: PageRank, Connected Components, Shortest Path | -| apache/hugegraph-ai | Graph RAG, KG construction, NL→Gremlin/Cypher | -| hugegraph-doc | Docs & website (hugegraph.apache.org) | - -## Data Flow -``` -Sources → hugegraph-loader → hugegraph-server → Hubble / Computer / AI -``` - -## Integrations -- Big Data: Flink, Spark, HDFS -- Queries: Gremlin (TinkerPop 3.8.1), OpenCypher, REST API + Swagger UI -- Storage: RocksDB (default), HStore (distributed) - -## Versions -Read Server revision from root `pom.xml` and TinkerPop from `hugegraph-server/pom.xml`. diff --git a/.serena/memories/implementation_patterns_and_guidelines.md b/.serena/memories/implementation_patterns_and_guidelines.md deleted file mode 100644 index ce83957f48..0000000000 --- a/.serena/memories/implementation_patterns_and_guidelines.md +++ /dev/null @@ -1,49 +0,0 @@ -# Implementation Patterns and Guidelines - -## Backend Architecture -- Backends implement `BackendStore` interface from `hugegraph-core` -- Each backend = separate Maven module under `hugegraph-server/` -- Configured via `hugegraph.properties` → `backend` property -- **Supported backends**: RocksDB (default/embedded), HStore (distributed), HBase (deprecated; planned for removal in 2.0) - -## GraphSpace Multi-Tenancy -- Core: `hugegraph-core/.../space/` (GraphSpace, SchemaTemplate, Service, register/) -- API: `hugegraph-api/.../api/space/GraphSpaceAPI.java` (includes GS profile endpoints) -- **Standalone mode**: GraphSpaceAPI and ManagerAPI are disabled - -## Auth System -- Disabled by default, enable via `bin/enable-auth.sh` -- ConfigAuthenticator was removed, use standard auth -- Multi-level: Users, Groups, Projects, Targets, Access control -- Location: `hugegraph-api/.../api/auth/` - -## gRPC Protocol -- PD protos: `hugegraph-pd/hg-pd-grpc/src/main/proto/` -- Store protos: `hugegraph-store/hg-store-grpc/src/main/proto/` -- After `.proto` changes: `mvn clean compile`; PD/Store gRPC POMs output to each module's `src/main/java/`. - -## Query Languages -- **Gremlin**: Native TinkerPop 3.8.1 -- **OpenCypher**: `hugegraph-api/opencypher/` -- TinkerPop exceptions are passed through in Gremlin responses - -## Schema -- Labels support TTL with runtime update -- Edge label conflicting conditions are handled safely - -## Testing -- **Profiles**: `unit-test`, `core-test`, `api-test`, `tinkerpop-structure-test`, `tinkerpop-process-test` -- **Backends in CI**: memory, rocksdb, hbase (matrix) -- **Single test class**: `mvn test -pl hugegraph-server/hugegraph-test -am -P core-test,memory -Dtest=ClassName` -- TinkerPop tests: `release-*`/`test-*` and upgrade branches selected in `server-ci.yml` -- Server Raft API tests are branch-gated in `server-ci.yml`; Store raft-core tests run in normal `pd-store-ci.yml` CI. - -## Docker -- Standalone: `docker/docker-compose.yml` (bridge network, Server + Hubble) -- Cluster: `docker/docker-compose-3pd-3store-3server.yml` -- Container logs: stdout-based - -## CI Pipelines -- `server-ci.yml`: compile + unit/core/API tests (memory/rocksdb/hbase × Java 17) -- `rerun-ci.yml`: auto-rerun flaky failures (max 2 reruns, 180s delay) -- `auto-pr-review.yml`: auto-comment on new PRs diff --git a/.serena/memories/key_file_locations.md b/.serena/memories/key_file_locations.md index bde5926a3c..32dee92d5c 100644 --- a/.serena/memories/key_file_locations.md +++ b/.serena/memories/key_file_locations.md @@ -1,44 +1,21 @@ -# Key File and Directory Locations +# Key file locations -## Build & Config -- `pom.xml` — Root multi-module POM -- `.editorconfig` — Code style rules -- `style/checkstyle.xml` — Checkstyle enforcement (hugegraph-style.xml was removed) -- `.licenserc.yaml` — License checker config +Use these paths as search anchors; follow the nearest README or `AGENTS.md` for local rules. -## Server (hugegraph-server) -- Core engine: `hugegraph-core/src/main/java/org/apache/hugegraph/` → `backend/`, `schema/`, `traversal/`, `task/` -- GraphSpace: `hugegraph-core/.../space/` → `GraphSpace.java`, `SchemaTemplate.java`, `Service.java`, `register/` -- REST APIs: `hugegraph-api/src/main/java/org/apache/hugegraph/api/` → `graph/`, `schema/`, `gremlin/`, `cypher/`, `auth/`, `space/` (GraphSpaceAPI), `metrics/`, `arthas/` -- OpenCypher: `hugegraph-api/.../opencypher/` -- Backend interface: `hugegraph-core/.../backend/store/BackendStore.java` -- Distribution: `hugegraph-dist/src/assembly/static/` → `bin/`, `conf/`, `lib/`, `logs/` -- Tests: `hugegraph-test/src/main/java/.../` → `unit/`, `core/`, `api/`, `tinkerpop/` +| Work area | Start here | +|---|---| +| Repository modules and versions | `pom.xml` | +| Build, contribution and documentation map | `docs/README.md`, `docs/BUILDING.md`, `docs/CONTRIBUTING.md` | +| Graph engine, schema, traversal and tasks | `hugegraph-server/hugegraph-core/src/main/java/org/apache/hugegraph/` | +| REST, Gremlin, Cypher and authentication APIs | `hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/` | +| Server distribution and runtime configuration | `hugegraph-server/hugegraph-dist/` | +| Server tests | `hugegraph-server/hugegraph-test/` | +| PD implementation and protocol | `hugegraph-pd/`, especially `hg-pd-core/`, `hg-pd-service/` and `hg-pd-grpc/` | +| Store implementation and protocol | `hugegraph-store/`, especially `hg-store-core/`, `hg-store-node/` and `hg-store-grpc/` | +| Shared graph structures | `hugegraph-struct/` | +| CI workflows and policy | `.github/workflows/`, `.github/scripts/`, `docs/ci.md` | +| Dependency and release metadata | `install-dist/release-docs/`, `install-dist/scripts/dependency/` | +| Docker and Compose | `docker/README.md`, `docker/` | +| Kubernetes and Helm | `helm/hugegraph/README.md`, `helm/hugegraph/docs/README.md`, `helm/hugegraph/values.yaml` | -## Docker -- `docker/docker-compose.yml` — Standalone Server + Hubble (bridge network) -- `docker/docker-compose-3pd-3store-3server.yml` — 3-node cluster -- `docker/docker-compose.dev.yml` — Dev mode - -## PD Module -- Proto: `hugegraph-pd/hg-pd-grpc/src/main/proto/` -- Dist: `hugegraph-pd/hg-pd-dist/src/assembly/static/` - -## Store Module -- Proto: `hugegraph-store/hg-store-grpc/src/main/proto/` -- Dist: `hugegraph-store/hg-store-dist/src/assembly/static/` - -## CI Workflows (.github/workflows/) -- `server-ci.yml` — Server tests (matrix: memory/rocksdb/hbase × Java 17) -- `pd-store-ci.yml` — PD, Store & HStore tests -- `commons-ci.yml` — Commons tests -- `cluster-test-ci.yml` — Cluster integration -- `licence-checker.yml` — License headers -- `rerun-ci.yml` — Auto-rerun for flaky workflows -- `auto-pr-review.yml` — Auto-comment on new PRs -- `check-dependencies.yml` — Dependency checks -- `codeql-analysis.yml` — CodeQL security scanning -- `stale.yml` — Stale issue/PR cleanup - -## Docs -- `README.md`, `docs/BUILDING.md`, `docs/CONTRIBUTING.md`, `AGENTS.md`, `CLAUDE.md` +Search the repository before assuming a path or configuration name is still current. This memory intentionally omits workflow filenames and submodule counts that change frequently. diff --git a/.serena/memories/project_overview.md b/.serena/memories/project_overview.md index deac1e6821..047305d69f 100644 --- a/.serena/memories/project_overview.md +++ b/.serena/memories/project_overview.md @@ -1,26 +1,19 @@ -# Apache HugeGraph Project Overview +# Project overview -## Project Purpose -Apache HugeGraph is a fast-speed, highly-scalable graph database supporting 10+ billion vertices/edges for OLTP workloads. Graduated from Apache Incubator (incubating branding removed). +Apache HugeGraph is a graph database with standalone and distributed deployment modes. It provides a property-graph data model, schema and indexes, graph traversals, REST/Gremlin/Cypher access, authentication and operational tooling. -## Key Capabilities -- Apache TinkerPop 3 compliant graph database -- Gremlin + OpenCypher query languages -- Schema metadata management (VertexLabel, EdgeLabel, PropertyKey, IndexLabel) with TTL update support -- Multi-type indexes (exact, range, complex conditions) -- Pluggable backend storage (RocksDB default, HStore distributed) -- GraphSpace multi-tenancy (standalone mode disables GraphSpaceAPI/ManagerAPI) -- Swagger UI for REST API documentation -- Integration with Flink/Spark/HDFS +## Deployment modes -## Technology Stack -- **Language**: Java 17 (required; currently supported release) -- **Build**: Maven 3.6.3+ -- **Graph Framework**: Apache TinkerPop 3.8.1 -- **RPC**: gRPC + Protocol Buffers -- **API Docs**: Swagger (io.swagger.core.v3) -- **Storage**: RocksDB (default/embedded), HStore (distributed/production), HBase (deprecated; planned for removal in 2.0) +- **Standalone:** HugeGraph Server uses embedded RocksDB. This is the shortest path for development and smaller deployments. +- **Distributed:** Server handles graph APIs, PD owns placement and metadata coordination, and HStore nodes own partition data and replication. -## Version -- Read `${revision}` from the root `pom.xml`; Maven flatten resolves it for published artifacts. -- License: Apache License 2.0 +## Authoritative entry points + +- Product and deployment overview: [`../../README.md`](../../README.md) +- Repository documentation map: [`../../docs/README.md`](../../docs/README.md) +- Build and contribution rules: [`../../docs/BUILDING.md`](../../docs/BUILDING.md), [`../../docs/CONTRIBUTING.md`](../../docs/CONTRIBUTING.md) +- Kubernetes deployment: [`../../helm/hugegraph/README.md`](../../helm/hugegraph/README.md) +- Repository agent guidance: [`../../AGENTS.md`](../../AGENTS.md) +- Current versions and module membership: [`../../pom.xml`](../../pom.xml) + +Do not copy release versions or detailed feature lists into this memory. Read the owning source when exact current behavior matters. diff --git a/.serena/memories/suggested_commands.md b/.serena/memories/suggested_commands.md deleted file mode 100644 index c1aa4d8e5b..0000000000 --- a/.serena/memories/suggested_commands.md +++ /dev/null @@ -1,59 +0,0 @@ -# Suggested Development Commands - -## Build -```bash -mvn clean install -DskipTests # Full build -mvn clean install -pl hugegraph-server -am -DskipTests # Server only -mvn clean compile -U -Dmaven.javadoc.skip=true -ntp # Compile only -mvn clean package -DskipTests # Aggregate distribution → root target/ -``` - -## Test -```bash -# Server tests (memory/rocksdb/hbase backends) -mvn test -pl hugegraph-server/hugegraph-test -am -P unit-test -mvn test -pl hugegraph-server/hugegraph-test -am -P core-test,memory -mvn test -pl hugegraph-server/hugegraph-test -am -P core-test,rocksdb -mvn test -pl hugegraph-server/hugegraph-test -am -P api-test,rocksdb - -# Single test class -mvn test -pl hugegraph-server/hugegraph-test -am -P core-test,memory -Dtest=YourTestClass - -# TinkerPop compliance (can be run locally on any branch) -mvn test -pl hugegraph-server/hugegraph-test -am -P tinkerpop-structure-test,memory - -# PD/Store (build struct first) -mvn install -pl hugegraph-struct -am -DskipTests -mvn test -pl hugegraph-pd/hg-pd-test -am -mvn test -pl hugegraph-store/hg-store-test -am -``` - -## Validation -```bash -mvn apache-rat:check -ntp # License headers -mvn editorconfig:check # Code style (.editorconfig) -mvn checkstyle:check # Code style (style/checkstyle.xml) -mvn clean compile -Dmaven.javadoc.skip=true # Compile warnings -``` - -## Server Ops -Scripts in `hugegraph-server/hugegraph-dist/src/assembly/static/bin/` (or extracted distribution `bin/`): -```bash -bin/init-store.sh && bin/start-hugegraph.sh # Init + start -bin/stop-hugegraph.sh # Stop -bin/enable-auth.sh # Enable auth -``` - -## Docker -Create the required authentication environment first; follow `docker/README.md`. -```bash -cd docker && docker compose up -d # Standalone Server + Hubble (bridge network) -cd docker && docker compose -f docker-compose-3pd-3store-3server.yml up -d # Cluster -``` - -## Distributed Build (BETA) -```bash -mvn install -pl hugegraph-struct -am -DskipTests # 1. Struct first -mvn clean package -pl hugegraph-pd -am -DskipTests # 2. PD -mvn clean package -pl hugegraph-store -am -DskipTests # 3. Store -``` diff --git a/.serena/memories/task_completion_checklist.md b/.serena/memories/task_completion_checklist.md deleted file mode 100644 index 58a32fb0e4..0000000000 --- a/.serena/memories/task_completion_checklist.md +++ /dev/null @@ -1,37 +0,0 @@ -# Task Completion Checklist - -## 1. Validation scope -Documentation-only changes: check links, paths and `git diff --check`. -For code changes, select relevant checks below and follow root `AGENTS.md` before pushing. -```bash -mvn apache-rat:check -ntp # License headers -mvn editorconfig:check # Style (.editorconfig) -mvn checkstyle:check # Style (style/checkstyle.xml) -mvn clean compile -Dmaven.javadoc.skip=true # Compile warnings -``` - -## 2. Testing -- Choose backend: `memory` (fast), `rocksdb` (realistic), `hbase` (deprecated compatibility) -- Single-test selection: check the module test POM and confirm the requested test actually ran. -- Bug fix → existing tests; New feature → write tests; Refactor → affected module tests - -## 3. Dependencies (if adding new) -1. License file → `install-dist/release-docs/licenses/` -2. Declare in `install-dist/release-docs/LICENSE` -3. Append NOTICE → `install-dist/release-docs/NOTICE` -4. Run `./install-dist/scripts/dependency/regenerate_known_dependencies.sh` - -## 4. CI Awareness -- `server-ci.yml`: memory/rocksdb/hbase × Java 17 -- `rerun-ci.yml`: auto-retries flaky failures -- `licence-checker.yml`: header validation -- Server Raft API tests are branch-gated; Store raft-core and core tests run in normal PD/Store CI. -- TinkerPop tests: only `release-*`/`test-*` branches - -## 5. Documentation -- Follow root `AGENTS.md`: user-visible feature/configuration/deployment changes ship with matching docs. - -## 6. Commit -- NEVER commit unless explicitly asked -- Format: `feat|fix|refactor(module): msg` -- Include issue ID if available diff --git a/AGENTS.md b/AGENTS.md index e7768ad5eb..3bf6deba08 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,62 +1,58 @@ # AGENTS.md -Repository-specific guidance; module files add local details. +Repository-specific guidance for coding agents. Module files add local ownership, commands and failure modes. -## Key relationships +## System map ```text -Server (hugegraph-server): graph engine + REST/Gremlin API - ├─ RocksDB: embedded backend - └─ HStore adapter → Store client → Store: partition data + Raft +Server: graph engine and user APIs + ├─ RocksDB: embedded standalone backend + └─ HStore adapter → Store client → Store partition data and Raft -PD: placement + metadata; consulted by Server and Store -Struct: shared types/codecs; separate implementations also exist in Server -Commons: shared utilities; independent compiler and test settings +PD: placement and metadata coordination +Struct: shared graph types and codecs +Commons: shared utilities and RPC infrastructure ``` ## Load on demand -| Work area | Read when working there | +| Work area | Read first | |---|---| -| Graph engine, API, backends | [Server](hugegraph-server/AGENTS.md) | -| Placement, metadata, PD client | [PD](hugegraph-pd/AGENTS.md) | -| Distributed storage and client | [Store](hugegraph-store/AGENTS.md) | -| Shared data types and serialization | [Struct](hugegraph-struct/AGENTS.md) | -| Utilities and RPC | [Commons](hugegraph-commons/AGENTS.md) | -| Container deployment | [Docker guide](docker/README.md) | -| PR requirements | [Contribution guide](docs/CONTRIBUTING.md) | +| Documentation ownership and durable links | [Repository docs index](docs/README.md) | +| Graph engine, API and backends | [Server guidance](hugegraph-server/AGENTS.md) | +| Placement, metadata and PD clients | [PD guidance](hugegraph-pd/AGENTS.md) | +| Distributed storage and Store clients | [Store guidance](hugegraph-store/AGENTS.md) | +| Shared graph types and serialization | [Struct guidance](hugegraph-struct/AGENTS.md) | +| Utilities and RPC | [Commons guidance](hugegraph-commons/AGENTS.md) | +| Docker deployment | [Docker guide](docker/README.md) | +| Kubernetes deployment | [Helm guide](helm/hugegraph/README.md) | +| Contribution requirements | [Contribution guide](docs/CONTRIBUTING.md) | ## Repository constraints -- Use existing module boundaries; keep unrelated refactors out of a fix. -- User-visible feature, configuration or deployment behavior changes must ship with matching docs. - Update in-repository docs in the same PR; link a paired `apache/hugegraph-doc` PR when website - docs are affected and coordinate both merges. A follow-up issue alone does not satisfy this rule. - Internal-only changes can use `Doc - No Need`. -- Keep README as an entry point; link detailed deployment instructions instead of duplicating them. -- Keep AGENTS.md under 100 lines where practical. Shared rules belong here, local exceptions - in module files. Keep key relationships, common commands and non-obvious pitfalls inline; - reference existing sources for versions, configuration details and lengthy procedures. +- Keep changes inside the module that owns the behavior; exclude unrelated cleanup from a functional fix. +- A user-visible feature, configuration or deployment change requires matching documentation in the same change. Link a coordinated `apache/hugegraph-doc` change when the website is affected; a follow-up issue alone is not sufficient. +- Keep root and module READMEs as entry points. Put detailed procedures in a focused document and link it from the relevant index. +- Treat `docs/README.md` as the repository documentation map. New durable Markdown files must be linked from it or from a module-local index. +- Treat `.serena/` as a small navigation cache. Do not store duplicated procedures, fixed release numbers, timestamps, review history, pull-request links or commit hashes there. +- Write documentation for the current contract and operational boundary, not as a development diary. Keep prose paragraphs as logical lines; wrap near 160 characters only when necessary for review. ## Build and validation -Commands run from the repository root. Java 17 and Maven 3.6.3+; -versions come from [pom.xml](pom.xml), including `${revision}`. +Run commands from the repository root. Java and Maven requirements are defined by [pom.xml](pom.xml) and summarized in [BUILDING.md](docs/BUILDING.md). ```bash mvn clean install -DskipTests mvn clean install -pl hugegraph-server -am -DskipTests ``` -For separate distributed-module builds, install `hugegraph-struct` first, -then build PD, Store and Server. Module guidance covers tests and CI prerequisites. -Commons tests require `-DskipCommonsTests=false`; a successful build does not imply its tests ran. - -- Java style: 120 columns, 4 spaces, no star imports; see [.editorconfig](.editorconfig). -- Before pushing code: `mvn editorconfig:format`, - `mvn clean compile -Dmaven.javadoc.skip=true`, and relevant module tests. - Documentation-only changes need link/path checks and `git diff --check`. -- PD/Store `.proto` builds generate Java into each `hg-*-grpc/src/main/java/` directory; - see the corresponding gRPC module POM before editing or cleaning generated sources. -- New dependencies require updating [release LICENSE/NOTICE/licenses](install-dist/release-docs/) - and [dependency inventory](install-dist/scripts/dependency/known-dependencies.txt). +For separate distributed-module builds, install `hugegraph-struct` first, then build PD, Store and Server. Commons tests require `-DskipCommonsTests=false`; a successful aggregate build does not imply those tests ran. + +Before pushing code, run `mvn editorconfig:format`, `mvn clean compile -Dmaven.javadoc.skip=true` and the tests selected by the affected modules. Documentation-only changes require relative-link review, rendered-heading review and `git diff --check`. + +## Non-obvious boundaries + +- Server changes commonly require both Server and PD/Store CI because the HStore path crosses module boundaries. +- PD and Store protocol builds generate Java into their gRPC modules; inspect the module POM before editing or deleting generated sources. +- New dependencies require updates to `install-dist/release-docs/` and `install-dist/scripts/dependency/known-dependencies.txt`. +- Read versions, plugin settings and module membership from Maven configuration instead of copying them into agent notes. diff --git a/README.md b/README.md index 2237a5e2da..60c7f60264 100644 --- a/README.md +++ b/README.md @@ -1,414 +1,125 @@

- hugegraph-logo + Apache HugeGraph

-

A graph database that supports more than 10 billion vertices & edges, high performance and scalability

+

A scalable graph database for connected data and real-time graph workloads

[![License](https://img.shields.io/badge/license-Apache%202-0E78BA.svg)](https://www.apache.org/licenses/LICENSE-2.0.html) -[![HugeGraph-Server CI](https://github.com/apache/hugegraph/actions/workflows/server-ci.yml/badge.svg)](https://github.com/apache/hugegraph/actions/workflows/server-ci.yml) -[![HugeGraph-PD & Store CI](https://github.com/apache/hugegraph/actions/workflows/pd-store-ci.yml/badge.svg)](https://github.com/apache/hugegraph/actions/workflows/pd-store-ci.yml) -[![GitHub Releases Downloads](https://img.shields.io/github/downloads/apache/hugegraph/total.svg)](https://github.com/apache/hugegraph/releases) +[![Server CI](https://github.com/apache/hugegraph/actions/workflows/server-ci.yml/badge.svg)](https://github.com/apache/hugegraph/actions/workflows/server-ci.yml) +[![PD and Store CI](https://github.com/apache/hugegraph/actions/workflows/pd-store-ci.yml/badge.svg)](https://github.com/apache/hugegraph/actions/workflows/pd-store-ci.yml) +[![Downloads](https://img.shields.io/github/downloads/apache/hugegraph/total.svg)](https://github.com/apache/hugegraph/releases) [![Artifact Hub](https://img.shields.io/endpoint?url=https%3A%2F%2Fartifacthub.io%2Fbadge%2Frepository%2Fhugegraph-helm)](https://artifacthub.io/packages/helm/hugegraph-helm/hugegraph-helm) -[![Ask DeepWiki](https://img.shields.io/badge/Ask-DeepWiki-blue)](https://deepwiki.com/apache/hugegraph)
---- +**Start here:** [Quick start](#quick-start) · [Deployment](#deployment) · [Documentation](#documentation) · [Development](#development) · [Ecosystem](#ecosystem) -**Quick Navigation:** [Architecture](#architecture) • [Quick Start](#quick-start) • [Module Map](#module-map) • [Ecosystem](#ecosystem) • [For Contributors](#contributing) • [Community](#community) +## Apache HugeGraph ---- +Apache HugeGraph is a graph database for storing, querying and operating connected data at scale. It combines schema management, indexes, graph traversals, pluggable storage and standalone or distributed deployment in one system. -## What is Apache HugeGraph? +Applications can use REST APIs, Gremlin, Cypher or client SDKs. Gremlin compatibility is provided through Apache TinkerPop; it is one access path alongside HugeGraph's native APIs and services. -[HugeGraph](https://hugegraph.apache.org/) is a fast and highly-scalable [graph database](https://en.wikipedia.org/wiki/Graph_database). -Billions of vertices and edges can be easily stored into and queried from HugeGraph due to its excellent OLTP capabilities. -HugeGraph is compliant with the [Apache TinkerPop 3](https://tinkerpop.apache.org/) framework allowing complicated graph queries to be -achieved through the powerful [Gremlin](https://tinkerpop.apache.org/gremlin.html) graph traversal language. +## Core capabilities -## Features +| Area | Capability | +|---|---| +| Data model | Property graph with explicit vertex labels, edge labels, property keys and indexes | +| Query and APIs | REST, Gremlin, Cypher, traverser APIs and language-specific clients | +| Storage | Embedded RocksDB for standalone deployments and HStore for distributed clusters | +| Operations | Authentication, metrics, tasks, backup and restore tooling, Docker and Kubernetes deployment | +| Scale | Single-node development through horizontally scalable Server, PD and Store clusters | +| Ecosystem | Data loading, visualization, graph computation, GraphRAG and AI integrations | -- **Schema Metadata Management**: VertexLabel, EdgeLabel, PropertyKey, and IndexLabel -- **Multi-type Indexes**: Exact query, range query, and complex conditions combination query -- **Plug-in Backend Store Framework**: RocksDB powers standalone deployments and HStore powers distributed clusters. See the [backend evolution guide](hugegraph-server/README.md#backend-evolution-and-compatibility) for compatibility details. -- **Big Data Integration**: Seamless integration with `Flink`/`Spark`/`HDFS` -- **Complete Graph Ecosystem**: In/out-memory Graph Computing + Graph Visualization & Tools + Graph Learning & AI -- **Dual Query Language Support**: [Gremlin](https://tinkerpop.apache.org/gremlin.html) (via [Apache TinkerPop 3](https://tinkerpop.apache.org/)) and [Cypher](https://en.wikipedia.org/wiki/Cypher_(query_language)) (OpenCypher) +## Quick start -## Ecosystem - -Complete **HugeGraph** ecosystem components: - -1. **[hugegraph-toolchain](https://github.com/apache/hugegraph-toolchain)** - Graph tools suite - - [Loader](https://github.com/apache/hugegraph-toolchain/tree/master/hugegraph-loader) - Data import tool - - [Dashboard](https://github.com/apache/hugegraph-toolchain/tree/master/hugegraph-hubble) - Web visualization platform - - [Tool](https://github.com/apache/hugegraph-toolchain/tree/master/hugegraph-tools) - Command-line utilities - - [Client](https://github.com/apache/hugegraph-toolchain/tree/master/hugegraph-client) - Java/Python client SDK - -2. **[hugegraph-computer](https://github.com/apache/hugegraph-computer)** - Integrated **graph computing** system - -3. **[hugegraph-ai](https://github.com/apache/hugegraph-ai)** - **Graph AI/LLM/Knowledge Graph** integration - -4. **[hugegraph-website](https://github.com/apache/hugegraph-doc)** - **Documentation & website** repository - -## Architecture - -HugeGraph supports both **standalone** and **distributed** deployments: - -``` - ┌─────────────────────────────────────────────────────┐ - │ Client Layer │ - │ Gremlin Console │ REST API │ Cypher │ SDK/Tools │ - └─────────────────────────┬───────────────────────────┘ - │ - ┌─────────────────────────▼───────────────────────────┐ - │ HugeGraph Server (:8080) │ - │ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │ - │ │ REST API │ │ Gremlin │ │ Cypher Engine │ │ - │ │(Jersey 3)│ │(TP 3.8.1)│ │ (OpenCypher) │ │ - │ └────┬─────┘ └────┬─────┘ └────────┬─────────┘ │ - │ └─────────────┼─────────────────┘ │ - │ ┌────────▼────────┐ │ - │ │ Graph Engine │ │ - │ │(hugegraph-core) │ │ - │ └────────┬────────┘ │ - └─────────────────────┼───────────────────────────────┘ - │ - ┌─────────────────┴─────────────────┐ - │ │ - ┌──────────────▼──────────────┐ ┌──────────────▼──────────────┐ - │ Standalone Mode │ │ Distributed Mode │ - │ ┌───────────────────────┐ │ │ ┌───────────────────────┐ │ - │ │ RocksDB │ │ │ │ HugeGraph-PD │ │ - │ │ (embedded) │ │ │ │ (Raft, 3-5 nodes) │ │ - │ └───────────────────────┘ │ │ │ :8620/:8686 │ │ - │ │ │ └───────────┬───────────┘ │ - │ Use Case: │ │ │ │ - │ Development/Testing │ │ ┌───────────▼───────────┐ │ - │ Single Node │ │ │ HStore │ │ - │ │ │ │ (Raft, 3+ nodes) │ │ - │ Data Scale: < 1TB │ │ │ :8520 │ │ - └─────────────────────────────┘ │ └───────────────────────┘ │ - │ │ - │ Use Case: │ - │ Production/HA/Cluster │ - │ │ - │ Data Scale: < 1000 TB │ - └─────────────────────────────┘ -``` - -See the [backend evolution guide](hugegraph-server/README.md#backend-evolution-and-compatibility) for lifecycle and historical compatibility guidance. - -To use ToplingDB with the RocksDB backend, follow the [three-step switching guide](docs/storage-lifecycle.md#storage-provider-selection-and-toplingdb). - -### Deployment Mode Comparison - -| Mode | Components | Use Case | Data Scale | High Availability | -|------|------------|----------|------------|-------------------| -| **Standalone** | Server + RocksDB | Development, Testing, Single Node | < 1TB | Basic | -| **Distributed** | Server + PD + HStore | Production, HA, Horizontal Scaling | < 1000 TB | Yes | - -### Module Overview - -| Module | Description | -|--------|-------------| -| [hugegraph-server](hugegraph-server) | Core graph engine with REST API, Gremlin/Cypher support, and pluggable backends (RocksDB default) | -| [hugegraph-pd](hugegraph-pd/README.md) | Placement Driver for distributed mode - handles meta storage, partition management and cluster scheduling | -| [hugegraph-store](hugegraph-store/README.md) | Distributed storage with Raft consensus for high availability and horizontal scaling | -| [hugegraph-commons](hugegraph-commons) | Shared utilities, RPC framework and common components | -| [hugegraph-struct](hugegraph-struct/README.md) | Shared schema, IDs, base elements, queries and encoding used by Server and Store | - -See the [1.8.0 shared-foundation migration guide](docs/shared-foundation-migration.md) for Java API changes, module ownership and coordinated upgrade requirements. - -
-📊 Click to view detailed architecture diagram (Mermaid) - -```mermaid -flowchart TB - CLIENTS["Client Layer
Gremlin Console · REST Client · Cypher Client · SDK/Tools"] - - subgraph Server["HugeGraph Server :8080"] - API[REST API
Jersey 3] - GS[Gremlin Server
TinkerPop 3.8.1] - CS[Cypher Engine
OpenCypher] - CORE[Graph Engine
hugegraph-core] - - API --> CORE - GS --> CORE - CS --> CORE - end - - subgraph Storage["Storage Layer"] - subgraph Standalone["Standalone Mode"] - ROCKS[(RocksDB
Embedded)] - end - - subgraph Distributed["Distributed Mode"] - PD_HSTORE[PD + HStore
Raft Cluster] - end - end - - CLIENTS --> Server - CORE --> ROCKS - CORE --> PD_HSTORE - - style Server fill:#e1f5ff - style Distributed fill:#fff4e1 - style Standalone fill:#f0f0f0 -``` - -
- -## Quick Start - - - -### 5 Minutes Quick Start +Start a standalone server for local evaluation: ```bash -# Start HugeGraph (standalone mode) -docker run -itd --name=hugegraph -p 8080:8080 hugegraph/hugegraph:1.7.0 - -# Verify server is running +docker run -d --name hugegraph -p 8080:8080 hugegraph/hugegraph curl http://localhost:8080/versions - -# Try a Gremlin query -curl -X POST http://localhost:8080/gremlin \ - -H "Content-Type: application/json" \ - -d '{"gremlin":"g.V().limit(5)"}' ``` -> **Production Note**: For production environments or public network exposure, you **must** enable the [AuthSystem](https://hugegraph.apache.org/docs/config/config-authentication/) for security. - -### Prerequisites - -- **Java 17** (required and currently the only supported Java release) -- **Maven 3.6.3+** (for building from source) - -The launch scripts reject Java versions older than 17. That minimum-version -check does not qualify later Java releases; use Java 17 unless another release -is explicitly listed as supported. - -Read the [Server runtime guide](docs/server-runtime.md#runtime-and-client-configuration) -for client configuration and query compatibility checks. - -### Option 1: Docker (Fastest) - -Docker is the quickest way to get started for **testing or development**: +Run a small graph query: ```bash -# Basic usage -docker run -itd --name=hugegraph -p 8080:8080 hugegraph/hugegraph:1.7.0 - -# With sample graph preloaded -docker run -itd --name=hugegraph -e PRELOAD=true -p 8080:8080 hugegraph/hugegraph:1.7.0 - -# With authentication enabled -docker run -itd --name=hugegraph -e PASSWORD=your_password -p 8080:8080 hugegraph/hugegraph:1.7.0 +curl -X POST http://localhost:8080/gremlin \ + -H 'Content-Type: application/json' \ + -d '{"gremlin":"g.V().limit(5)"}' ``` -For advanced Docker configurations, see: - -* [Docker Documentation](https://hugegraph.apache.org/docs/quickstart/hugegraph-server/#3-deploy) -* [Docker Compose Examples](./docker/) -* [Docker README](./docker/README.md) -* [Server Docker README](hugegraph-server/hugegraph-dist/docker/README.md) - -> **Docker Desktop (Mac/Windows)**: The 3-node distributed cluster (`docker/docker-compose-3pd-3store-3server.yml`) uses Docker bridge networking and works on all platforms including Docker Desktop. Allocate at least 12 GB memory to Docker Desktop. - -> **Note**: Docker images are convenience releases, not **official ASF distribution artifacts**. See [ASF Release Distribution Policy](https://infra.apache.org/release-distribution.html#dockerhub) for details. -> -> **Version Tags**: Use release tags (e.g., `1.7.0`) for stable deployments. The `latest` tag should only be used for testing or development. +The default image is intended for local evaluation. Pin a released image for repeatable deployments and enable authentication before exposing the service outside a trusted network. See the [server deployment guide](https://hugegraph.apache.org/docs/quickstart/hugegraph-server/) for packages, configuration and production preparation. -### Option 2: Kubernetes with Helm +## Deployment -The HStore Helm chart deploys HugeGraph PD, Store, and Server as a distributed -Kubernetes cluster. See the [chart documentation](helm/hugegraph/README.md) for -single-node and highly available presets, configuration, and -upgrade guidance. +| Goal | Recommended entry point | +|---|---| +| Local development | [Standalone Docker](docker/README.md) | +| Multi-process or distributed test environment | [Docker Compose examples](docker/README.md) | +| Kubernetes deployment | [HugeGraph Helm chart](helm/hugegraph/README.md) | +| Binary installation | [Download and deployment guide](https://hugegraph.apache.org/docs/quickstart/hugegraph-server/) | +| Build or customize the source | [Building from source](docs/BUILDING.md) | +A standalone deployment runs Server with embedded RocksDB. A distributed deployment separates query serving, metadata and placement, and partition storage: -
-Option 3: Download Binary Package - -Download pre-built packages from the [Download Page](https://hugegraph.apache.org/docs/download/download/): - -```bash -# Download and extract -# For historical 1.7.0 and earlier releases, use the archive URL and -# set PACKAGE=apache-hugegraph-incubating-{version} instead. -BASE_URL="https://downloads.apache.org/hugegraph/{version}" -PACKAGE="apache-hugegraph-{version}" -# Historical alternative: -# BASE_URL="https://archive.apache.org/dist/incubator/hugegraph/{version}" -# PACKAGE="apache-hugegraph-incubating-{version}" - -wget ${BASE_URL}/${PACKAGE}.tar.gz -tar -xzf ${PACKAGE}.tar.gz -cd ${PACKAGE} - -# Initialize backend storage -bin/init-store.sh - -# Start server -bin/start-hugegraph.sh - -# Check server status -bin/monitor-hugegraph.sh +```text +Clients and tools + │ + ▼ +HugeGraph Server ─────► RocksDB (standalone) + │ + └──────────────► PD ─────► HStore nodes (distributed) ``` -For detailed instructions, see the [Binary Installation Guide](https://hugegraph.apache.org/docs/quickstart/hugegraph-server/#32-download-the-binary-tar-tarball). +## Repository modules -
+| Module | Responsibility | +|---|---| +| [`hugegraph-server`](hugegraph-server/) | Graph engine, schema, REST/Gremlin/Cypher APIs and backend adapters | +| [`hugegraph-pd`](hugegraph-pd/) | Placement, metadata and distributed-cluster coordination | +| [`hugegraph-store`](hugegraph-store/) | Partition storage and Raft-based replication | +| [`hugegraph-struct`](hugegraph-struct/) | Shared graph structures, identifiers and serialization | +| [`hugegraph-commons`](hugegraph-commons/) | Shared utilities and RPC infrastructure | +| [`helm/hugegraph`](helm/hugegraph/) | Kubernetes chart for Server, PD, Store and optional ecosystem services | -
-Option 4: Build from Source +## Documentation -Build from source for development or customization: +Use the shortest authoritative source for the task: -```bash -# Clone repository -git clone https://github.com/apache/hugegraph.git -cd hugegraph +- [Repository documentation index](docs/README.md): build, contribution, API, runtime, storage and internal design documents. +- [Official website documentation](https://hugegraph.apache.org/docs/): user installation, configuration and feature guides. +- [Helm documentation index](helm/hugegraph/docs/README.md): Kubernetes installation, operations and optional components. +- [Docker guide](docker/README.md): local and distributed Compose environments. +- [`AGENTS.md`](AGENTS.md): repository rules and code-navigation hints for contributors and coding agents. -# Build all modules (skip tests for faster build) -mvn clean package -DskipTests +The repository index explains which location owns each kind of information. Detailed documents should be linked from an index rather than left as isolated files. -# Extract built package -tar -xzf target/apache-hugegraph-{version}.tar.gz -cd apache-hugegraph-{version}/apache-hugegraph-server-{version} +## Development -# Initialize and start -bin/init-store.sh -bin/start-hugegraph.sh -``` - -For detailed build instructions, see [BUILDING.md](docs/BUILDING.md) and [Build from Source Guide](https://hugegraph.apache.org/docs/quickstart/hugegraph-server/#33-source-code-compilation). - -
- -
-Verify Installation - -Once the server is running, verify the installation: +The source build uses Java 17 and Maven 3.6.3 or later. Read versions from the root [`pom.xml`](pom.xml) instead of copying them into secondary documents. ```bash -# Check server version -curl http://localhost:8080/versions - -# Expected output: -# { -# "versions": { -# "version": "v1", -# "core": "1.7.0", -# "gremlin": "3.8.1", -# "api": "1.7.0" -# } -# } - -# Try Gremlin console (if installed locally) -bin/gremlin-console.sh - -# In Gremlin console: -gremlin> :remote connect tinkerpop.server conf/remote.yaml -gremlin> :> g.V().limit(5) +mvn clean install -DskipTests +mvn clean install -pl hugegraph-server -am -DskipTests ``` -For comprehensive documentation, visit the [HugeGraph Documentation](https://hugegraph.apache.org/docs/). - -Read the [storage lifecycle and recovery guide](docs/storage-lifecycle.md) before restoring data, mounting store directories or upgrading the storage runtime. - -
- -## Module Map - -**Developer Navigation**: Find the right module for your task +Before contributing, read [BUILDING.md](docs/BUILDING.md), [CONTRIBUTING.md](docs/CONTRIBUTING.md) and the relevant module `AGENTS.md`. Run the tests required by the changed modules; Server changes commonly require both Server and PD/Store validation. -| I want to... | Module | Key Path | -|--------------|--------|----------| -| Understand graph operations | `hugegraph-core` | `StandardHugeGraph.java` | -| Modify REST APIs | `hugegraph-api` | `src/.../api/` | -| Add storage backend | `hugegraph-core` | `BackendStore.java` | -| Develop Gremlin features | `hugegraph-core` | `src/.../traversal/` | -| Develop Cypher features | `hugegraph-api` | `src/.../opencypher/` | -| Work on distributed coordination | `hugegraph-pd` | `hg-pd-core/` | -| Work on distributed storage | `hugegraph-store` | `hg-store-core/` | -| Add backend implementations | `hugegraph-server/hugegraph-{backend}` | `hugegraph-rocksdb/`, `hugegraph-hstore/` | -| Understand configuration | `hugegraph-dist` | `src/assembly/static/conf/` | -| Run tests | `hugegraph-test` | Test suites with multiple profiles | - -For repository constraints and module guidance, see [AGENTS.md](AGENTS.md). - -
-For Contributors - -**New to HugeGraph?** Follow this path to get started: - -1. **Understand the Architecture** - - Read [AGENTS.md](AGENTS.md) for key component relationships and module guidance - - Review the [Architecture Diagram](#architecture) above - -2. **Set Up Your Environment** - - Install Java 17 and Maven 3.6.3+ - - Follow [BUILDING.md](docs/BUILDING.md) for build instructions - - Configure your IDE to use `.editorconfig` for code style and `style/checkstyle.xml` for Checkstyle rules - -3. **Find Your First Issue** - - Browse [Good First Issues](https://github.com/apache/hugegraph/issues?q=label%3A%22good+first+issue%22) - - Check [Help Wanted Issues](https://github.com/apache/hugegraph/issues?q=label%3A%22help+wanted%22) - -4. **Learn the Codebase** - - Use the [Module Map](#module-map) to navigate - - Try [DeepWiki](https://deepwiki.com/apache/hugegraph) for AI-powered codebase understanding - - Run tests to understand behavior: `mvn test -pl hugegraph-server/hugegraph-test -am -P core-test,memory` - - Try modifying a test and see what breaks - -5. **Code Standards** - - Line length: 120 characters - - Indentation: 4 spaces - - No star imports - - Commit format: `feat|fix|refactor(module): description` - -6. **Submit Your Contribution** - - Read [CONTRIBUTING.md](docs/CONTRIBUTING.md) for guidelines - - Follow the [Contribution Guidelines](https://hugegraph.apache.org/docs/contribution-guidelines/) - - Use [GitHub Desktop](https://desktop.github.com/) to simplify the PR process - -
- -## Contributing - -Welcome to contribute to HugeGraph! - -- **How to Contribute**: See [CONTRIBUTING.md](docs/CONTRIBUTING.md) and [Contribution Guidelines](https://hugegraph.apache.org/docs/contribution-guidelines/) -- **Code Style**: Configure your IDE to use `.editorconfig` for code style and `style/checkstyle.xml` for Checkstyle rules -- **PR Tool**: [GitHub Desktop](https://desktop.github.com/) is recommended for simpler workflow - -Thank you to all the contributors who have helped make HugeGraph better! - -[![contributors graph](https://contrib.rocks/image?repo=apache/hugegraph)](https://github.com/apache/hugegraph/graphs/contributors) - -## License - -HugeGraph is licensed under [Apache 2.0 License](LICENSE). - -## Community - -**Get Help & Stay Connected** - -- **[GitHub Issues](https://github.com/apache/hugegraph/issues)**: Report bugs and request features (quick response) -- **Mailing List**: [dev@hugegraph.apache.org](mailto:dev@hugegraph.apache.org) ([subscribe here](https://hugegraph.apache.org/docs/contribution-guidelines/subscribe/)) -- **Slack**: [ASF HugeGraph Channel](https://the-asf.slack.com/archives/C059UU2FJ23) -- **WeChat**: Scan the QR code to follow Apache HugeGraph official account +## Ecosystem -

-WeChat QR Code -

+| Project | Purpose | +|---|---| +| [HugeGraph Toolchain](https://github.com/apache/hugegraph-toolchain) | Java client, Loader, Hubble, CLI tools and Spark connector | +| [HugeGraph Computer](https://github.com/apache/hugegraph-computer) | Distributed and in-memory graph computation, including Vermeer | +| [HugeGraph AI](https://github.com/apache/hugegraph-ai) | Python client, GraphRAG, knowledge-graph extraction, MCP and graph ML | +| [HugeGraph Documentation](https://github.com/apache/hugegraph-doc) | Website and long-form user documentation | -## Thanks +## Community and license -HugeGraph relies on the [Apache TinkerPop](http://tinkerpop.apache.org) framework. We are grateful to the TinkerPop community, Titan, and DataStax for their foundational work. Thanks to all contributors and organizations who have helped make HugeGraph possible. +- [Contribution guide](https://hugegraph.apache.org/docs/contribution-guidelines/) +- [Issue tracker](https://github.com/apache/hugegraph/issues) +- [Developer mailing list](mailto:dev@hugegraph.apache.org) -You are welcome to contribute to HugeGraph, and we look forward to working with you to build an excellent open-source community. +Apache HugeGraph is licensed under the [Apache License 2.0](LICENSE). diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000000..df3c56aa09 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,54 @@ +# Repository documentation + +This directory contains source-specific documentation for Apache HugeGraph. It complements the [official website documentation](https://hugegraph.apache.org/docs/) and should not duplicate complete user guides that already live there. + +## Find the right document + +| Task | Document | +|---|---| +| Understand the repository and deployment choices | [Root README](../README.md) | +| Build the project from source | [BUILDING.md](BUILDING.md) | +| Prepare and validate a contribution | [CONTRIBUTING.md](CONTRIBUTING.md) | +| Understand CI selection and required checks | [ci.md](ci.md) | +| Call the REST API | [rest-api-usage.md](rest-api-usage.md) | +| Use the Cypher endpoint | [cypher-api.md](cypher-api.md) | +| Use the same-neighbors batch API | [same-neighbors-batch.md](same-neighbors-batch.md) | +| Configure clients or diagnose Server runtime behavior | [server-runtime.md](server-runtime.md) | +| Select, upgrade or recover a storage backend | [storage-lifecycle.md](storage-lifecycle.md) | +| Understand shared module ownership and migration boundaries | [shared-foundation-migration.md](shared-foundation-migration.md) | +| Deploy or operate Kubernetes resources | [Helm README](../helm/hugegraph/README.md) and [Helm docs index](../helm/hugegraph/docs/README.md) | +| Run Docker or Compose environments | [Docker README](../docker/README.md) | + +Module-specific implementation details belong beside the module they describe. Contributor and agent navigation belongs in the root or module `AGENTS.md`; short tool-specific caches under `.serena/` must link back to these authoritative files. + +## Source-of-truth hierarchy + +Use this order when information overlaps: + +1. Executable configuration and source code define current behavior. +2. The closest module README documents module usage and local constraints. +3. This directory documents cross-module build, API, runtime and design topics. +4. The website repository owns long-form user tutorials and release-oriented guides. +5. `AGENTS.md` and `.serena/` summarize navigation for development tools; they must not become independent product documentation. + +A secondary document should link to the canonical source instead of copying version numbers, option tables or procedures that will drift. + +## Writing durable documentation + +- Describe the current contract, supported workflow and operational boundary. Do not record implementation chronology or review discussions. +- Do not embed pull-request links, commit hashes or temporary branch names as durable explanations. Link to a stable file, configuration key, public issue or website section only when it remains useful after the change is merged. +- Give every durable document a clear owner and add it to this index or a module-local index. Avoid isolated Markdown files that are discoverable only through repository search. +- Use task-oriented headings and explicit terms such as component names, configuration keys, file paths and expected results. This improves both human navigation and LLM retrieval. +- Keep prose paragraphs as logical lines. Do not hard-wrap every sentence; wrap near 160 characters only when a long source line becomes difficult to review. Preserve intentional line breaks in lists, tables, code and quoted output. +- Prefer one concise example that users can run over multiple nearly identical examples. Move uncommon recovery procedures or compatibility details into a focused document and link to it. +- State prerequisites, safety implications and verification steps near the operation they qualify. + +## Adding or changing a document + +Before merging a documentation change: + +1. Confirm that an existing document is not already the canonical owner of the topic. +2. Link the new or moved page from this index, a module README or another obvious entry point. +3. Remove duplicated or obsolete text rather than leaving two competing versions. +4. Check relative links, headings, code blocks and commands from the directory where users will run them. +5. Update matching website documentation when public installation, configuration or behavior changes. diff --git a/helm/hugegraph/README.md b/helm/hugegraph/README.md index ec1e2420d6..acf1afc379 100644 --- a/helm/hugegraph/README.md +++ b/helm/hugegraph/README.md @@ -1,343 +1,106 @@ -# HugeGraph HStore Helm Chart +# HugeGraph Helm chart -Deploys **3 PD + 3 Store + 3 Server and Hubble** by default, with authentication -and persistent storage enabled. Requires **Helm 3.10+ and Kubernetes 1.23+**. -The OCI chart is named `hugegraph-helm`; the application and default Kubernetes resource names remain -`hugegraph`. This chart targets HugeGraph 1.8.0 and later; earlier service releases -are not supported. +This chart deploys a distributed HugeGraph cluster on Kubernetes. The default topology is 3 PD, 3 Store and 3 Server replicas with Hubble, authentication and persistent storage enabled. SeaTunnel and Vermeer are optional and disabled by default. -Provide a default StorageClass or prepare matching PVs. The default installation -needs **7 volumes**: 3 × 10 GiB for PD, 3 × 50 GiB for Store, and 1 × 1 GiB -for Hubble. The chart creates PVCs; it does not create a storage provisioner. -SeaTunnel and Vermeer are **disabled by default**, including in the single-node -and cluster presets. Optional components add resources only when enabled. +**Requirements:** Helm 3.10 or later, Kubernetes 1.23 or later, and a default StorageClass or prepared persistent volumes. -## Install a published Chart +## Documentation map -For a quick trial, install the latest available Chart from GHCR: +| Goal | Document | +|---|---| +| Install the chart and choose common values | This README | +| Understand every detailed chart document | [Documentation index](docs/README.md) | +| Operate, scale, upgrade or troubleshoot a cluster | [Operations](docs/operations.md) | +| Install from OCI, mirror images or work offline | [Distribution](docs/distribution.md) | +| Deploy the RAG service | [RAG](docs/rag.md) | +| Enable data import and export | [SeaTunnel](docs/seatunnel.md) | +| Enable graph computation | [Vermeer](docs/vermeer.md) | +| Start from reviewed value files | [Examples](examples/README.md) | +| Inspect every supported value | [`values.yaml`](values.yaml) | + +The root [repository documentation index](../../docs/README.md) links this chart to the wider Server, Docker and development documentation. + +## Install a published chart ```bash kubectl config current-context kubectl get storageclass helm install hugegraph oci://ghcr.io/hugegraph/hugegraph-helm --devel \ - -n hugegraph --create-namespace --wait --timeout 15m + --namespace hugegraph --create-namespace --wait --timeout 15m ``` -> [!TIP] -> `--devel` selects the highest Chart version, including development and stable -> versions, without limiting the version series. For production or reproducible -> installs, replace it with `--version ` and review the images. - -See [distribution and offline installation](docs/distribution.md) for Docker Hub, -the single-node preset and internal OCI/HTTP repositories. Development Charts may -use `latest` images; pin component `image.digest` values when needed. -The source installation and configuration examples below assume a repository -checkout and commands run from its root. +`--devel` is convenient for evaluation because it can select development chart versions. For production or reproducible environments, use an explicit published version and pin image tags or digests after reviewing them. -The [stable bootstrap configuration](docs/operations.md#stable-bootstrap-topology) -always records initialization inputs separately from node replicas. Use a PD -image with separate bootstrap and runtime quorum checks. PD membership changes, -Store admission and safe retirement remain manual operations. Growing from one -Store to three does not change existing data from RF=1 to RF=3; replica policy -is configured independently with `pd.partition.defaultShardCount`. +## Install from source -## Install from source and open Hubble +Run from the repository root: ```bash -helm install hugegraph ./helm/hugegraph -n hugegraph \ - --create-namespace --wait --timeout 15m +helm install hugegraph ./helm/hugegraph \ + --namespace hugegraph --create-namespace --wait --timeout 15m +``` -# Find assigned ports and a reachable node IP -kubectl -n hugegraph get svc hugegraph-server hugegraph-hubble -kubectl get nodes -o wide +Check the deployed services and read the initial administrator password: -# Read the initial admin password +```bash +kubectl -n hugegraph get pods,svc kubectl -n hugegraph get secret hugegraph-admin \ -o jsonpath='{.data.password}' | base64 --decode ``` -Open **`http://:`** and log in as `admin` with that -password. Server API uses `http://:`. -HTTP works directly; a hostname, certificate or extra acknowledgement is not -required. PD remains internal. - -If node access is unavailable, use port-forward: +Use the assigned Hubble service address, or forward it locally: ```bash kubectl -n hugegraph port-forward svc/hugegraph-hubble 8088:8088 -# Open http://127.0.0.1:8088 ``` -Commands assume release/namespace `hugegraph`. For another release, use the names -shown by `kubectl get svc,secret -n `. Default workloads use -`-`; generated Secrets use `-admin`, -`-auth-token`, and `-pd-auth`. - -## Common configurations - -### API only - -Hubble is optional. Current Hubble login requires Server authentication. - -```bash -# Authenticated API, without the UI -helm install hugegraph ./helm/hugegraph -n hugegraph --create-namespace \ - --set hubble.enabled=false - -# Also disable API authentication, if wanted -# Add: --set server.auth.enabled=false -``` - -Inactive credential values may remain in the values file when auth is disabled. - -### Optional components - -| Component | Default | Enable when needed | -|---|---|---| -| Hubble | Enabled | `hubble.enabled=false` selects API-only deployment | -| SeaTunnel | Disabled | `seatunnel.enabled=true` adds data import/export and its native UI | -| Vermeer | Disabled | `vermeer.enabled=true` adds graph computation, Hubble integration and its native UI | - -
-SeaTunnel: optional import, export and migration - -Set `seatunnel.enabled=true` to start one long-running hybrid member alongside HugeGraph; -set `seatunnel.mode=cluster` to use multiple members of the same native StatefulSet -(two by default). SeaTunnel is disabled by default and its topology is independent -of the HugeGraph single-/multi-node presets. Both modes include the engine's task UI. -Native HTTP defaults to NodePort in easy mode and ClusterIP in strict mode. - -Only authenticated HTTP is exposed through NodePort; member/CLI port 5801 stays -restricted to same-release callers in both modes. Strict additionally limits -egress. Actual isolation needs a supporting CNI and trusted namespace RBAC. - -The chart injects the same-release Server address, GraphSpace and administrator -Secret references into the mounted Source/Sink examples. Create the target graph -before submitting them manually; Helm does not create graphs or import data. -UI and REST submission use a separate native HTTP Basic administrator account -with a newly generated 6-character password in `easy` or 16 characters in `strict`; online upgrades reuse the -existing Secret, including credentials created by older releases. Container -security and scheduling options follow the other components; see the -[SeaTunnel deployment guide](docs/seatunnel.md) for configuration and limits. - -
+Then open `http://127.0.0.1:8088` and sign in as `admin`. -
-Vermeer: optional graph computation with Hubble +## Choose a topology -Enable Vermeer with `--set vermeer.enabled=true`. The default -`vermeer.mode=standalone` runs one Master and one Worker as two containers in -one Pod. Set `vermeer.mode=cluster` for one Master Pod and multiple Worker Pods -(`vermeer.worker.replicas=3` by default). Both HugeGraph presets leave Vermeer -disabled; choose the compute topology explicitly when enabling it. +| Configuration | Purpose | +|---|---| +| Default `values.yaml` | 3 PD, 3 Store, 3 Server and Hubble | +| `values-single.yaml` | Small 1 PD, 1 Store, 1 Server environment for evaluation | +| `values-cluster.yaml` | Cluster scheduling, anti-affinity and resource starting points | +| `values-strict.yaml` | Private service defaults and NetworkPolicy-oriented deployment | -With Hubble enabled in its default PD mode, the chart configures the internal -Master URL and service token automatically. Sign in to Hubble as the HugeGraph -administrator, select an HStore graph, then load it and run an algorithm. The -existing flow includes reload, task status/cancellation, paginated results and -unload; it does not write results back into HugeGraph properties. +Topology presets do not automatically enable SeaTunnel or Vermeer. Enable optional components explicitly and choose their own standalone or cluster mode. -Native Vermeer UI/API uses NodePort in easy mode and ClusterIP in strict mode, -with a separate generated password: 6 characters in `easy`, 16 in `strict`. -Hubble needs no manual token configuration. Internal RPC stays private. -See the [Vermeer deployment guide](docs/vermeer.md) for administration and recovery. +## Common settings -
+| Goal | Value | +|---|---| +| Disable Hubble | `hubble.enabled=false` | +| Disable Server authentication for a trusted local environment | `server.auth.enabled=false` | +| Disable persistent storage for a disposable new installation | `persistence.enabled=false` | +| Select a StorageClass | `pd.storage.storageClassName`, `store.storage.storageClassName`, `hubble.persistence.storageClassName` | +| Use an internal image registry | `global.imageRegistry` | +| Enable SeaTunnel | `seatunnel.enabled=true` | +| Enable Vermeer | `vermeer.enabled=true` | +| Change Server, PD or Store replicas | `server.replicas`, `pd.replicas`, `store.replicas` | +| Choose public or private service entry | Component `service.type` or chart `mode` | -### Internal image registry +Use `--set` for small overrides and a reviewed YAML file for repeatable installations. [`values.yaml`](values.yaml) is the authoritative option reference; examples show complete combinations without duplicating the full option table here. -Mirror the four component images (`hugegraph/pd`, `hugegraph/store`, -`hugegraph/server`, `hugegraph/hubble`) at the configured tags or digests: +## Optional components -```bash -helm install hugegraph ./helm/hugegraph -n hugegraph --create-namespace \ - --set global.imageRegistry=registry.internal.example.com -``` +### SeaTunnel -A component repository with an explicit registry takes priority over the global -prefix. Set `imagePullSecrets` if the registry needs credentials. -Store's wait init container and Helm test reuse the Store and Server images, -which already contain `curl`; no separate curl image is needed by default. -See the [complete registry example](examples/values-internal-registry.yaml). -When enabled, also mirror `apache/seatunnel` and/or `hugegraph/vermeer` at the -configured versions. Vermeer token initialization reuses its own image. -The optional Vermeer image defaults to `latest` with `Always` pull policy, like -the other HugeGraph components. See [image compatibility and upgrades](docs/vermeer.md#image-compatibility) -for image settings and production pinning. +SeaTunnel provides import, export and graph-to-graph migration. Enable it with `seatunnel.enabled=true`, then follow the [SeaTunnel guide](docs/seatunnel.md) for standalone or cluster mode, credentials, example jobs and operational limits. -### Storage +### Vermeer -Use a named dynamic StorageClass when the cluster has no suitable default: +Vermeer provides graph computation and Hubble integration. Enable it with `vermeer.enabled=true`, then follow the [Vermeer guide](docs/vermeer.md) for topology, authentication, storage and recovery. -```bash -helm install hugegraph ./helm/hugegraph -n hugegraph --create-namespace \ - --set pd.storage.storageClassName=my-csi \ - --set store.storage.storageClassName=my-csi \ - --set hubble.persistence.storageClassName=my-csi -``` +### RAG -Empty `storageClassName` inherits the cluster default. `"-"` explicitly selects -no StorageClass. Neither creates a provisioner. For local disks, prepare host -directories and PVs first; the [seven-volume local example](examples/README.md#storage) -includes node affinity, capacities and scheduling requirements. - -For a **new temporary installation**, add `--set persistence.enabled=false` -to use `emptyDir`. Component storage flags override that global setting. -PVC failures never cause an automatic fallback. Do not switch initialized -PD/Store data between persistent and temporary storage. -Vermeer adds separate Master and Worker data claims: two in standalone mode, -or one Master claim plus one per Worker in cluster mode. Its storage flags -inherit `persistence.enabled`; see [Vermeer storage](docs/vermeer.md#storage-and-recovery). - -Hubble persists its Text2GQL master key alongside H2. Existing releases may -need a one-time API-key re-entry; see [Text2GQL credentials](docs/operations.md#hubble-text2gql-credentials). - -### PD metadata namespace - -`metadataCluster` defaults to `hg-test`, preserving the namespace used by existing -Server images. The chart gives Server and Store the same value so Store scans -can find the Server's Schema. This is separate from a graph space or Raft group. -Changing it does not migrate metadata; upgrades reject changes to a recorded -namespace. See [metadata namespace adoption](docs/operations.md#pd-metadata-namespace) -before upgrading a deployment that used custom metadata settings. - -### Server service identity - -`server.serviceId` and `server.graphSpace` select the Server's PD service metadata. -Both default to `DEFAULT`, which preserves the image configuration. Non-default -values inject `HG_SERVER_SERVICE_ID` and `HG_SERVER_GRAPHSPACE` for the image -entrypoint. Service IDs accept printable ASCII, including spaces and backslashes; -the full name, including `/` and `-`, survives metadata reload and graph-space -clearing. Dollar signs remain literal through Kubernetes environment expansion. -Graph spaces must be `DEFAULT` or up to 48 lowercase letters, digits and -underscores, starting with a letter. Create the target space before starting its -assigned Server; these settings do not create it. - -```bash -helm upgrade --install hugegraph ./helm/hugegraph -n hugegraph \ - --set-string server.serviceId=analytics \ - --set-string server.graphSpace=team_a \ - --set-string server.testGraphAlias=team_a-demo -``` - -Use a chart and Server image build from the same source version containing these -mappings. Older release images without them ignore these environment settings; -select a matching image build explicitly. The chart does not detect old images. -The Server's existing `SERVICE_ID` normalization (`GraphManager.serviceId()`) is -unchanged: select `GRAPHSPACE` and the complete raw `SERVICE_NAME` in discovery -queries. Identifier-only lookup has no uniqueness or isolation guarantee. - -`server.testGraphAlias` selects an existing Gremlin binding for every Server Pod, -defaulting to `DEFAULT-hugegraph`. It does not create a graph or infer its binding -from `server.graphSpace`. Match the binding's case: `Demo.properties` can register -`DEFAULT-Demo`, while REST-created graph names are lowercase. A successful query -of the default local binding does not verify a graph in `team_a`. Before replacing -a Pod after `Could not rebind`, verify that the graph exists and the selected alias -matches its binding; restarting cannot create a missing graph or correct an alias. - -These settings do not change the REST default path graph space or Hubble's -selected service. Use explicit `/graphspaces/team_a/...` paths and the matching -Hubble selection. Non-default discovery, authentication and graph-space isolation -still need verification with a running Linux cluster. See the -[container identity contract](../../docker/README.md#server-service-identity). - -## Modes and entry points - -`values-single.yaml` and `values-cluster.yaml` select the HugeGraph topology. -The independent `vermeer.mode` and `seatunnel.mode` select optional engine -topologies; none of these presets enables an optional engine automatically. - -`mode: easy` defaults HTTP entries to NodePort. `mode: strict` defaults them to ClusterIP -and enables full NetworkPolicy isolation; authentication, Hubble and persistence stay enabled. -Use `--set mode=strict` or `-f helm/hugegraph/values-strict.yaml`. - -**Explicit component value > global value > mode default.** An explicit `false` -is preserved; null component values inherit. The global settings are -`persistence.enabled` and `global.imageRegistry`. SeaTunnel/Vermeer HTTP stays -authenticated and peer channels remain internal. No mode requires HTTPS. - -Server/Hubble entry choices: - -| Entry | Access | When to use it | -|---|---|---| -| NodePort | Reachable node IP + assigned port | Direct access without another controller; easy default | -| ClusterIP | Internal Service IP/DNS | In-cluster clients, an existing gateway or port-forward | -| LoadBalancer | Infrastructure-assigned address | A load balancer controller is available | -| Ingress | HTTP routes through a controller | Shared HTTP routing; hostname and TLS are optional | - -ClusterIP is an internal virtual service address, not a node IP. An ordinary -laptop usually cannot reach it directly. With default `externalTrafficPolicy: -Cluster`, NodePort can forward through a node that does not host the target Pod. - -Native HTTP supports only ClusterIP/NodePort. A null `service.type` inherits the -mode; existing explicit ClusterIP values stay private. The ClusterIP fallback -applies only when the effective merged values lack `mode`. An upgrade using new -chart defaults can instead inherit `mode: easy` and NodePort. To keep native HTTP -private during upgrades, explicitly set `seatunnel.service.type` and -`vermeer.service.type` to `ClusterIP`. Entry commands are in the -[SeaTunnel](docs/seatunnel.md) and -[Vermeer](docs/vermeer.md#optional-native-administration) guides. - -To fix a NodePort, set the component's `service.nodePort`. -Omission or `0` allocates automatically. Kubernetes validates the actual cluster -range; the chart does not force `30000–32767`. - -A [hostless HTTP Ingress example](examples/values-http-ingress.yaml) is available. -With base-service NetworkPolicy enabled, add rules for actual clients and controllers; -empty external rule lists are valid but can block access. Explicit Service and -policy values override either mode. Legacy exposure acknowledgement fields are -accepted for compatibility and no longer gate rendering. - -## Common parameters - -Defaults below describe a fresh easy-mode install. Supply `--set` or a YAML file -with `-f`; see [values.yaml](values.yaml) for all fields and their comments. - -| Parameter | Meaning | Default | -|---|---|---| -| `mode` | Entry and policy defaults | `easy` | -| `pd.replicas` / `store.replicas` / `server.replicas` | Component replicas | `3` / `3` / `3` | -| `hubble.enabled` | Install the UI | `true` | -| `seatunnel.enabled` / `vermeer.enabled` | Install optional data/computation engines | `false` / `false` | -| `vermeer.mode` | One Pod with two containers, or separate Master/Worker Pods | `standalone` | -| `vermeer.worker.replicas` | Worker Pods in Vermeer cluster mode | `3` | -| `server.auth.enabled` | Server authentication | `true` | -| `server.service.type` / `hubble.service.type` | Explicit entry type; null inherits mode | resolved `NodePort` | -| `seatunnel.service.type` / `vermeer.service.type` | Optional native HTTP entry; null inherits mode | resolved `NodePort` when enabled | -| `pd.service.type` | PD client entry type | `ClusterIP` | -| `*.service.nodePort` | Fixed component HTTP NodePort; omitted/0 allocates automatically | unset | -| `global.imageRegistry` | Prefix image repositories without an explicit registry | `""` | -| `*.image.repository` / `tag` / `digest` | Component image; digest takes priority | see values | -| `persistence.enabled` | Global persistent storage | `true` | -| `pd.storage.enabled` / `store.storage.enabled` / `hubble.persistence.enabled` | Explicit component storage override | `null` (inherits) | -| `*.storageClassName` | Cluster default when empty; `"-"` means no class | `""` | -| `pd.storage.size` / `store.storage.size` / `hubble.persistence.size` | Volume capacities | `10Gi` / `50Gi` / `1Gi` | -| `server.serviceId` / `server.graphSpace` | PD service name and existing graph space | `DEFAULT` / `DEFAULT` | -| `server.testGraphAlias` | Existing Gremlin binding checked by `helm test` | `DEFAULT-hugegraph` | -| `server.storageWaitTimeoutSeconds` | Storage-ready deadline | `300` | -| `networkPolicy.enabled` | Explicit policy override; null inherits mode | resolved `false` | - -
-Advanced settings and presets - -- [Operations](docs/operations.md): credentials, probes, upgrades, membership, - scheduling, policies and troubleshooting. -- [Deployment examples](examples/README.md): private registry, local volumes, - fixed GitOps credentials, external Secrets, HTTP Ingress and API-only usage. -- `values-single.yaml`: 1 PD + 1 Store + 1 Server, with Hubble and authentication. -- `values-cluster.yaml`: required PD/Store anti-affinity, resources and controlled - Store updates. NetworkPolicy inherits mode; the preset is a capacity starting point. -- Base PD/Server/Hubble client Services support native `externalTrafficPolicy`, `loadBalancerClass`, - `loadBalancerIP`, `loadBalancerSourceRanges`, `externalIPs` and - `allocateLoadBalancerNodePorts`, subject to cluster/controller support. -- Resources, JVM options, scheduling, probes, HPA/PDB, metadata and external - Hubble discovery are configured under their components in `values.yaml`. - Default images preserve automatic JVM sizing; set resources for your capacity. - -
+The chart can deploy HugeGraph AI's RAG service. Follow the [RAG guide](docs/rag.md) for model credentials, network exposure, persistence and compatibility requirements. ## Upgrade and verify +Review the active values before upgrading: + ```bash helm get values hugegraph -n hugegraph --all helm upgrade hugegraph ./helm/hugegraph -n hugegraph --reuse-values \ @@ -345,83 +108,18 @@ helm upgrade hugegraph ./helm/hugegraph -n hugegraph --reuse-values \ helm test hugegraph -n hugegraph --logs --timeout 5m ``` -`--reuse-values` preserves existing UI, entry, storage and credential settings. -An easy-mode upgrade that inherits Server/Hubble entry types prints a short -NodePort-default notice in NOTES; explicitly configured entry types are preserved. -To adopt new defaults, use `--reset-values` with a reviewed values file retaining -all settings your release needs. - -PD, Store and Server images built from this version run as UID/GID `10001`. The -PD and Store pods get `fsGroup: 10001` (with `fsGroupChangePolicy: OnRootMismatch`) -unless their `podSecurityContext` sets `fsGroup`, also when `--reuse-values` keeps -an older release's empty value, so that user can write PVCs created by older -images, which ran as root. - -Switch PD and Store to images 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 the published `latest` before it moves 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: +`--reuse-values` preserves existing settings; `--reset-values` adopts new defaults and therefore requires a complete reviewed values file. Always verify Pod readiness, a fresh Hubble login and at least one business query after the upgrade. Templates and linting cannot prove storage, networking or application behavior in a live cluster. -```bash -helm upgrade hugegraph ./helm/hugegraph -n hugegraph --reuse-values \ - --set pd.image.tag= \ - --set store.image.tag= \ - --set-string pd.image.digest= \ - --set-string store.image.digest= \ - --set pd.podSecurityContext.fsGroupChangePolicy=Always \ - --set store.podSecurityContext.fsGroupChangePolicy=Always \ - --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: - -```bash -kubectl get pods -n hugegraph \ - -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.containers[*].image}{"\n"}{end}' -``` +## Operational boundaries -`--reuse-values` keeps `Always`, which walks the whole volume on every Pod -start, so set the policy back once those Pods are running: +- PD and Store membership changes are coordinated operations. Changing a replica count in values does not by itself complete every safe join, transfer or retirement step; use the [operations guide](docs/operations.md). +- Increasing Store replicas does not retroactively change existing data from replication factor 1 to replication factor 3. Replica policy and node count are separate concerns. +- Persistent PD and Store data must keep stable identities and metadata settings. Do not switch an initialized deployment between temporary and persistent storage. +- Generated Secrets provide initial credentials. Changing a Secret alone does not necessarily rotate an account already stored by an application. +- Pin compatible chart and component image versions for production. A chart cannot reliably infer behavior that an older image does not implement. -```bash -helm upgrade hugegraph ./helm/hugegraph -n hugegraph --reuse-values \ - --set pd.podSecurityContext.fsGroupChangePolicy=OnRootMismatch \ - --set store.podSecurityContext.fsGroupChangePolicy=OnRootMismatch \ - --wait --timeout 15m -``` +## More resources -See [Storage and upgrades](docs/operations.md#storage-and-upgrades) for volumes -the kubelet cannot change. Older explicit helper images also remain under -value reuse; clear `store.waitImage` and `server.waitImage` to reuse component images. - -The admin Secret is an **initial credential**. Changing it alone does not rotate -an existing account; follow [credential rotation](docs/operations.md#credentials). -The chart checks persisted Raft identities and storage/membership changes during -upgrades; those changes require a coordinated procedure. - -`helm --wait` checks readiness. `helm test` checks graph binding and visible -associated indexes for `CREATED` status on each Server Pod. 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, and indexed queries may keep failing until -those Pods restart after the jobs finish. It does not prove index query results; add -[business assertions](docs/operations.md#business-query-assertions) -with `--set-file server.testGremlin=assertions.groovy`. Also verify a fresh Hubble -login and graph query. Templates and linting alone do not prove live volume, -network or application behavior. - -Website guides: [Helm deployment](https://hugegraph.apache.org/docs/quickstart/hugegraph/hugegraph-helm/) -and [Kubernetes operations](https://hugegraph.apache.org/docs/quickstart/hugegraph/hugegraph-helm-operations/). +- [Official Helm deployment guide](https://hugegraph.apache.org/docs/quickstart/hugegraph/hugegraph-helm/) +- [Official Kubernetes operations guide](https://hugegraph.apache.org/docs/quickstart/hugegraph/hugegraph-helm-operations/) +- [Artifact Hub package](https://artifacthub.io/packages/helm/hugegraph-helm/hugegraph-helm) diff --git a/helm/hugegraph/docs/README.md b/helm/hugegraph/docs/README.md new file mode 100644 index 0000000000..f3b38c0a6e --- /dev/null +++ b/helm/hugegraph/docs/README.md @@ -0,0 +1,49 @@ +# Helm documentation index + +The chart [README](../README.md) is the installation and configuration entry point. This directory contains focused operational and optional-component guides that would make the entry point difficult to scan if kept inline. + +## Documents + +| Document | Read it when you need to... | +|---|---| +| [distribution.md](distribution.md) | Install from OCI or HTTP repositories, mirror images, work offline, or choose a single-node distribution path | +| [operations.md](operations.md) | Manage credentials, persistence, bootstrap, membership, scaling, upgrades, scheduling, policies, probes and troubleshooting | +| [rag.md](rag.md) | Deploy and secure the HugeGraph AI RAG service through the chart | +| [seatunnel.md](seatunnel.md) | Configure SeaTunnel import, export and migration in standalone or cluster mode | +| [vermeer.md](vermeer.md) | Configure Vermeer computation, Hubble integration, native administration, storage and recovery | + +Reviewed value combinations live under [`../examples/`](../examples/). The complete value schema and comments live in [`../values.yaml`](../values.yaml). Keep those as the source of truth instead of copying every value into each guide. + +## Recommended reading paths + +### First installation + +1. [Chart README](../README.md) +2. [Distribution](distribution.md) when the published OCI chart or default images are not directly reachable +3. [Examples](../examples/README.md) for a complete registry, storage, Ingress or GitOps configuration + +### Production preparation or upgrade + +1. [Operations](operations.md) +2. The active release values from `helm get values ... --all` +3. Relevant optional-component guide when SeaTunnel, Vermeer or RAG is enabled + +### Incident or recovery + +Start with the matching section in [operations.md](operations.md). Follow links into component-specific guides only when the failure belongs to that component. Record durable recovery rules in the canonical guide rather than appending an incident timeline. + +## Documentation ownership + +- `../README.md` owns chart purpose, first install, topology selection, common settings and high-level boundaries. +- `operations.md` owns procedures that can affect availability, identity, credentials or persistent data. +- Optional-component guides own their component-specific setup and failure modes. +- `../values.yaml` owns option names, defaults and field-level comments. +- The website owns long-form user tutorials and release-facing documentation. + +## Authoring rules + +- Link every durable page from this index or an obvious parent section. Do not leave operational instructions as isolated Markdown files. +- Explain the supported current procedure, prerequisites, safety boundary and verification result. Avoid review history, temporary workarounds and change-by-change narratives. +- Do not use pull-request links, commit hashes or branch names as permanent evidence. Prefer stable source paths, value names and public user documentation. +- Keep prose paragraphs as logical lines. Wrap near 160 characters only when necessary for review; preserve structure in tables, lists and code blocks. +- When a value or default changes, update `values.yaml`, the smallest relevant guide and any corresponding website page in the same change. From 056f61a11c7c27fa1a047ec3ab548222b310e53e Mon Sep 17 00:00:00 2001 From: imbajin Date: Sun, 8 Nov 2026 13:13:46 +0800 Subject: [PATCH 2/8] docs: address deployment and architecture review --- .editorconfig | 2 +- .serena/memories/architecture_and_modules.md | 7 +++-- .serena/memories/project_overview.md | 2 +- README.md | 28 ++++++++++++++------ docs/README.md | 1 + helm/hugegraph/README.md | 19 ++++++++++++- 6 files changed, 46 insertions(+), 13 deletions(-) diff --git a/.editorconfig b/.editorconfig index a275803cec..e769ddc280 100644 --- a/.editorconfig +++ b/.editorconfig @@ -33,7 +33,7 @@ indent_size = 4 continuation_indent_size = 8 [*.md] -max_line_length = 160 +max_line_length = unset ij_visual_guides = 160 ij_wrap_on_typing = false diff --git a/.serena/memories/architecture_and_modules.md b/.serena/memories/architecture_and_modules.md index 7481a60db9..92b422e81f 100644 --- a/.serena/memories/architecture_and_modules.md +++ b/.serena/memories/architecture_and_modules.md @@ -4,11 +4,14 @@ Clients and ecosystem tools │ ▼ -HugeGraph Server ─────► RocksDB (standalone) +HugeGraph Server ─────────────────► RocksDB (standalone) │ - └───────────► PD ─────► HStore nodes (distributed) + ├─ metadata / placement lookup ─► PD ── coordinates ─► HStore nodes + └─ graph data requests ──────────────────────────────► HStore nodes (distributed) ``` +PD supplies metadata, placement and membership information; Server sends graph data requests directly to the selected HStore nodes. + ## Top-level ownership - `hugegraph-server/`: graph engine, schema, tasks, traversers, REST/Gremlin/Cypher APIs and storage adapters. diff --git a/.serena/memories/project_overview.md b/.serena/memories/project_overview.md index 047305d69f..8a60b3cc93 100644 --- a/.serena/memories/project_overview.md +++ b/.serena/memories/project_overview.md @@ -4,7 +4,7 @@ Apache HugeGraph is a graph database with standalone and distributed deployment ## Deployment modes -- **Standalone:** HugeGraph Server uses embedded RocksDB. This is the shortest path for development and smaller deployments. +- **Standalone:** HugeGraph Server uses embedded RocksDB by default. The HBase backend remains supported but is deprecated. RocksDB is the shortest path for development and smaller deployments. - **Distributed:** Server handles graph APIs, PD owns placement and metadata coordination, and HStore nodes own partition data and replication. ## Authoritative entry points diff --git a/README.md b/README.md index 60c7f60264..12eef11208 100644 --- a/README.md +++ b/README.md @@ -35,22 +35,33 @@ Applications can use REST APIs, Gremlin, Cypher or client SDKs. Gremlin compatib ## Quick start -Start a standalone server for local evaluation: +Start a standalone server for local evaluation, bind it to the loopback interface and wait for the version endpoint before continuing: ```bash -docker run -d --name hugegraph -p 8080:8080 hugegraph/hugegraph -curl http://localhost:8080/versions +docker run -d --name hugegraph \ + -p 127.0.0.1:8080:8080 hugegraph/hugegraph + +for attempt in $(seq 1 60); do + if curl -fs http://127.0.0.1:8080/versions; then + break + fi + if [ "${attempt}" -eq 60 ]; then + docker logs hugegraph + exit 1 + fi + sleep 2 +done ``` Run a small graph query: ```bash -curl -X POST http://localhost:8080/gremlin \ +curl -X POST http://127.0.0.1:8080/gremlin \ -H 'Content-Type: application/json' \ -d '{"gremlin":"g.V().limit(5)"}' ``` -The default image is intended for local evaluation. Pin a released image for repeatable deployments and enable authentication before exposing the service outside a trusted network. See the [server deployment guide](https://hugegraph.apache.org/docs/quickstart/hugegraph-server/) for packages, configuration and production preparation. +The loopback bind keeps this evaluation endpoint off ordinary remote interfaces while authentication is not enabled. Users of older Docker or unusual host-network setups should also restrict host firewall access explicitly. Pin a released image for repeatable deployments and enable authentication before exposing the service outside a trusted network. See the [server deployment guide](https://hugegraph.apache.org/docs/quickstart/hugegraph-server/) for packages, configuration and production preparation. ## Deployment @@ -62,15 +73,16 @@ The default image is intended for local evaluation. Pin a released image for rep | Binary installation | [Download and deployment guide](https://hugegraph.apache.org/docs/quickstart/hugegraph-server/) | | Build or customize the source | [Building from source](docs/BUILDING.md) | -A standalone deployment runs Server with embedded RocksDB. A distributed deployment separates query serving, metadata and placement, and partition storage: +A standalone deployment runs Server with embedded RocksDB. In a distributed deployment, Server gets metadata and placement from PD but sends graph data requests directly to HStore nodes: ```text Clients and tools │ ▼ -HugeGraph Server ─────► RocksDB (standalone) +HugeGraph Server ─────────────────► RocksDB (standalone) │ - └──────────────► PD ─────► HStore nodes (distributed) + ├─ metadata / placement lookup ─► PD ── coordinates ─► HStore nodes + └─ graph data requests ──────────────────────────────► HStore nodes (distributed) ``` ## Repository modules diff --git a/docs/README.md b/docs/README.md index df3c56aa09..a00c93e9d4 100644 --- a/docs/README.md +++ b/docs/README.md @@ -18,6 +18,7 @@ This directory contains source-specific documentation for Apache HugeGraph. It c | Understand shared module ownership and migration boundaries | [shared-foundation-migration.md](shared-foundation-migration.md) | | Deploy or operate Kubernetes resources | [Helm README](../helm/hugegraph/README.md) and [Helm docs index](../helm/hugegraph/docs/README.md) | | Run Docker or Compose environments | [Docker README](../docker/README.md) | +| Navigate the repository with Serena | [Serena project context](../.serena/README.md) | Module-specific implementation details belong beside the module they describe. Contributor and agent navigation belongs in the root or module `AGENTS.md`; short tool-specific caches under `.serena/` must link back to these authoritative files. diff --git a/helm/hugegraph/README.md b/helm/hugegraph/README.md index acf1afc379..b3f2482cb3 100644 --- a/helm/hugegraph/README.md +++ b/helm/hugegraph/README.md @@ -99,12 +99,29 @@ The chart can deploy HugeGraph AI's RAG service. Follow the [RAG guide](docs/rag ## Upgrade and verify -Review the active values before upgrading: +Review the active values, then use the same chart source as the installation. + +For a published OCI chart, select an explicit published version: + +```bash +helm get values hugegraph -n hugegraph --all +CHART_VERSION="REPLACE_WITH_PUBLISHED_VERSION" +helm upgrade hugegraph oci://ghcr.io/hugegraph/hugegraph-helm \ + --version "${CHART_VERSION}" -n hugegraph --reuse-values \ + --wait --timeout 15m +``` + +For a source checkout, run the local-path command from the repository root: ```bash helm get values hugegraph -n hugegraph --all helm upgrade hugegraph ./helm/hugegraph -n hugegraph --reuse-values \ --wait --timeout 15m +``` + +Verify either upgrade with: + +```bash helm test hugegraph -n hugegraph --logs --timeout 5m ``` From cf29756951f89182392e0872669ac6988e0cea5c Mon Sep 17 00:00:00 2001 From: dark Date: Sun, 8 Nov 2026 13:46:15 +0800 Subject: [PATCH 3/8] docs: restore Helm anchors and safe readiness check --- README.md | 5 +++-- helm/hugegraph/README.md | 12 ++++++++++++ 2 files changed, 15 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 12eef11208..4a5ab48499 100644 --- a/README.md +++ b/README.md @@ -46,14 +46,15 @@ for attempt in $(seq 1 60); do break fi if [ "${attempt}" -eq 60 ]; then + printf 'Server did not become ready; inspect the logs before continuing.\n' >&2 docker logs hugegraph - exit 1 + break fi sleep 2 done ``` -Run a small graph query: +After the version request succeeds, run a small graph query. If the loop reports a timeout, resolve the startup failure before continuing: ```bash curl -X POST http://127.0.0.1:8080/gremlin \ diff --git a/helm/hugegraph/README.md b/helm/hugegraph/README.md index b3f2482cb3..3c6463c292 100644 --- a/helm/hugegraph/README.md +++ b/helm/hugegraph/README.md @@ -67,6 +67,12 @@ Then open `http://127.0.0.1:8088` and sign in as `admin`. Topology presets do not automatically enable SeaTunnel or Vermeer. Enable optional components explicitly and choose their own standalone or cluster mode. +## Modes and entry points + +`mode: easy` defaults HTTP Services to NodePort; `mode: strict` defaults them to ClusterIP and enables NetworkPolicy isolation by default. The chart leaves authentication, Hubble and persistence enabled unless explicitly changed. A NetworkPolicy requires support from the cluster network plugin. + +For inherited settings, an explicit component value takes precedence. An unset component Service type inherits the mode default; an unset component storage flag inherits `persistence.enabled`. Explicit `false` is preserved. Separately, `global.imageRegistry` rewrites component image repository references. Existing explicit Service values remain in effect on upgrade, including with `--reuse-values`; see [SeaTunnel](docs/seatunnel.md) and [Vermeer](docs/vermeer.md#optional-native-administration) for their entry points. + ## Common settings | Goal | Value | @@ -83,6 +89,12 @@ Topology presets do not automatically enable SeaTunnel or Vermeer. Enable option Use `--set` for small overrides and a reviewed YAML file for repeatable installations. [`values.yaml`](values.yaml) is the authoritative option reference; examples show complete combinations without duplicating the full option table here. +### Server service identity + +`server.serviceId` and `server.graphSpace` select the Server's PD service metadata. Both default to `DEFAULT`, preserving the image configuration; non-default values are passed to the Server image as `HG_SERVER_SERVICE_ID` and `HG_SERVER_GRAPHSPACE`. Create a non-default graph space before starting the assigned Server: these settings do not create it. + +Use a Server image that supports these mappings. They do not change the REST default graph-space path or select a Hubble service; `server.testGraphAlias` must also name an existing Gremlin binding. See the [container identity contract](../../docker/README.md#server-service-identity) for validation, compatibility and configuration details. + ## Optional components ### SeaTunnel From 18942c042ab29acb7937a839ca55bc7e3a4a7bee Mon Sep 17 00:00:00 2001 From: dark Date: Sun, 8 Nov 2026 13:49:26 +0800 Subject: [PATCH 4/8] docs: report bounded readiness failures --- README.md | 30 ++++++++++++++++-------------- 1 file changed, 16 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 4a5ab48499..c068c02d23 100644 --- a/README.md +++ b/README.md @@ -38,20 +38,22 @@ Applications can use REST APIs, Gremlin, Cypher or client SDKs. Gremlin compatib Start a standalone server for local evaluation, bind it to the loopback interface and wait for the version endpoint before continuing: ```bash -docker run -d --name hugegraph \ - -p 127.0.0.1:8080:8080 hugegraph/hugegraph - -for attempt in $(seq 1 60); do - if curl -fs http://127.0.0.1:8080/versions; then - break - fi - if [ "${attempt}" -eq 60 ]; then - printf 'Server did not become ready; inspect the logs before continuing.\n' >&2 - docker logs hugegraph - break - fi - sleep 2 -done +( + docker run -d --name hugegraph \ + -p 127.0.0.1:8080:8080 hugegraph/hugegraph || exit 1 + + for attempt in $(seq 1 60); do + if curl -fs --max-time 2 http://127.0.0.1:8080/versions; then + exit 0 + fi + if [ "${attempt}" -eq 60 ]; then + printf 'Server did not become ready; inspect the logs before continuing.\n' >&2 + docker logs hugegraph + exit 1 + fi + sleep 2 + done +) ``` After the version request succeeds, run a small graph query. If the loop reports a timeout, resolve the startup failure before continuing: From f6ea667f0d5afdeee1c3defcb25bbf417c937748 Mon Sep 17 00:00:00 2001 From: dark Date: Sun, 8 Nov 2026 13:51:19 +0800 Subject: [PATCH 5/8] docs: clarify Helm image registry precedence --- helm/hugegraph/README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/helm/hugegraph/README.md b/helm/hugegraph/README.md index 3c6463c292..f6d6705add 100644 --- a/helm/hugegraph/README.md +++ b/helm/hugegraph/README.md @@ -71,7 +71,9 @@ Topology presets do not automatically enable SeaTunnel or Vermeer. Enable option `mode: easy` defaults HTTP Services to NodePort; `mode: strict` defaults them to ClusterIP and enables NetworkPolicy isolation by default. The chart leaves authentication, Hubble and persistence enabled unless explicitly changed. A NetworkPolicy requires support from the cluster network plugin. -For inherited settings, an explicit component value takes precedence. An unset component Service type inherits the mode default; an unset component storage flag inherits `persistence.enabled`. Explicit `false` is preserved. Separately, `global.imageRegistry` rewrites component image repository references. Existing explicit Service values remain in effect on upgrade, including with `--reuse-values`; see [SeaTunnel](docs/seatunnel.md) and [Vermeer](docs/vermeer.md#optional-native-administration) for their entry points. +For inherited settings, an explicit component value takes precedence. An unset component Service type inherits the mode default; an unset component storage flag inherits `persistence.enabled`. Explicit `false` is preserved. Separately, `global.imageRegistry` prefixes unqualified image references such as `hugegraph/server`; already-qualified references such as `ghcr.io/team/server` or `localhost:5000/team/server` are unchanged. To move a qualified image, set its component `image.repository` explicitly; also update qualified `server.waitImage` or `store.waitImage` overrides if used. See the [private registry example](examples/values-internal-registry.yaml). + +Existing explicit Service values remain in effect on upgrade, including with `--reuse-values`; see [SeaTunnel](docs/seatunnel.md) and [Vermeer](docs/vermeer.md#optional-native-administration) for their entry points. ## Common settings @@ -81,7 +83,7 @@ For inherited settings, an explicit component value takes precedence. An unset c | Disable Server authentication for a trusted local environment | `server.auth.enabled=false` | | Disable persistent storage for a disposable new installation | `persistence.enabled=false` | | Select a StorageClass | `pd.storage.storageClassName`, `store.storage.storageClassName`, `hubble.persistence.storageClassName` | -| Use an internal image registry | `global.imageRegistry` | +| Prefix unqualified image references with an internal registry | `global.imageRegistry` | | Enable SeaTunnel | `seatunnel.enabled=true` | | Enable Vermeer | `vermeer.enabled=true` | | Change Server, PD or Store replicas | `server.replicas`, `pd.replicas`, `store.replicas` | From 2538e9a40f684ae4be0ba229187b0bf27e0125ec Mon Sep 17 00:00:00 2001 From: dark Date: Sun, 8 Nov 2026 14:04:40 +0800 Subject: [PATCH 6/8] docs: restore welcoming project and Helm guides --- README.md | 456 +++++++++++++++++++++++++++++------ helm/hugegraph/README.md | 503 ++++++++++++++++++++++++++++++++------- 2 files changed, 805 insertions(+), 154 deletions(-) diff --git a/README.md b/README.md index c068c02d23..1a015d93ba 100644 --- a/README.md +++ b/README.md @@ -1,41 +1,48 @@

- Apache HugeGraph + hugegraph-logo

-

A scalable graph database for connected data and real-time graph workloads

+

A graph database that supports more than 10 billion vertices & edges, high performance and scalability

[![License](https://img.shields.io/badge/license-Apache%202-0E78BA.svg)](https://www.apache.org/licenses/LICENSE-2.0.html) -[![Server CI](https://github.com/apache/hugegraph/actions/workflows/server-ci.yml/badge.svg)](https://github.com/apache/hugegraph/actions/workflows/server-ci.yml) -[![PD and Store CI](https://github.com/apache/hugegraph/actions/workflows/pd-store-ci.yml/badge.svg)](https://github.com/apache/hugegraph/actions/workflows/pd-store-ci.yml) -[![Downloads](https://img.shields.io/github/downloads/apache/hugegraph/total.svg)](https://github.com/apache/hugegraph/releases) +[![HugeGraph-Server CI](https://github.com/apache/hugegraph/actions/workflows/server-ci.yml/badge.svg)](https://github.com/apache/hugegraph/actions/workflows/server-ci.yml) +[![HugeGraph-PD & Store CI](https://github.com/apache/hugegraph/actions/workflows/pd-store-ci.yml/badge.svg)](https://github.com/apache/hugegraph/actions/workflows/pd-store-ci.yml) +[![GitHub Releases Downloads](https://img.shields.io/github/downloads/apache/hugegraph/total.svg)](https://github.com/apache/hugegraph/releases) [![Artifact Hub](https://img.shields.io/endpoint?url=https%3A%2F%2Fartifacthub.io%2Fbadge%2Frepository%2Fhugegraph-helm)](https://artifacthub.io/packages/helm/hugegraph-helm/hugegraph-helm) +[![Ask DeepWiki](https://img.shields.io/badge/Ask-DeepWiki-blue)](https://deepwiki.com/apache/hugegraph)
-**Start here:** [Quick start](#quick-start) · [Deployment](#deployment) · [Documentation](#documentation) · [Development](#development) · [Ecosystem](#ecosystem) +--- -## Apache HugeGraph +**Quick Navigation:** [Architecture](#architecture) • [Quick Start](#quick-start) • [Module Map](#module-map) • [Documentation](#documentation) • [Ecosystem](#ecosystem) • [For Contributors](#contributing) • [Community](#community) -Apache HugeGraph is a graph database for storing, querying and operating connected data at scale. It combines schema management, indexes, graph traversals, pluggable storage and standalone or distributed deployment in one system. +--- -Applications can use REST APIs, Gremlin, Cypher or client SDKs. Gremlin compatibility is provided through Apache TinkerPop; it is one access path alongside HugeGraph's native APIs and services. +## What is Apache HugeGraph? -## Core capabilities +[HugeGraph](https://hugegraph.apache.org/) is a fast and highly-scalable [graph database](https://en.wikipedia.org/wiki/Graph_database). +Billions of vertices and edges can be easily stored into and queried from HugeGraph due to its excellent OLTP capabilities. +HugeGraph is compliant with the [Apache TinkerPop 3](https://tinkerpop.apache.org/) framework allowing complicated graph queries to be +achieved through the powerful [Gremlin](https://tinkerpop.apache.org/gremlin.html) graph traversal language. -| Area | Capability | -|---|---| -| Data model | Property graph with explicit vertex labels, edge labels, property keys and indexes | -| Query and APIs | REST, Gremlin, Cypher, traverser APIs and language-specific clients | -| Storage | Embedded RocksDB for standalone deployments and HStore for distributed clusters | -| Operations | Authentication, metrics, tasks, backup and restore tooling, Docker and Kubernetes deployment | -| Scale | Single-node development through horizontally scalable Server, PD and Store clusters | -| Ecosystem | Data loading, visualization, graph computation, GraphRAG and AI integrations | +## Features -## Quick start +- **Schema Metadata Management**: VertexLabel, EdgeLabel, PropertyKey, and IndexLabel +- **Multi-type Indexes**: Exact query, range query, and complex conditions combination query +- **Plug-in Backend Store Framework**: RocksDB powers standalone deployments and HStore powers distributed clusters. See the [backend evolution guide](hugegraph-server/README.md#backend-evolution-and-compatibility) for compatibility details. +- **Backend Compatibility**: HBase is deprecated but remains supported; see the [backend evolution guide](hugegraph-server/README.md#backend-evolution-and-compatibility). +- **Big Data Integration**: Seamless integration with `Flink`/`Spark`/`HDFS` +- **Complete Graph Ecosystem**: In/out-memory Graph Computing + Graph Visualization & Tools + Graph Learning & AI +- **Dual Query Language Support**: [Gremlin](https://tinkerpop.apache.org/gremlin.html) (via [Apache TinkerPop 3](https://tinkerpop.apache.org/)) and [Cypher](https://en.wikipedia.org/wiki/Cypher_(query_language)) (OpenCypher) -Start a standalone server for local evaluation, bind it to the loopback interface and wait for the version endpoint before continuing: +## Quick Start + +### 5 Minutes Quick Start + +Start a standalone server for local evaluation, bind it to the loopback interface and wait until the graph service is ready before continuing: ```bash ( @@ -43,7 +50,7 @@ Start a standalone server for local evaluation, bind it to the loopback interfac -p 127.0.0.1:8080:8080 hugegraph/hugegraph || exit 1 for attempt in $(seq 1 60); do - if curl -fs --max-time 2 http://127.0.0.1:8080/versions; then + if curl -fs --max-time 2 http://127.0.0.1:8080/graphs; then exit 0 fi if [ "${attempt}" -eq 60 ]; then @@ -56,7 +63,7 @@ Start a standalone server for local evaluation, bind it to the loopback interfac ) ``` -After the version request succeeds, run a small graph query. If the loop reports a timeout, resolve the startup failure before continuing: +After the readiness request succeeds, run a small graph query. If the loop reports a timeout, resolve the startup failure before continuing: ```bash curl -X POST http://127.0.0.1:8080/gremlin \ @@ -66,75 +73,378 @@ curl -X POST http://127.0.0.1:8080/gremlin \ The loopback bind keeps this evaluation endpoint off ordinary remote interfaces while authentication is not enabled. Users of older Docker or unusual host-network setups should also restrict host firewall access explicitly. Pin a released image for repeatable deployments and enable authentication before exposing the service outside a trusted network. See the [server deployment guide](https://hugegraph.apache.org/docs/quickstart/hugegraph-server/) for packages, configuration and production preparation. -## Deployment +## Ecosystem -| Goal | Recommended entry point | -|---|---| -| Local development | [Standalone Docker](docker/README.md) | -| Multi-process or distributed test environment | [Docker Compose examples](docker/README.md) | -| Kubernetes deployment | [HugeGraph Helm chart](helm/hugegraph/README.md) | -| Binary installation | [Download and deployment guide](https://hugegraph.apache.org/docs/quickstart/hugegraph-server/) | -| Build or customize the source | [Building from source](docs/BUILDING.md) | +Complete **HugeGraph** ecosystem components: -A standalone deployment runs Server with embedded RocksDB. In a distributed deployment, Server gets metadata and placement from PD but sends graph data requests directly to HStore nodes: +1. **[hugegraph-toolchain](https://github.com/apache/hugegraph-toolchain)** - Graph tools suite + - [Loader](https://github.com/apache/hugegraph-toolchain/tree/master/hugegraph-loader) - Data import tool + - [Dashboard](https://github.com/apache/hugegraph-toolchain/tree/master/hugegraph-hubble) - Web visualization platform + - [Tool](https://github.com/apache/hugegraph-toolchain/tree/master/hugegraph-tools) - Command-line utilities + - [Client](https://github.com/apache/hugegraph-toolchain/tree/master/hugegraph-client) - Java/Python client SDK -```text -Clients and tools - │ - ▼ -HugeGraph Server ─────────────────► RocksDB (standalone) - │ - ├─ metadata / placement lookup ─► PD ── coordinates ─► HStore nodes - └─ graph data requests ──────────────────────────────► HStore nodes (distributed) +2. **[hugegraph-computer](https://github.com/apache/hugegraph-computer)** - Integrated **graph computing** system + +3. **[hugegraph-ai](https://github.com/apache/hugegraph-ai)** - **Graph AI/LLM/Knowledge Graph** integration + +4. **[hugegraph-doc](https://github.com/apache/hugegraph-doc)** - **Documentation & website** repository + +## Architecture + +HugeGraph supports both **standalone** and **distributed** deployments: + +```mermaid +flowchart TB + CLIENTS["Client Layer
Gremlin Console · REST Client · Cypher Client · SDK/Tools"] + + subgraph Server["HugeGraph Server :8080"] + API[REST API
Jersey 3] + GS[Gremlin Server
TinkerPop] + CS[Cypher Engine
OpenCypher] + CORE[Graph Engine
hugegraph-core] + + API --> CORE + GS --> CORE + CS --> CORE + end + + subgraph Storage["Storage Layer"] + subgraph Standalone["Standalone Mode"] + ROCKS[(RocksDB
Embedded)] + end + + subgraph Distributed["Distributed Mode"] + PD[HugeGraph PD
Metadata and placement] + HSTORE[(HStore
Partitioned storage)] + end + end + + CLIENTS --> Server + CORE --> ROCKS + CORE -.->|metadata and placement| PD + CORE -->|graph data requests| HSTORE + PD -.->|coordinates| HSTORE + + style Server fill:#e1f5ff + style Distributed fill:#fff4e1 + style Standalone fill:#f0f0f0 ``` -## Repository modules -| Module | Responsibility | -|---|---| -| [`hugegraph-server`](hugegraph-server/) | Graph engine, schema, REST/Gremlin/Cypher APIs and backend adapters | -| [`hugegraph-pd`](hugegraph-pd/) | Placement, metadata and distributed-cluster coordination | -| [`hugegraph-store`](hugegraph-store/) | Partition storage and Raft-based replication | -| [`hugegraph-struct`](hugegraph-struct/) | Shared graph structures, identifiers and serialization | -| [`hugegraph-commons`](hugegraph-commons/) | Shared utilities and RPC infrastructure | -| [`helm/hugegraph`](helm/hugegraph/) | Kubernetes chart for Server, PD, Store and optional ecosystem services | +
+Text architecture diagram -## Documentation +``` + ┌─────────────────────────────────────────────────────┐ + │ Client Layer │ + │ Gremlin Console │ REST Client │ Cypher │ SDK/Tools │ + └─────────────────────────┬───────────────────────────┘ + │ + ┌─────────────────────────▼───────────────────────────┐ + │ HugeGraph Server (:8080) │ + │ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │ + │ │ REST API │ │ Gremlin │ │ Cypher Engine │ │ + │ │(Jersey 3)│ │TinkerPop │ │ (OpenCypher) │ │ + │ └────┬─────┘ └────┬─────┘ └────────┬─────────┘ │ + │ └─────────────┼─────────────────┘ │ + │ ┌────────▼────────┐ │ + │ │ Graph Engine │ │ + │ │(hugegraph-core) │ │ + │ └────────┬────────┘ │ + └─────────────────────┼───────────────────────────────┘ + │ + ┌─────────────────┴─────────────────┐ + │ │ + ┌──────────────▼──────────────┐ ┌──────────────▼──────────────┐ + │ Standalone Mode │ │ Distributed Mode │ + │ ┌───────────────────────┐ │ │ ┌───────────────────────┐ │ + │ │ RocksDB │ │ │ │ HugeGraph-PD │ │ + │ │ (embedded) │ │ │ │ (Raft, 3-5 nodes) │ │ + │ └───────────────────────┘ │ │ │ :8620/:8686 │ │ + │ │ │ └───────────┬───────────┘ │ + │ Use Case: │ │ coordinates │ │ + │ Development/Testing │ │ ┌───────────▼───────────┐ │ + │ Single Node │ │ │ HStore │ │ + │ │ │ │ (Raft, 3+ nodes) │ │ + │ Single-node storage │ │ │ :8520 │ │ + └─────────────────────────────┘ │ └───────────────────────┘ │ + │ │ + │ Use Case: │ + │ Production/HA/Cluster │ + │ │ + │ Horizontal scaling │ + └─────────────────────────────┘ +``` -Use the shortest authoritative source for the task: +
-- [Repository documentation index](docs/README.md): build, contribution, API, runtime, storage and internal design documents. -- [Official website documentation](https://hugegraph.apache.org/docs/): user installation, configuration and feature guides. -- [Helm documentation index](helm/hugegraph/docs/README.md): Kubernetes installation, operations and optional components. -- [Docker guide](docker/README.md): local and distributed Compose environments. -- [`AGENTS.md`](AGENTS.md): repository rules and code-navigation hints for contributors and coding agents. +In distributed mode, Server asks PD for metadata and placement, then sends graph data requests directly to HStore; PD coordinates the storage nodes and does not forward graph data. + +See the [backend evolution guide](hugegraph-server/README.md#backend-evolution-and-compatibility) for lifecycle and historical compatibility guidance. + +To use ToplingDB with the RocksDB backend, follow the [three-step switching guide](docs/storage-lifecycle.md#storage-provider-selection-and-toplingdb). + +### Deployment Mode Comparison + +| Mode | Components | Use Case | Scaling | High Availability | +|------|------------|----------|---------|-------------------| +| **Standalone** | Server + RocksDB | Development, Testing, Single Node | Single node | Basic | +| **Distributed** | Server + PD + HStore | Production, HA, Horizontal Scaling | Horizontal scaling | Yes | + +Actual capacity depends on hardware, data and workload. + +### Module Overview + +| Module | Description | +|--------|-------------| +| [hugegraph-server](hugegraph-server) | Core graph engine with REST API, Gremlin/Cypher support, and pluggable backends (RocksDB default) | +| [hugegraph-pd](hugegraph-pd/README.md) | Placement Driver for distributed mode - handles meta storage, partition management and cluster scheduling | +| [hugegraph-store](hugegraph-store/README.md) | Distributed storage with Raft consensus for high availability and horizontal scaling | +| [hugegraph-commons](hugegraph-commons) | Shared utilities, RPC framework and common components | +| [hugegraph-struct](hugegraph-struct/README.md) | Shared schema, IDs, base elements, queries and encoding used by Server and Store | -The repository index explains which location owns each kind of information. Detailed documents should be linked from an index rather than left as isolated files. +See the [1.8.0 shared-foundation migration guide](docs/shared-foundation-migration.md) for Java API changes, module ownership and coordinated upgrade requirements. -## Development -The source build uses Java 17 and Maven 3.6.3 or later. Read versions from the root [`pom.xml`](pom.xml) instead of copying them into secondary documents. + +## Installation + + + +### Prerequisites + +- **Java 17** (required and currently the only supported Java release) +- **Maven 3.6.3+** (for building from source) + +The launch scripts reject Java versions older than 17. That minimum-version +check does not qualify later Java releases; use Java 17 unless another release +is explicitly listed as supported. + +Read the [Server runtime guide](docs/server-runtime.md#runtime-and-client-configuration) +for client configuration and query compatibility checks. + +### Option 1: Docker (Fastest) + +Docker is the quickest way to get started for **testing or development**. Each command below is an alternative; remove or rename an existing `hugegraph` container before trying another. The loopback port binding is for local use: ```bash -mvn clean install -DskipTests -mvn clean install -pl hugegraph-server -am -DskipTests +# Basic usage +docker run -itd --name=hugegraph -p 127.0.0.1:8080:8080 hugegraph/hugegraph:1.7.0 + +# With sample graph preloaded +docker run -itd --name=hugegraph -e PRELOAD=true -p 127.0.0.1:8080:8080 hugegraph/hugegraph:1.7.0 + +# With authentication enabled +docker run -itd --name=hugegraph -e PASSWORD=your_password -p 127.0.0.1:8080:8080 hugegraph/hugegraph:1.7.0 ``` -Before contributing, read [BUILDING.md](docs/BUILDING.md), [CONTRIBUTING.md](docs/CONTRIBUTING.md) and the relevant module `AGENTS.md`. Run the tests required by the changed modules; Server changes commonly require both Server and PD/Store validation. +For advanced Docker configurations, see: -## Ecosystem +* [Docker Documentation](https://hugegraph.apache.org/docs/quickstart/hugegraph-server/#3-deploy) +* [Docker Compose Examples](./docker/) +* [Docker README](./docker/README.md) +* [Server Docker README](hugegraph-server/hugegraph-dist/docker/README.md) + +> **Docker Desktop (Mac/Windows)**: The 3-node distributed cluster (`docker/docker-compose-3pd-3store-3server.yml`) uses Docker bridge networking and works on all platforms including Docker Desktop. Allocate at least 12 GB memory to Docker Desktop. + +> **Note**: Docker images are convenience releases, not **official ASF distribution artifacts**. See [ASF Release Distribution Policy](https://infra.apache.org/release-distribution.html#dockerhub) for details. +> +> **Version Tags**: Use release tags (e.g., `1.7.0`) for stable deployments. The `latest` tag should only be used for testing or development. + +### Option 2: Kubernetes with Helm + +The HStore Helm chart deploys HugeGraph PD, Store, and Server as a distributed +Kubernetes cluster. See the [chart documentation](helm/hugegraph/README.md) for +single-node and highly available presets, configuration, and +upgrade guidance. + + +
+Option 3: Download Binary Package + +Download pre-built packages from the [Download Page](https://hugegraph.apache.org/docs/download/download/). Replace `{version}` below with the version of the package you choose: + +```bash +# Download and extract +# For historical 1.7.0 and earlier releases, use the archive URL and +# set PACKAGE=apache-hugegraph-incubating-{version} instead. +BASE_URL="https://downloads.apache.org/hugegraph/{version}" +PACKAGE="apache-hugegraph-{version}" +# Historical alternative: +# BASE_URL="https://archive.apache.org/dist/incubator/hugegraph/{version}" +# PACKAGE="apache-hugegraph-incubating-{version}" + +wget ${BASE_URL}/${PACKAGE}.tar.gz +tar -xzf ${PACKAGE}.tar.gz +cd ${PACKAGE} + +# Initialize backend storage +bin/init-store.sh + +# Start server +bin/start-hugegraph.sh + +# Check server status +bin/monitor-hugegraph.sh +``` + +For detailed instructions, see the [Binary Installation Guide](https://hugegraph.apache.org/docs/quickstart/hugegraph-server/#32-download-the-binary-tar-tarball). + +
+ +
+Option 4: Build from Source + +Build from source for development or customization: + +```bash +# Clone repository +git clone https://github.com/apache/hugegraph.git +cd hugegraph + +# Build all modules (skip tests for faster build) +mvn clean package -DskipTests + +# Replace VERSION with the project version from pom.xml before extracting +VERSION="" +tar -xzf "hugegraph-server/apache-hugegraph-server-${VERSION}.tar.gz" +cd "apache-hugegraph-server-${VERSION}" + +# Initialize and start +bin/init-store.sh +bin/start-hugegraph.sh +``` + +For detailed build instructions, see [BUILDING.md](docs/BUILDING.md) and [Build from Source Guide](https://hugegraph.apache.org/docs/quickstart/hugegraph-server/#33-source-code-compilation). + +
+ +
+Verify Installation + +Once the server is running, verify the installation: + +```bash +# Check server version +curl http://localhost:8080/versions + +# The response reports the installed server and Gremlin versions. + +# Try Gremlin console (if installed locally) +bin/gremlin-console.sh +``` + +In the Gremlin console: + +```text +gremlin> :remote connect tinkerpop.server conf/remote.yaml +gremlin> :> g.V().limit(5) +``` + +For comprehensive documentation, visit the [HugeGraph Documentation](https://hugegraph.apache.org/docs/). + +Read the [storage lifecycle and recovery guide](docs/storage-lifecycle.md) before restoring data, mounting store directories or upgrading the storage runtime. + +
+ +## Module Map + +
+Developer navigation + +**Developer Navigation**: Find the right module for your task + +| I want to... | Module | Key Path | +|--------------|--------|----------| +| Understand graph operations | `hugegraph-core` | `StandardHugeGraph.java` | +| Modify REST APIs | `hugegraph-api` | `src/.../api/` | +| Add storage backend | `hugegraph-core` | `BackendStore.java` | +| Develop Gremlin features | `hugegraph-core` | `src/.../traversal/` | +| Develop Cypher features | `hugegraph-api` | `src/.../opencypher/` | +| Work on distributed coordination | `hugegraph-pd` | `hg-pd-core/` | +| Work on distributed storage | `hugegraph-store` | `hg-store-core/` | +| Add backend implementations | `hugegraph-server/hugegraph-{backend}` | `hugegraph-rocksdb/`, `hugegraph-hstore/` | +| Understand configuration | `hugegraph-dist` | `src/assembly/static/conf/` | +| Run tests | `hugegraph-test` | Test suites with multiple profiles | + +For repository constraints and module guidance, see [AGENTS.md](AGENTS.md). + +
+ +
+For Contributors + +**New to HugeGraph?** Follow this path to get started: + +1. **Understand the Architecture** + - Read [AGENTS.md](AGENTS.md) for key component relationships and module guidance + - Review the [Architecture Diagram](#architecture) above + +2. **Set Up Your Environment** + - Install Java 17 and Maven 3.6.3+ + - Follow [BUILDING.md](docs/BUILDING.md) for build instructions + - Configure your IDE to use `.editorconfig` for code style and `style/checkstyle.xml` for Checkstyle rules + +3. **Find Your First Issue** + - Browse [Good First Issues](https://github.com/apache/hugegraph/issues?q=label%3A%22good+first+issue%22) + - Check [Help Wanted Issues](https://github.com/apache/hugegraph/issues?q=label%3A%22help+wanted%22) + +4. **Learn the Codebase** + - Use the [Module Map](#module-map) to navigate + - Try [DeepWiki](https://deepwiki.com/apache/hugegraph) for AI-powered codebase understanding + - Run tests to understand behavior: `mvn test -pl hugegraph-server/hugegraph-test -am -P core-test,memory` + - Try modifying a test and see what breaks + +5. **Code Standards** + - Line length: 120 characters + - Indentation: 4 spaces + - No star imports + - Commit format: `feat|fix|refactor(module): description` + +6. **Submit Your Contribution** + - Read [CONTRIBUTING.md](docs/CONTRIBUTING.md) for guidelines + - Follow the [Contribution Guidelines](https://hugegraph.apache.org/docs/contribution-guidelines/) + - Use [GitHub Desktop](https://desktop.github.com/) to simplify the PR process + +
+ +## Documentation + +- [Repository documentation index](docs/README.md): build, API, runtime, storage and internal design guides. +- [Official HugeGraph documentation](https://hugegraph.apache.org/docs/): user guides and released-product instructions. +- [Helm documentation index](helm/hugegraph/docs/README.md): Kubernetes installation, operations and optional components. + +## Contributing + +Welcome to contribute to HugeGraph! + +- **How to Contribute**: See [CONTRIBUTING.md](docs/CONTRIBUTING.md) and [Contribution Guidelines](https://hugegraph.apache.org/docs/contribution-guidelines/) +- **Code Style**: Configure your IDE to use `.editorconfig` for code style and `style/checkstyle.xml` for Checkstyle rules +- **PR Tool**: [GitHub Desktop](https://desktop.github.com/) is recommended for simpler workflow + +Thank you to all the contributors who have helped make HugeGraph better! + +[![contributors graph](https://contrib.rocks/image?repo=apache/hugegraph)](https://github.com/apache/hugegraph/graphs/contributors) + +## License + +HugeGraph is licensed under [Apache 2.0 License](LICENSE). + +## Community + +**Get Help & Stay Connected** + +- **[GitHub Issues](https://github.com/apache/hugegraph/issues)**: Report bugs and request features (quick response) +- **Mailing List**: [dev@hugegraph.apache.org](mailto:dev@hugegraph.apache.org) ([subscribe here](https://hugegraph.apache.org/docs/contribution-guidelines/subscribe/)) +- **Slack**: [ASF HugeGraph Channel](https://the-asf.slack.com/archives/C059UU2FJ23) +- **WeChat**: Scan the QR code to follow Apache HugeGraph official account -| Project | Purpose | -|---|---| -| [HugeGraph Toolchain](https://github.com/apache/hugegraph-toolchain) | Java client, Loader, Hubble, CLI tools and Spark connector | -| [HugeGraph Computer](https://github.com/apache/hugegraph-computer) | Distributed and in-memory graph computation, including Vermeer | -| [HugeGraph AI](https://github.com/apache/hugegraph-ai) | Python client, GraphRAG, knowledge-graph extraction, MCP and graph ML | -| [HugeGraph Documentation](https://github.com/apache/hugegraph-doc) | Website and long-form user documentation | +

+WeChat QR Code +

-## Community and license +## Thanks -- [Contribution guide](https://hugegraph.apache.org/docs/contribution-guidelines/) -- [Issue tracker](https://github.com/apache/hugegraph/issues) -- [Developer mailing list](mailto:dev@hugegraph.apache.org) +HugeGraph relies on the [Apache TinkerPop](http://tinkerpop.apache.org) framework. We are grateful to the TinkerPop community, Titan, and DataStax for their foundational work. Thanks to all contributors and organizations who have helped make HugeGraph possible. -Apache HugeGraph is licensed under the [Apache License 2.0](LICENSE). +You are welcome to contribute to HugeGraph, and we look forward to working with you to build an excellent open-source community. diff --git a/helm/hugegraph/README.md b/helm/hugegraph/README.md index f6d6705add..14b3e13689 100644 --- a/helm/hugegraph/README.md +++ b/helm/hugegraph/README.md @@ -1,121 +1,391 @@ -# HugeGraph Helm chart +# HugeGraph HStore Helm Chart -This chart deploys a distributed HugeGraph cluster on Kubernetes. The default topology is 3 PD, 3 Store and 3 Server replicas with Hubble, authentication and persistent storage enabled. SeaTunnel and Vermeer are optional and disabled by default. +Deploys **3 PD + 3 Store + 3 Server and Hubble** by default, with authentication +and persistent storage enabled. Requires **Helm 3.10+ and Kubernetes 1.23+**. +The OCI chart is named `hugegraph-helm`; the application and default Kubernetes resource names remain +`hugegraph`. This chart targets HugeGraph 1.8.0 and later; earlier service releases +are not supported. -**Requirements:** Helm 3.10 or later, Kubernetes 1.23 or later, and a default StorageClass or prepared persistent volumes. +Provide a default StorageClass or prepare matching PVs. The default installation +needs **7 volumes**: 3 × 10 GiB for PD, 3 × 50 GiB for Store, and 1 × 1 GiB +for Hubble. The chart creates PVCs; it does not create a storage provisioner. +SeaTunnel, Vermeer and RAG are **disabled by default**, including in the single-node +and cluster presets. Optional components add resources only when enabled. -## Documentation map +For a map of the chart guides, see the [documentation index](docs/README.md). +For complete configuration options, see [values.yaml](values.yaml) and the +[deployment examples](examples/README.md). -| Goal | Document | -|---|---| -| Install the chart and choose common values | This README | -| Understand every detailed chart document | [Documentation index](docs/README.md) | -| Operate, scale, upgrade or troubleshoot a cluster | [Operations](docs/operations.md) | -| Install from OCI, mirror images or work offline | [Distribution](docs/distribution.md) | -| Deploy the RAG service | [RAG](docs/rag.md) | -| Enable data import and export | [SeaTunnel](docs/seatunnel.md) | -| Enable graph computation | [Vermeer](docs/vermeer.md) | -| Start from reviewed value files | [Examples](examples/README.md) | -| Inspect every supported value | [`values.yaml`](values.yaml) | +## Install a published Chart -The root [repository documentation index](../../docs/README.md) links this chart to the wider Server, Docker and development documentation. - -## Install a published chart +For a quick trial, install the latest available Chart from GHCR: ```bash kubectl config current-context kubectl get storageclass helm install hugegraph oci://ghcr.io/hugegraph/hugegraph-helm --devel \ - --namespace hugegraph --create-namespace --wait --timeout 15m + -n hugegraph --create-namespace --wait --timeout 15m ``` -`--devel` is convenient for evaluation because it can select development chart versions. For production or reproducible environments, use an explicit published version and pin image tags or digests after reviewing them. +> [!TIP] +> `--devel` selects the highest Chart version, including development and stable +> versions, without limiting the version series. For production or reproducible +> installs, replace it with `--version ` and review the images. + +See [distribution and offline installation](docs/distribution.md) for Docker Hub, +the single-node preset and internal OCI/HTTP repositories. Development Charts may +use `latest` images; pin component `image.digest` values when needed. +The source installation and configuration examples below assume a repository +checkout and commands run from its root. -## Install from source +The [stable bootstrap configuration](docs/operations.md#stable-bootstrap-topology) +always records initialization inputs separately from node replicas. Use a PD +image with separate bootstrap and runtime quorum checks. PD membership changes, +Store admission and safe retirement remain manual operations. Growing from one +Store to three does not change existing data from RF=1 to RF=3; replica policy +is configured independently with `pd.partition.defaultShardCount`. -Run from the repository root: +## Install from source and open Hubble ```bash -helm install hugegraph ./helm/hugegraph \ - --namespace hugegraph --create-namespace --wait --timeout 15m -``` +helm install hugegraph ./helm/hugegraph -n hugegraph \ + --create-namespace --wait --timeout 15m -Check the deployed services and read the initial administrator password: +# Find assigned ports and a reachable node IP +kubectl -n hugegraph get svc hugegraph-server hugegraph-hubble +kubectl get nodes -o wide -```bash -kubectl -n hugegraph get pods,svc +# Read the initial admin password kubectl -n hugegraph get secret hugegraph-admin \ -o jsonpath='{.data.password}' | base64 --decode ``` -Use the assigned Hubble service address, or forward it locally: +On a trusted network, open **`http://:`** and log in +as `admin` with that password. Server API uses +`http://:`. These HTTP connections are unencrypted; +use local port-forwarding or a trusted network for evaluation. Before allowing +access from an untrusted network, use an HTTPS reverse proxy or Ingress and +restrict access appropriately. PD remains internal. + +If node access is unavailable, use port-forward: ```bash kubectl -n hugegraph port-forward svc/hugegraph-hubble 8088:8088 +# Open http://127.0.0.1:8088 ``` -Then open `http://127.0.0.1:8088` and sign in as `admin`. +Commands assume release/namespace `hugegraph`. For another release, use the names +shown by `kubectl get svc,secret -n `. Default workloads use +`-`; generated Secrets use `-admin`, +`-auth-token`, and `-pd-auth`. -## Choose a topology +## Common configurations -| Configuration | Purpose | -|---|---| -| Default `values.yaml` | 3 PD, 3 Store, 3 Server and Hubble | -| `values-single.yaml` | Small 1 PD, 1 Store, 1 Server environment for evaluation | -| `values-cluster.yaml` | Cluster scheduling, anti-affinity and resource starting points | -| `values-strict.yaml` | Private service defaults and NetworkPolicy-oriented deployment | +### API only -Topology presets do not automatically enable SeaTunnel or Vermeer. Enable optional components explicitly and choose their own standalone or cluster mode. +Hubble is optional. Current Hubble login requires Server authentication. -## Modes and entry points +```bash +# Authenticated API, without the UI +helm install hugegraph ./helm/hugegraph -n hugegraph --create-namespace \ + --set hubble.enabled=false -`mode: easy` defaults HTTP Services to NodePort; `mode: strict` defaults them to ClusterIP and enables NetworkPolicy isolation by default. The chart leaves authentication, Hubble and persistence enabled unless explicitly changed. A NetworkPolicy requires support from the cluster network plugin. +# For local or trusted-network testing only, also disable API authentication +# Add: --set server.auth.enabled=false +``` -For inherited settings, an explicit component value takes precedence. An unset component Service type inherits the mode default; an unset component storage flag inherits `persistence.enabled`. Explicit `false` is preserved. Separately, `global.imageRegistry` prefixes unqualified image references such as `hugegraph/server`; already-qualified references such as `ghcr.io/team/server` or `localhost:5000/team/server` are unchanged. To move a qualified image, set its component `image.repository` explicitly; also update qualified `server.waitImage` or `store.waitImage` overrides if used. See the [private registry example](examples/values-internal-registry.yaml). +The default easy mode exposes HTTP services through NodePort. Disable Server +authentication only for local or trusted-network testing; retain it in other +environments. Inactive credential values may remain in the values file when +authentication is disabled. -Existing explicit Service values remain in effect on upgrade, including with `--reuse-values`; see [SeaTunnel](docs/seatunnel.md) and [Vermeer](docs/vermeer.md#optional-native-administration) for their entry points. +### Optional components -## Common settings +| Component | Default | Enable when needed | +|---|---|---| +| Hubble | Enabled | `hubble.enabled=false` selects API-only deployment | +| SeaTunnel | Disabled | `seatunnel.enabled=true` adds data import/export and its native UI | +| Vermeer | Disabled | `vermeer.enabled=true` adds graph computation, Hubble integration and its native UI | +| RAG | Disabled | `rag.enabled=true` adds the RAG service and its resource storage | -| Goal | Value | -|---|---| -| Disable Hubble | `hubble.enabled=false` | -| Disable Server authentication for a trusted local environment | `server.auth.enabled=false` | -| Disable persistent storage for a disposable new installation | `persistence.enabled=false` | -| Select a StorageClass | `pd.storage.storageClassName`, `store.storage.storageClassName`, `hubble.persistence.storageClassName` | -| Prefix unqualified image references with an internal registry | `global.imageRegistry` | -| Enable SeaTunnel | `seatunnel.enabled=true` | -| Enable Vermeer | `vermeer.enabled=true` | -| Change Server, PD or Store replicas | `server.replicas`, `pd.replicas`, `store.replicas` | -| Choose public or private service entry | Component `service.type` or chart `mode` | +
+SeaTunnel: optional import, export and migration -Use `--set` for small overrides and a reviewed YAML file for repeatable installations. [`values.yaml`](values.yaml) is the authoritative option reference; examples show complete combinations without duplicating the full option table here. +Set `seatunnel.enabled=true` to start one long-running hybrid member alongside HugeGraph; +set `seatunnel.mode=cluster` to use multiple members of the same native StatefulSet +(two by default). SeaTunnel is disabled by default and its topology is independent +of the HugeGraph single-/multi-node presets. Both modes include the engine's task UI. +Native HTTP defaults to NodePort in easy mode and ClusterIP in strict mode. -### Server service identity +Only authenticated HTTP is exposed through NodePort; member/CLI port 5801 stays +restricted to same-release callers in both modes. Strict additionally limits +egress. Actual isolation needs a supporting CNI and trusted namespace RBAC. -`server.serviceId` and `server.graphSpace` select the Server's PD service metadata. Both default to `DEFAULT`, preserving the image configuration; non-default values are passed to the Server image as `HG_SERVER_SERVICE_ID` and `HG_SERVER_GRAPHSPACE`. Create a non-default graph space before starting the assigned Server: these settings do not create it. +The chart injects the same-release Server address, GraphSpace and administrator +Secret references into the mounted Source/Sink examples. Create the target graph +before submitting them manually; Helm does not create graphs or import data. +UI and REST submission use a separate native HTTP Basic administrator account +with a newly generated 6-character password in `easy` or 16 characters in `strict`; online upgrades reuse the +existing Secret, including credentials created by older releases. Container +security and scheduling options follow the other components; see the +[SeaTunnel deployment guide](docs/seatunnel.md) for configuration and limits. -Use a Server image that supports these mappings. They do not change the REST default graph-space path or select a Hubble service; `server.testGraphAlias` must also name an existing Gremlin binding. See the [container identity contract](../../docker/README.md#server-service-identity) for validation, compatibility and configuration details. +
-## Optional components +
+Vermeer: optional graph computation with Hubble -### SeaTunnel +Enable Vermeer with `--set vermeer.enabled=true`. The default +`vermeer.mode=standalone` runs one Master and one Worker as two containers in +one Pod. Set `vermeer.mode=cluster` for one Master Pod and multiple Worker Pods +(`vermeer.worker.replicas=3` by default). Both HugeGraph presets leave Vermeer +disabled; choose the compute topology explicitly when enabling it. -SeaTunnel provides import, export and graph-to-graph migration. Enable it with `seatunnel.enabled=true`, then follow the [SeaTunnel guide](docs/seatunnel.md) for standalone or cluster mode, credentials, example jobs and operational limits. +With Hubble enabled in its default PD mode, the chart configures the internal +Master URL and service token automatically. Sign in to Hubble as the HugeGraph +administrator, select an HStore graph, then load it and run an algorithm. The +existing flow includes reload, task status/cancellation, paginated results and +unload; it does not write results back into HugeGraph properties. -### Vermeer +Native Vermeer UI/API uses NodePort in easy mode and ClusterIP in strict mode, +with a separate generated password: 6 characters in `easy`, 16 in `strict`. +Hubble needs no manual token configuration. Internal RPC stays private. +See the [Vermeer deployment guide](docs/vermeer.md) for administration and recovery. -Vermeer provides graph computation and Hubble integration. Enable it with `vermeer.enabled=true`, then follow the [Vermeer guide](docs/vermeer.md) for topology, authentication, storage and recovery. +
-### RAG +
+RAG: optional GraphRAG service -The chart can deploy HugeGraph AI's RAG service. Follow the [RAG guide](docs/rag.md) for model credentials, network exposure, persistence and compatibility requirements. +Enable RAG with `rag.enabled=true` or the [RAG values preset](values-rag.yaml). +RAG is a single process with a separate resource volume; model endpoints must be +reachable from its Pod. Use a compatible HugeGraph AI image, and protect external +access with an authenticated reverse proxy. The [RAG guide](docs/rag.md) covers +model credentials, persisted configuration, network exposure and compatibility. -## Upgrade and verify +
+ +### Internal image registry -Review the active values, then use the same chart source as the installation. +Mirror the four component images (`hugegraph/pd`, `hugegraph/store`, +`hugegraph/server`, `hugegraph/hubble`) at the configured tags or digests: -For a published OCI chart, select an explicit published version: +```bash +helm install hugegraph ./helm/hugegraph -n hugegraph --create-namespace \ + --set global.imageRegistry=registry.internal.example.com +``` + +The global prefix applies to unqualified image references such as +`hugegraph/server`. A component repository with an explicit registry, such as +`ghcr.io/team/server` or `localhost:5000/team/server`, takes priority and is +not rewritten. Set the component `image.repository` explicitly to move such an +image; update qualified `server.waitImage` or `store.waitImage` overrides too. +Set `imagePullSecrets` if the registry needs credentials. +Store's wait init container and Helm test reuse the Store and Server images, +which already contain `curl`; no separate curl image is needed by default. +See the [complete registry example](examples/values-internal-registry.yaml). +When enabled, also mirror `apache/seatunnel` and/or `hugegraph/vermeer` at the +configured versions. Vermeer token initialization reuses its own image. +The optional Vermeer image defaults to `latest` with `Always` pull policy, like +the other HugeGraph components. See [image compatibility and upgrades](docs/vermeer.md#image-compatibility) +for image settings and production pinning. + +### Storage + +Use a named dynamic StorageClass when the cluster has no suitable default: + +```bash +helm install hugegraph ./helm/hugegraph -n hugegraph --create-namespace \ + --set pd.storage.storageClassName=my-csi \ + --set store.storage.storageClassName=my-csi \ + --set hubble.persistence.storageClassName=my-csi +``` + +Empty `storageClassName` inherits the cluster default. `"-"` explicitly selects +no StorageClass. Neither creates a provisioner. For local disks, prepare host +directories and PVs first; the [seven-volume local example](examples/README.md#storage) +includes node affinity, capacities and scheduling requirements. + +For a **new temporary installation**, add `--set persistence.enabled=false` +to use `emptyDir`. Component storage flags override that global setting. +PVC failures never cause an automatic fallback. Do not switch initialized +PD/Store data between persistent and temporary storage. +Vermeer adds separate Master and Worker data claims: two in standalone mode, +or one Master claim plus one per Worker in cluster mode. Its storage flags +inherit `persistence.enabled`; see [Vermeer storage](docs/vermeer.md#storage-and-recovery). + +Hubble persists its Text2GQL master key alongside H2. Existing releases may +need a one-time API-key re-entry; see [Text2GQL credentials](docs/operations.md#hubble-text2gql-credentials). + +### Partition sharding + +For a new installation, `pd.partition.defaultShardCount` sets the initial +replica count for each partition. When unset, the chart seeds RF=1 with fewer +than three Stores and RF=3 with three or more Stores. An explicit value must be +odd and no greater than `store.replicas`. `pd.partition.storeMaxShardCount` +controls the initial shard capacity per Store; see [values.yaml](values.yaml) +for the derivation and defaults. + +PD persists these values during first bootstrap. Scaling Store or changing Helm +values later does not change the persisted replica policy or move existing data. +Use the [bootstrap topology guide](docs/operations.md#stable-bootstrap-topology) +for adoption and coordinated changes. + +### PD metadata namespace + +`metadataCluster` defaults to `hg-test`, preserving the namespace used by existing +Server images. The chart gives Server and Store the same value so Store scans +can find the Server's Schema. This is separate from a graph space or Raft group. +Changing it does not migrate metadata; upgrades reject changes to a recorded +namespace. See [metadata namespace adoption](docs/operations.md#pd-metadata-namespace) +before upgrading a deployment that used custom metadata settings. + +### Server service identity + +`server.serviceId` and `server.graphSpace` select the Server's PD service metadata. +Both default to `DEFAULT`, which preserves the image configuration. Non-default +values inject `HG_SERVER_SERVICE_ID` and `HG_SERVER_GRAPHSPACE` for the image +entrypoint. Service IDs accept printable ASCII, including spaces and backslashes; +the full name, including `/` and `-`, survives metadata reload and graph-space +clearing. Dollar signs remain literal through Kubernetes environment expansion. +Graph spaces must be `DEFAULT` or up to 48 lowercase letters, digits and +underscores, starting with a letter. Create the target space before starting its +assigned Server; these settings do not create it. + +```bash +helm upgrade --install hugegraph ./helm/hugegraph -n hugegraph \ + --set-string server.serviceId=analytics \ + --set-string server.graphSpace=team_a \ + --set-string server.testGraphAlias=team_a-demo +``` + +Use a chart and Server image build from the same source version containing these +mappings. Older release images without them ignore these environment settings; +select a matching image build explicitly. The chart does not detect old images. +The Server's existing `SERVICE_ID` normalization (`GraphManager.serviceId()`) is +unchanged: select `GRAPHSPACE` and the complete raw `SERVICE_NAME` in discovery +queries. Identifier-only lookup has no uniqueness or isolation guarantee. + +`server.testGraphAlias` selects an existing Gremlin binding for every Server Pod, +defaulting to `DEFAULT-hugegraph`. It does not create a graph or infer its binding +from `server.graphSpace`. Match the binding's case: `Demo.properties` can register +`DEFAULT-Demo`, while REST-created graph names are lowercase. A successful query +of the default local binding does not verify a graph in `team_a`. Before replacing +a Pod after `Could not rebind`, verify that the graph exists and the selected alias +matches its binding; restarting cannot create a missing graph or correct an alias. + +These settings do not change the REST default path graph space or Hubble's +selected service. Use explicit `/graphspaces/team_a/...` paths and the matching +Hubble selection. Non-default discovery, authentication and graph-space isolation +still need verification with a running Linux cluster. See the +[container identity contract](../../docker/README.md#server-service-identity). + +## Modes and entry points + +`values-single.yaml` and `values-cluster.yaml` select the HugeGraph topology. +The independent `vermeer.mode` and `seatunnel.mode` select optional engine +topologies; none of these presets enables an optional engine automatically. + +`mode: easy` defaults HTTP entries to NodePort. `mode: strict` defaults them to +ClusterIP and enables NetworkPolicy resources; authentication, Hubble and +persistence stay enabled. Network isolation requires a CNI plugin that supports +and actually enforces Kubernetes NetworkPolicy. Use `--set mode=strict` or +`-f helm/hugegraph/values-strict.yaml`. + +An explicit component value takes precedence. An unset component Service type +inherits the mode default; an unset component storage flag inherits +`persistence.enabled`. Explicit `false` is preserved. The separate +`global.imageRegistry` rule is described in [Internal image registry](#internal-image-registry). +SeaTunnel/Vermeer HTTP stays authenticated and peer channels remain internal. +The chart does not automatically configure TLS. For access over untrusted +networks, provide TLS through an HTTPS proxy or Ingress and restrict access +appropriately. + +Server/Hubble entry choices: + +| Entry | Access | When to use it | +|---|---|---| +| NodePort | Reachable node IP + assigned port | Direct access without another controller; easy default | +| ClusterIP | Internal Service IP/DNS | In-cluster clients, an existing gateway or port-forward | +| LoadBalancer | Infrastructure-assigned address | A load balancer controller is available | +| Ingress | Routes through a controller | Shared routing; configure HTTPS for untrusted networks | + +ClusterIP is an internal virtual service address, not a node IP. An ordinary +laptop usually cannot reach it directly. With default `externalTrafficPolicy: +Cluster`, NodePort can forward through a node that does not host the target Pod. + +Native HTTP supports only ClusterIP/NodePort. A null `service.type` inherits the +mode; existing explicit ClusterIP values stay private. The ClusterIP fallback +applies only when the effective merged values lack `mode`. An upgrade using new +chart defaults can instead inherit `mode: easy` and NodePort. To keep native HTTP +private during upgrades, explicitly set `seatunnel.service.type` and +`vermeer.service.type` to `ClusterIP`. Entry commands are in the +[SeaTunnel](docs/seatunnel.md) and +[Vermeer](docs/vermeer.md#optional-native-administration) guides. + +To fix a NodePort, set the component's `service.nodePort`. +Omission or `0` allocates automatically. Kubernetes validates the actual cluster +range; the chart does not force `30000–32767`. + +A [hostless HTTP Ingress example](examples/values-http-ingress.yaml) is available. +With base-service NetworkPolicy enabled, add rules for actual clients and controllers; +empty external rule lists are valid but can block access. Explicit Service and +policy values override either mode. Legacy exposure acknowledgement fields are +accepted for compatibility and no longer gate rendering. + +## Common parameters + +Defaults below describe a fresh easy-mode install. Supply `--set` or a YAML file +with `-f`; see [values.yaml](values.yaml) for all fields and their comments. + +| Parameter | Meaning | Default | +|---|---|---| +| `mode` | Entry and policy defaults | `easy` | +| `pd.replicas` / `store.replicas` / `server.replicas` | Component replicas | `3` / `3` / `3` | +| `hubble.enabled` | Install the UI | `true` | +| `seatunnel.enabled` / `vermeer.enabled` | Install optional data/computation engines | `false` / `false` | +| `rag.enabled` | Install the optional RAG service | `false` | +| `vermeer.mode` | One Pod with two containers, or separate Master/Worker Pods | `standalone` | +| `vermeer.worker.replicas` | Worker Pods in Vermeer cluster mode | `3` | +| `server.auth.enabled` | Server authentication | `true` | +| `server.service.type` / `hubble.service.type` | Explicit entry type; null inherits mode | resolved `NodePort` | +| `seatunnel.service.type` / `vermeer.service.type` | Optional native HTTP entry; null inherits mode | resolved `NodePort` when enabled | +| `pd.service.type` | PD client entry type | `ClusterIP` | +| `*.service.nodePort` | Fixed component HTTP NodePort; omitted/0 allocates automatically | unset | +| `global.imageRegistry` | Prefix image repositories without an explicit registry | `""` | +| `*.image.repository` / `tag` / `digest` | Component image; digest takes priority | see values | +| `persistence.enabled` | Global persistent storage | `true` | +| `pd.storage.enabled` / `store.storage.enabled` / `hubble.persistence.enabled` | Explicit component storage override | `null` (inherits) | +| `*.storageClassName` | Cluster default when empty; `"-"` means no class | `""` | +| `pd.storage.size` / `store.storage.size` / `hubble.persistence.size` | Volume capacities | `10Gi` / `50Gi` / `1Gi` | +| `server.serviceId` / `server.graphSpace` | PD service name and existing graph space | `DEFAULT` / `DEFAULT` | +| `server.testGraphAlias` | Existing Gremlin binding checked by `helm test` | `DEFAULT-hugegraph` | +| `server.storageWaitTimeoutSeconds` | Storage-ready deadline | `300` | +| `networkPolicy.enabled` | Explicit policy override; null inherits mode | resolved `false` | + +
+Advanced settings and presets + +- [Operations](docs/operations.md): credentials, probes, upgrades, membership, + scheduling, policies and troubleshooting. +- [Deployment examples](examples/README.md): private registry, local volumes, + fixed GitOps credentials, external Secrets, HTTP Ingress and API-only usage. +- `values-single.yaml`: 1 PD + 1 Store + 1 Server, with Hubble and authentication. +- `values-cluster.yaml`: required PD/Store anti-affinity, resources and controlled + Store updates. NetworkPolicy inherits mode; the preset is a capacity starting point. +- Base PD/Server/Hubble client Services support native `externalTrafficPolicy`, `loadBalancerClass`, + `loadBalancerIP`, `loadBalancerSourceRanges`, `externalIPs` and + `allocateLoadBalancerNodePorts`, subject to cluster/controller support. +- Resources, JVM options, scheduling, probes, HPA/PDB, metadata and external + Hubble discovery are configured under their components in `values.yaml`. + Default images preserve automatic JVM sizing; set resources for your capacity. + +
+ +## Upgrade and verify + +Inspect the saved values, then use the same chart source as the installation. +For the published OCI chart, specify the published chart version: ```bash helm get values hugegraph -n hugegraph --all @@ -125,7 +395,7 @@ helm upgrade hugegraph oci://ghcr.io/hugegraph/hugegraph-helm \ --wait --timeout 15m ``` -For a source checkout, run the local-path command from the repository root: +For a source checkout, run from the repository root: ```bash helm get values hugegraph -n hugegraph --all @@ -133,24 +403,95 @@ helm upgrade hugegraph ./helm/hugegraph -n hugegraph --reuse-values \ --wait --timeout 15m ``` -Verify either upgrade with: +After either upgrade, verify the release: ```bash helm test hugegraph -n hugegraph --logs --timeout 5m ``` -`--reuse-values` preserves existing settings; `--reset-values` adopts new defaults and therefore requires a complete reviewed values file. Always verify Pod readiness, a fresh Hubble login and at least one business query after the upgrade. Templates and linting cannot prove storage, networking or application behavior in a live cluster. +`--reuse-values` preserves existing UI, entry, storage and credential settings. +An easy-mode upgrade that inherits Server/Hubble entry types prints a short +NodePort-default notice in NOTES; explicitly configured entry types are preserved. +To adopt new defaults, use `--reset-values` with a reviewed values file retaining +all settings your release needs. + +PD, Store and Server images built from this version run as UID/GID `10001`. The +PD and Store pods get `fsGroup: 10001` (with `fsGroupChangePolicy: OnRootMismatch`) +unless their `podSecurityContext` sets `fsGroup`, also when `--reuse-values` keeps +an older release's empty value, so that user can write PVCs created by older +images, which ran as root. + +Switch PD and Store to images 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 the published `latest` before it moves 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. +The migration commands below use a source checkout and run from the repository +root. For an OCI installation, replace `./helm/hugegraph` with +`oci://ghcr.io/hugegraph/hugegraph-helm` and add the same explicit +`--version "${CHART_VERSION}"` used in the published-chart upgrade above. -## Operational boundaries +```bash +# Replace with the tag of the matching UID/GID 10001 images. +IMAGE_TAG="REPLACE_WITH_IMAGE_TAG" +helm upgrade hugegraph ./helm/hugegraph -n hugegraph --reuse-values \ + --set-string pd.image.tag="${IMAGE_TAG}" \ + --set-string store.image.tag="${IMAGE_TAG}" \ + --set-string pd.image.digest= \ + --set-string store.image.digest= \ + --set pd.podSecurityContext.fsGroupChangePolicy=Always \ + --set store.podSecurityContext.fsGroupChangePolicy=Always \ + --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: + +```bash +kubectl get pods -n hugegraph \ + -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.containers[*].image}{"\n"}{end}' +``` -- PD and Store membership changes are coordinated operations. Changing a replica count in values does not by itself complete every safe join, transfer or retirement step; use the [operations guide](docs/operations.md). -- Increasing Store replicas does not retroactively change existing data from replication factor 1 to replication factor 3. Replica policy and node count are separate concerns. -- Persistent PD and Store data must keep stable identities and metadata settings. Do not switch an initialized deployment between temporary and persistent storage. -- Generated Secrets provide initial credentials. Changing a Secret alone does not necessarily rotate an account already stored by an application. -- Pin compatible chart and component image versions for production. A chart cannot reliably infer behavior that an older image does not implement. +`--reuse-values` keeps `Always`, which walks the whole volume on every Pod +start, so set the policy back once those Pods are running: -## More resources +```bash +helm upgrade hugegraph ./helm/hugegraph -n hugegraph --reuse-values \ + --set pd.podSecurityContext.fsGroupChangePolicy=OnRootMismatch \ + --set store.podSecurityContext.fsGroupChangePolicy=OnRootMismatch \ + --wait --timeout 15m +``` -- [Official Helm deployment guide](https://hugegraph.apache.org/docs/quickstart/hugegraph/hugegraph-helm/) -- [Official Kubernetes operations guide](https://hugegraph.apache.org/docs/quickstart/hugegraph/hugegraph-helm-operations/) -- [Artifact Hub package](https://artifacthub.io/packages/helm/hugegraph-helm/hugegraph-helm) +See [Storage and upgrades](docs/operations.md#storage-and-upgrades) for volumes +the kubelet cannot change. Older explicit helper images also remain under +value reuse; clear `store.waitImage` and `server.waitImage` to reuse component images. + +The admin Secret is an **initial credential**. Changing it alone does not rotate +an existing account; follow [credential rotation](docs/operations.md#credentials). +The chart checks persisted Raft identities and storage/membership changes during +upgrades; those changes require a coordinated procedure. + +`helm --wait` checks readiness. `helm test` checks graph binding and visible +associated indexes for `CREATED` status on each Server Pod. 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, and indexed queries may keep failing until +those Pods restart after the jobs finish. It does not prove index query results; add +[business assertions](docs/operations.md#business-query-assertions) +with `--set-file server.testGremlin=assertions.groovy`. Also verify a fresh Hubble +login and graph query. Templates and linting alone do not prove live volume, +network or application behavior. + +Website guides: [Helm deployment](https://hugegraph.apache.org/docs/quickstart/hugegraph/hugegraph-helm/) +and [Kubernetes operations](https://hugegraph.apache.org/docs/quickstart/hugegraph/hugegraph-helm-operations/). From caae1136ea28c961e8bc63cec143c87a72ec380d Mon Sep 17 00:00:00 2001 From: imbajin Date: Sun, 8 Nov 2026 14:44:07 +0800 Subject: [PATCH 7/8] docs: harden Docker quick-start recovery --- README.md | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 1a015d93ba..dc49bc4823 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,7 @@ achieved through the powerful [Gremlin](https://tinkerpop.apache.org/gremlin.htm ### 5 Minutes Quick Start -Start a standalone server for local evaluation, bind it to the loopback interface and wait until the graph service is ready before continuing: +Start a standalone server for local evaluation, bind it to the loopback interface and wait until a Gremlin query succeeds before continuing: ```bash ( @@ -50,11 +50,14 @@ Start a standalone server for local evaluation, bind it to the loopback interfac -p 127.0.0.1:8080:8080 hugegraph/hugegraph || exit 1 for attempt in $(seq 1 60); do - if curl -fs --max-time 2 http://127.0.0.1:8080/graphs; then + if curl -fsS --max-time 2 -o /dev/null \ + -X POST http://127.0.0.1:8080/gremlin \ + -H 'Content-Type: application/json' \ + -d '{"gremlin":"g.V().limit(1)"}'; then exit 0 fi if [ "${attempt}" -eq 60 ]; then - printf 'Server did not become ready; inspect the logs before continuing.\n' >&2 + printf 'Server query did not become ready; inspect the logs before continuing.\n' >&2 docker logs hugegraph exit 1 fi @@ -63,7 +66,7 @@ Start a standalone server for local evaluation, bind it to the loopback interfac ) ``` -After the readiness request succeeds, run a small graph query. If the loop reports a timeout, resolve the startup failure before continuing: +After the readiness query succeeds, run a small graph query: ```bash curl -X POST http://127.0.0.1:8080/gremlin \ @@ -71,6 +74,13 @@ curl -X POST http://127.0.0.1:8080/gremlin \ -d '{"gremlin":"g.V().limit(5)"}' ``` +A timeout deliberately leaves the named container available for diagnosis. Inspect `docker logs hugegraph` and preserve any required data or attached volumes first. When it is safe to discard the failed container, stop and remove it before retrying: + +```bash +docker stop hugegraph 2>/dev/null || true +docker rm hugegraph +``` + The loopback bind keeps this evaluation endpoint off ordinary remote interfaces while authentication is not enabled. Users of older Docker or unusual host-network setups should also restrict host firewall access explicitly. Pin a released image for repeatable deployments and enable authentication before exposing the service outside a trusted network. See the [server deployment guide](https://hugegraph.apache.org/docs/quickstart/hugegraph-server/) for packages, configuration and production preparation. ## Ecosystem @@ -447,4 +457,4 @@ HugeGraph is licensed under [Apache 2.0 License](LICENSE). HugeGraph relies on the [Apache TinkerPop](http://tinkerpop.apache.org) framework. We are grateful to the TinkerPop community, Titan, and DataStax for their foundational work. Thanks to all contributors and organizations who have helped make HugeGraph possible. -You are welcome to contribute to HugeGraph, and we look forward to working with you to build an excellent open-source community. +You are welcome to contribute to HugeGraph, and we look forward to working with you to build an excellent open-source community. \ No newline at end of file From e3d0fb8a3e65defe44705da6fd9d07488232ae67 Mon Sep 17 00:00:00 2001 From: imbajin Date: Sun, 8 Nov 2026 14:44:51 +0800 Subject: [PATCH 8/8] docs: clarify reused Helm service values --- helm/hugegraph/README.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/helm/hugegraph/README.md b/helm/hugegraph/README.md index 14b3e13689..4e66812fd1 100644 --- a/helm/hugegraph/README.md +++ b/helm/hugegraph/README.md @@ -415,6 +415,15 @@ NodePort-default notice in NOTES; explicitly configured entry types are preserve To adopt new defaults, use `--reset-values` with a reviewed values file retaining all settings your release needs. +A release installed with an older chart may have a NodePort stored in its release values even when the operator never set the Service type explicitly. `--reuse-values` can retain that value, so changing only `mode=strict` does not guarantee that existing Server or Hubble Services become `ClusterIP`. Inspect the effective values and Services after the upgrade: + +```bash +helm get values hugegraph -n hugegraph --all +kubectl -n hugegraph get svc hugegraph-server hugegraph-hubble +``` + +To make existing entries private, explicitly set `server.service.type=ClusterIP` and `hubble.service.type=ClusterIP`—plus the Service type of each enabled optional component—or use `--reset-values` with a complete reviewed values file. Verify the resulting Service types rather than assuming a mode change replaced values retained from an older release. + PD, Store and Server images built from this version run as UID/GID `10001`. The PD and Store pods get `fsGroup: 10001` (with `fsGroupChangePolicy: OnRootMismatch`) unless their `podSecurityContext` sets `fsGroup`, also when `--reuse-values` keeps @@ -494,4 +503,4 @@ login and graph query. Templates and linting alone do not prove live volume, network or application behavior. Website guides: [Helm deployment](https://hugegraph.apache.org/docs/quickstart/hugegraph/hugegraph-helm/) -and [Kubernetes operations](https://hugegraph.apache.org/docs/quickstart/hugegraph/hugegraph-helm-operations/). +and [Kubernetes operations](https://hugegraph.apache.org/docs/quickstart/hugegraph/hugegraph-helm-operations/). \ No newline at end of file