imbajin commented on code in PR #506: URL: https://github.com/apache/hugegraph-doc/pull/506#discussion_r4152765582
########## content/en/docs/quickstart/toolchain/hugegraph-hubble.md: ########## @@ -1,683 +1,323 @@ --- -title: "HugeGraph-Hubble Quick Start" -description: "Deploy HugeGraph-Hubble for graph visualization, schema management, data import, and Gremlin or Cypher queries." -linkTitle: "Visual with HugeGraph-Hubble" +title: "Graph Visualization with Hubble: Standalone Quick Start" +description: "Visualize graph data with Hubble and RocksDB Server: start with Docker, explore schema, import CSV, and run Gremlin queries." +linkTitle: "Hubble Basics and Standalone" weight: 1 -search_keywords: [HugeGraph Hubble, graph visualization, web console] +search_keywords: [HugeGraph Hubble, graph visualization, Web management interface, RocksDB] search_boost: 1.6 --- -### 1 HugeGraph-Hubble Overview +Hubble is the HugeGraph Web management and graph visualization interface. Use one workspace to manage schema, import data, run queries, +and switch between graph, table, and JSON results. This guide uses **standalone RocksDB Server + Hubble**, without PD or Store. -> [!WARNING] -> **Restrict Hubble and Server access in production** -> -> Hubble listens on plain HTTP and must not be exposed directly to the Internet or untrusted networks. Terminate HTTPS at a trusted entry point, restrict source IPs for both Hubble and Server, and enable Server authentication and authorization with minimum permissions. Retain and restrict access to Server `audit-*.log` files. `auth.audit_log_rate` is a per-user rate limit, not a dedicated audit-log switch. Hubble has no separate account database; if Server allows anonymous access, Hubble has no login step. - -> **Version note**: This page follows hugegraph-toolchain `master`. Features that depend on newer Server, PD or Store versions are marked below and are unavailable on older Servers. - -> **Testing Guide**: For running HugeGraph-Hubble tests locally, please refer to [HugeGraph Toolchain Local Testing Guide](/docs/guides/toolchain-local-test) - -HugeGraph-Hubble is HugeGraph's web management interface. It connects to one HugeGraph Server, either directly or through PD in a distributed cluster, manages GraphSpaces, graphs and schemas, imports data, runs Gremlin and Cypher queries and built-in graph algorithms, and visualizes the results. - -The platform mainly includes the following modules: - -##### Graph Overview - -Graph Overview lists GraphSpaces (in PD mode) and graphs. It creates, clones and clears graphs, loads demo graphs, opens the graph detail page with statistics and schema, and jumps to the query workbench. - -##### Metadata Modeling - -Metadata Modeling manages PropertyKeys, VertexLabels, EdgeLabels and IndexLabels of one graph, in list and graph views. Schema Templates keep reusable Groovy schemas per GraphSpace that can be applied when a graph is created. - -##### Data Import - -> The data import page is intended for small-scale trials. For bulk or production imports, use [HugeGraph Loader](/docs/quickstart/toolchain/hugegraph-loader). - -Data Sources register FILE, HDFS, JDBC and KAFKA sources. Import tasks are configured in four steps and can run once, on a cron schedule, or continuously for Kafka. - -##### Graph Query - -Graph Query runs Gremlin and Cypher statements in immediate or asynchronous mode and displays results as a graph (2D or 3D), a table, or JSON. It keeps execution records and favorite statements. - -##### Built-in Graph Algorithms - -Built-in Graph Algorithms provides forms for the Server's OLTP traverser APIs (interactive exploration) and for OLAP jobs (cluster batch computation through HugeGraph Computer or Vermeer). - -##### Async Tasks - -Async Tasks lists background tasks such as Gremlin and Cypher tasks, algorithm tasks, metadata removal, index creation and rebuild, and Vermeer load or compute tasks, with detail, cancel and delete actions. - -##### System and Operations - -System and Operations covers the personal profile, account management with GraphSpace permission presets, and, in PD mode, the cluster overview and node details. - -#### 1.1 Compatibility +For HStore, read the shared operations here first, then follow the [distributed supplement](/docs/quickstart/toolchain/visualization/hugegraph-hubble-hstore/). +This guide follows Toolchain `master` (currently `1.8.0`); Docker `latest` is mutable, so check the actual running versions. -Hubble detects the authentication mode and the capabilities of the connected Server; there is no separate authentication switch in Hubble. The supported combinations are: - -| HugeGraph Server / PD | Deployment | Hubble compatibility | Scope and limitations | -|---|---|---|---| -| Server 1.5.x | Standalone, normally without authentication | Minimum compatibility | Basic graph, schema, data and Gremlin workflows only. GraphSpace, account permissions, PD/Store topology, cluster operations and newer algorithms are unavailable. | -| Server 1.7.x with matching PD/Store 1.7.x | Standalone or distributed | Minimum compatibility through legacy adapters | Core management and query workflows stay usable, but legacy REST/Gremlin authentication, permission semantics, metrics and algorithm capabilities give a reduced experience. | -| Server, PD and Store 1.8.x or later | Distributed deployment recommended | Full and recommended experience | GraphSpace, account permission presets, cluster operations, async tasks and algorithm capability handling are designed and validated against this generation. | - -Use matching Server, PD and Store minor versions in a distributed cluster. - -### 2 Deploy - -There are three ways to deploy `hugegraph-hubble` - -- Use Docker (Convenient for Test/Dev) -- Download the Toolchain binary package -- Source code compilation - -Hubble runs on Java 11: the backend is compiled with `java.version=11` and the Docker image is based on `eclipse-temurin:11-jre`. `bin/start-hubble.sh` only checks that a `java` binary is on the `PATH`, so make sure the right JDK is selected. - -#### 2.1 Use docker (Convenient for Test/Dev) - -> **Special Note**: Hubble no longer asks for the Server host and port on the web page. The Server address comes from `conf/hugegraph-hubble.properties`: `server.direct_url` when `pd.enabled=false`, or PD discovery through `pd.peers` when `pd.enabled=true`. Inside the container `127.0.0.1` refers to the `hubble` container itself, so the packaged default `server.direct_url=http://127.0.0.1:8080` does not reach a Server running in another container. -> -> If `hubble` and `server` are in the same docker network, we **recommend** using the `container_name` (in our example, it is `server`) as the hostname, and `8080` as the port. Or you can use the **host IP** as the hostname, and the port is configured by the host for the server. - -The image copies the packaged distribution to `/hubble`, rewrites `server.host=0.0.0.0` and clears `dashboard.address` in `/hubble/conf/hugegraph-hubble.properties`, exposes port `8088` and runs `./bin/start-hubble.sh -f` in the foreground. - -Prepare a `hugegraph-hubble.properties` that points at your Server and keeps the container listening on all interfaces: - -```properties -server.host=0.0.0.0 -server.port=8088 -pd.enabled=false -server.direct_url=http://server:8080 -``` - -Then start [hubble](https://hub.docker.com/r/hugegraph/hubble) with that file mounted over the packaged configuration: - -```bash -docker run -itd --name=hubble -p 8088:8088 \ - -v "$PWD/hugegraph-hubble.properties:/hubble/conf/hugegraph-hubble.properties" \ - hugegraph/hubble:1.7.0 -``` - -Alternatively, you can use Docker Compose to start `hubble`. Additionally, if `hubble` and the graph is in the same Docker network, you can access the graph using the container name of the graph, eliminating the need for the host machine's IP address. - -Use `docker-compose up -d`, `docker-compose.yml` is following: - -```yaml -version: '3' -services: - server: - image: hugegraph/hugegraph:1.7.0 - container_name: server - environment: - - PASSWORD=xxx - ports: - - 8080:8080 - - hubble: - image: hugegraph/hubble:1.7.0 - container_name: hubble - ports: - - 8088:8088 - volumes: - - ./hugegraph-hubble.properties:/hubble/conf/hugegraph-hubble.properties -``` - -> Note: -> -> 1. The docker image of hugegraph-hubble is a convenience release to start hugegraph-hubble quickly, but not **official distribution** artifacts. You can find more details from [ASF Release Distribution Policy](https://infra.apache.org/release-distribution.html#dockerhub). -> -> 2. Recommend to use `release tag` (like `1.7.0`) for the stable version. Use `latest` tag to experience the newest functions in development. - -#### 2.2 Download the Toolchain binary package +> [!WARNING] +> Do not expose Hubble or Server directly to the public network. In production, use HTTPS, containers, +> [authentication and authorization](/docs/config/config-authentication/), and an access allowlist. -`hubble` is in the `toolchain` project. First, download the binary tar tarball -```bash -export VERSION=1.7.0 -export ARCHIVE="apache-hugegraph-toolchain-incubating-${VERSION}" -wget "https://downloads.apache.org/hugegraph/${VERSION}/${ARCHIVE}.tar.gz"; -tar -xvf "${ARCHIVE}.tar.gz" -cd "${ARCHIVE}/apache-hugegraph-hubble-incubating-${VERSION}" -``` +## Start the standalone pair -Edit `conf/hugegraph-hubble.properties` so that the Server address is correct, then run `hubble` +Use the main repository's [docker/docker-compose.yml](https://github.com/apache/hugegraph/blob/master/docker/docker-compose.yml) +instead of writing another Compose file. It already combines RocksDB Server and Hubble, with networking, health checks, and data volumes. +See the adjacent [README](https://github.com/apache/hugegraph/blob/master/docker/README.md) for deployment details. ```bash -bin/start-hubble.sh +git clone --branch master --single-branch --depth 1 https://github.com/apache/hugegraph.git +cd hugegraph/docker ``` -`start-hubble.sh` accepts the following options: - -| Option | Description | -|--------|-------------| -| `-f`, `--foreground [true\|false]` | Run in the foreground instead of as a daemon; the Docker image uses `-f` | -| `-d`, `--debug` | Enable the JDWP debugger on port `8787` (`server=y,suspend=n`) | - -The script starts the JVM with `-Xms512m -Dfile.encoding=UTF-8 -Dhubble.home.path=<install dir>`, writes the PID to `bin/pid`, logs to `logs/hugegraph-hubble.log` and waits up to 30 seconds for `http://<server.host>:<server.port>/about` to answer before it returns. - -The packaged default is `server.host=localhost`, so the service only accepts loopback connections until you change it. After startup, open `http://<host>:8088`. +If you already have the main repository, enter its `docker/` directory. Compose mounts +[`conf/hubble/standalone.properties`](https://github.com/apache/hugegraph/blob/master/docker/conf/hubble/standalone.properties) +from that directory. It sets `pd.enabled=false` and `server.direct_url=http://server:8080`; +both services communicate over one Docker network, without a Server address configured per graph. +Do not download only the YAML and start it from another directory: relative configuration files may be missing. -Run `bin/stop-hubble.sh` to stop the service. It sends `SIGTERM` first so that the shutdown hooks pause running load tasks and close the embedded H2 database cleanly, and only escalates to `SIGKILL` if the process is still alive after `STOP_TIMEOUT` seconds (environment variable, default `30`). - -#### 2.3 Source code compilation - -Hubble's build uses `frontend-maven-plugin` in `hugegraph-hubble/hubble-dist/pom.xml` to install Node.js v18.20.8 and Yarn v1.22.21, so neither tool needs to be installed beforehand. JDK 11 and Maven are required. - -Download the toolchain source code. - -```shell -git clone https://github.com/apache/hugegraph-toolchain.git -``` +Hubble defaults to host loopback port `8088`; Server publishes `8080`. For a trial on your machine only, change Server's +`ports` entry to `127.0.0.1:8080:8080` to avoid exposing the anonymous API to other machines. -Compile `hubble`. It depends on the loader and client, so you need to build these dependencies in advance during the compilation process (you can skip this step later). - -```shell -cd hugegraph-toolchain -python -m pip install -r hugegraph-hubble/hubble-dist/assembly/travis/requirements.txt -mvn install -pl hugegraph-client,hugegraph-loader -am -Dmaven.javadoc.skip=true -DskipTests -ntp -cd hugegraph-hubble -mvn -e compile package -Dmaven.javadoc.skip=true -Dmaven.test.skip=true -ntp -cd apache-hugegraph-hubble-* -``` - -Run `hubble` +Choose an unused project name for this trial and keep these variables in the same terminal. +Restore this project name if you use another terminal. ```bash -bin/start-hubble.sh -d +export HUGEGRAPH_VERSION=latest +export HUBBLE_IMAGE=hugegraph/hubble:latest +export HUBBLE_DEMO_PROJECT="hubble-demo-$(date +%Y%m%d-%H%M%S)" +docker compose ls +docker compose -p "$HUBBLE_DEMO_PROJECT" -f docker-compose.yml pull +docker compose -p "$HUBBLE_DEMO_PROJECT" -f docker-compose.yml up -d --wait +docker compose -p "$HUBBLE_DEMO_PROJECT" -f docker-compose.yml ps +curl -fsS http://127.0.0.1:8080/versions ``` -For frontend work, run `yarn dev` inside `hubble-fe`. The backend POM does not configure `spring-boot:run`, so run `org.apache.hugegraph.HugeGraphHubble` from `hubble-be/target/classes` with `-Dhubble.home.path` pointing at a writable directory instead. - -### 3 Platform Workflows - -The home page groups the modules into three journeys: Graph Overview, Graph Import and Graph Query. It also shows whether Hubble runs in PD / cluster mode or in non-PD standalone mode. The module usage process of the platform is as follows: - -<div style="text-align: center;"> - <img src="/docs/images/images-hubble/2平台使用流程.png" alt="image"> -</div> - - -### 4 Platform Instructions -#### 4.1 Graph Management -In PD mode, [Graph Space Management] lists all GraphSpaces of the cluster and can create or edit one, including its alias, optional Kubernetes namespace and compute task, and resource limits. In non-PD standalone mode there is exactly one GraphSpace named `DEFAULT` and the GraphSpace list is skipped. - -##### 4.1.1 Graph creation -Under the graph management module, click [New Graph] and fill in the graph name, an optional alias, an optional schema template and optional sample data. The graph name is unique inside its GraphSpace and cannot be changed after creation. - -<div style="text-align: center;"> - <img src="/docs/images/images-hubble/311图创建.png" alt="image"> -</div> - - -Create graph by filling in the content as follows: - -<center> - <img src="/docs/images/images-hubble/311图创建2.png" alt="image"> -</center> - -> **Special Note**: The Server connection is not configured on this page. It comes from `conf/hugegraph-hubble.properties`, through `server.direct_url` or PD discovery; see section 2.1 for the Docker hostname rules. Graph creation is only offered when the connected Server exposes it (REST API 0.67 or later); on older Servers the graph list is read-only. - -##### 4.1.2 Graph Access -Realize the information access to the graph space. After entering, you can perform operations such as multidimensional query analysis, metadata management, data import, and algorithm analysis of the graph. [Open Graph Studio] opens the query workbench, [Metadata Config] opens the schema pages, and the graph detail page shows vertex and edge statistics together with the schema. - -<center> - <img src="/docs/images/images-hubble/312图访问.png" alt="image"> -</center> - - -##### 4.1.3 Graph management -1. The graph list has a card view and a list view. Search matches the graph name. -2. Per-graph actions are View Schema (with [Export Groovy Schema]), Metadata Config, Clone Graph (schema only, or schema and data), Clear Schema and Data, Delete, and, in PD mode, Set Default. -3. [Sample data and resources] builds a demo graph inside the current graph: the Red Chamber demo graph, the People & Software demo graph, or the Tiny Movie Rank demo. These demos add missing schema and elements only and never clear existing data. - -<center> - <img src="/docs/images/images-hubble/313图管理.png" alt="image"> -</center> - - -#### 4.2 Metadata Modeling (list + graph mode) -##### 4.2.1 Module entry -Open [Metadata Config] from the graph list, or the metadata page of a graph at `/graphspace/<graphspace>/graph/<graph>/meta`. The page has five tabs, Property, Vertex Type, Edge Type, Vertex Index and Edge Index, and a switch between list view and graph view. - -<center> - <img src="/docs/images/images-hubble/321元数据入口.png" alt="image"> -</center> - - -##### 4.2.2 Property type -###### 4.2.2.1 Create type -1. Fill in or select the property name, data type, and cardinality to complete the creation of the property. -2. Created properties can be used as properties of vertex type and edge type. - -List mode: - -<center> - <img src="/docs/images/images-hubble/3221属性创建.png" alt="image"> -</center> - +Once services are healthy, open <http://127.0.0.1:8088>. In a fresh directory without `HUGEGRAPH_ADMIN_PASSWORD`, +Server allows anonymous access and Hubble opens the home page directly. For authentication, follow the Docker README to configure +an administrator password and JWT secret in `.env`, then sign in with a Server account. Hubble has no separate account database. +Personal and account-management pages depend on the authentication mode and your permissions. Do not overwrite an existing `.env`. -Graph mode: +Use `latest` to try current features, and pin a published image version or digest for production. +Images are convenience distributions; official release archives are on the [download page](/docs/download/download/). +The algorithm and account examples use Hubble `1.8.0` with Server `1.7.0`; available controls depend on Server capabilities. Review Comment: 🧹 Minor — This sentence calls the app “Hubble 1.8.0”, but Toolchain's Maven revision is 1.8.0 while Hubble's `/about` response reports 3.0.0; the commands also pull a mutable `latest` tag. Please label this as the Toolchain 1.8.0 build, state the `/about` version, and either pin the example image or clarify that the version pair is illustrative; apply the same wording in Chinese. ########## content/en/docs/quickstart/toolchain/visualization/hugegraph-hubble-hstore.md: ########## @@ -0,0 +1,162 @@ +--- +title: "Manage an HStore Cluster with Hubble" +description: "Connect HStore and PD to Hubble and understand GraphSpaces, Schema templates, cluster topology, and node metrics." +linkTitle: "Hubble with HStore" +weight: 2 +search_keywords: [HugeGraph Hubble, HStore, PD, GraphSpace, cluster management] +--- + +This guide covers the differences between HStore + PD and standalone RocksDB. +For modeling, importing data, and querying, see the [Hubble standalone guide](/docs/quickstart/toolchain/hugegraph-hubble/). +This guide follows Toolchain `master`. + +The main repository's [docker/docker-compose-hstore.yml](https://github.com/apache/hugegraph/blob/master/docker/docker-compose-hstore.yml) +already combines PD, Store, Server, and Hubble. Follow the adjacent +[Docker README](https://github.com/apache/hugegraph/blob/master/docker/README.md) to prepare `.env` and generated Hubble local configuration, +then start it from `docker/`; do not maintain another deployment YAML. +The settings below explain connection differences and do not replace the README's PD credential and service-readiness requirements. + +The illustrated setup uses Hubble `1.8.0` with Server, PD, and Store `1.7.0`; metrics and permission APIs vary by version. + +## Connect to a distributed cluster + +Hubble still manages graph data through the **Server graph API**. In distributed mode, it discovers Servers through PD +and collects cluster information from PD and Store. Hubble does not read or write graph data directly in Store. + +Follow the [PD deployment guide](/docs/quickstart/hugegraph/hugegraph-pd/) and +[HStore deployment guide](/docs/quickstart/hugegraph/hugegraph-hstore/) to start matching versions of PD, Store, and Server. +Confirm that Server is registered and Store is ready, then edit Hubble's `conf/hugegraph-hubble.properties`. Review Comment: ⚠️ Important — In the recommended Docker Compose setup, this path is the container mount target and is read-only. Please direct readers to edit the generated host file at `docker/conf/hubble/hstore.local.properties` via `set-hubble-pd-password.sh`, preserve the generated PD credential, and align the Chinese guide; editing the mounted file inside the container cannot work. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
