feat(docker): add attachable Hubble Compose add-on for the 3-node cluster

README.md

@@ -201,7 +201,7 @@ For advanced Docker configurations, see:
 * [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.
+> **Docker Desktop (Mac/Windows)**: The 3-node distributed cluster (`docker/docker-compose-3pd-3store-3server.yml`) joins a pre-created external Docker network shared with the Hubble add-on (see the [Docker README](./docker/README.md) quickstart) 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.
 >

docker/docker-compose-3pd-3store-3server.yml

@@ -17,9 +17,14 @@
 
 name: hugegraph-3x3
 
+# The cluster network is shared with the Hubble add-on
+# (docker-compose-hubble.yml), so it is external and must exist first:
+#   docker network create hugegraph-net
+# Set HUGEGRAPH_NETWORK to use a differently named network.
 networks:
   hg-net:
-    driver: bridge
+    external: true
+    name: ${HUGEGRAPH_NETWORK:-hugegraph-net}
 
 volumes:
   hg-pd0-data:
@@ -31,8 +36,10 @@ volumes:
 
 # ── Shared service defaults ──────────────────────────────────────────
 x-pd-common: &pd-common
+  # Pin a release via HUGEGRAPH_VERSION in docker/.env; unset, the image
+  # tags default to latest. All Compose files here read the same variable.
   image: hugegraph/pd:${HUGEGRAPH_VERSION:-latest}
-  pull_policy: missing
+  pull_policy: ${HUGEGRAPH_PULL_POLICY:-always}
   restart: unless-stopped
   networks: [hg-net]
   healthcheck:
@@ -44,7 +51,7 @@ x-pd-common: &pd-common
 
 x-store-common: &store-common
   image: hugegraph/store:${HUGEGRAPH_VERSION:-latest}
-  pull_policy: missing
+  pull_policy: ${HUGEGRAPH_PULL_POLICY:-always}
   restart: unless-stopped
   networks: [hg-net]
   depends_on:
@@ -58,21 +65,41 @@ x-store-common: &store-common
     retries: 40
     start_period: 120s
 
+# Shared Server environment; each server node adds its own
+# HG_SERVER_REST_URL on top of this map.
+x-server-env: &server-env
+  STORE_REST: store0:8520
+  HG_SERVER_BACKEND: hstore
+  HG_SERVER_PD_PEERS: pd0:8686,pd1:8686,pd2:8686
+  # Register every Server replica with PD under one application name so
+  # PD-aware clients such as Hubble discover the cluster as one logical
+  # Server; `hg` matches the Hubble configuration.
+  HG_SERVER_CLUSTER: hg
+  HG_SERVER_USE_PD: "true"
+  HG_SERVER_MIN_FREE_MEMORY: "0"
+  HG_SERVER_INIT_STORE_ENABLED: "false"
+  # All replicas must share one token secret so a token issued by any
+  # server validates on every other server.
+  HG_SERVER_AUTH_TOKEN_SECRET: ${HUGEGRAPH_AUTH_TOKEN_SECRET:?Set a shared auth token secret}
+  PASSWORD: ${HUGEGRAPH_ADMIN_PASSWORD:?Set a non-default admin password}
+
 x-server-common: &server-common
   image: hugegraph/server:${HUGEGRAPH_VERSION:-latest}
-  pull_policy: missing
+  pull_policy: ${HUGEGRAPH_PULL_POLICY:-always}
   restart: unless-stopped
   networks: [hg-net]
   depends_on:
     store0: { condition: service_healthy }
     store1: { condition: service_healthy }
     store2: { condition: service_healthy }
-  environment:
-    STORE_REST: store0:8520
-    HG_SERVER_BACKEND: hstore
-    HG_SERVER_PD_PEERS: pd0:8686,pd1:8686,pd2:8686
   healthcheck:
-    test: ["CMD-SHELL", "curl -fsS http://localhost:8080/versions >/dev/null || exit 1"]
+    # Prove the image actually enforces authentication. /versions is open by
+    # design, so an image that ignores PASSWORD still answers it and looks
+    # healthy while the graph APIs are wide open. Requiring 401 on a graph
+    # request catches exactly that, and it stays correct after an operator
+    # rotates the admin password through the API, which an authenticated
+    # probe pinned to the seeded PASSWORD would not.
+    test: ["CMD-SHELL", "test \"$$(curl -s -o /dev/null -w '%{http_code}' \"$${HG_SERVER_REST_URL}/graphs/hugegraph/schema/vertexlabels\")\" = 401"]
     interval: 10s
     timeout: 5s
     retries: 30
@@ -86,7 +113,6 @@ services:
     <<: *pd-common
     container_name: hg-pd0
     hostname: pd0
-    networks: [ hg-net ]
     environment:
       HG_PD_GRPC_HOST: pd0
       HG_PD_GRPC_PORT: "8686"
@@ -96,15 +122,16 @@ services:
       HG_PD_INITIAL_STORE_LIST: store0:8500,store1:8500,store2:8500
       HG_PD_DATA_PATH: /hugegraph-pd/pd_data
       HG_PD_INITIAL_STORE_COUNT: 3
-    ports: ["8620:8620", "8686:8686"]
+    ports:
+      - "${HUGEGRAPH_CONTROL_PLANE_HOST:-127.0.0.1}:8620:8620"
+      - "${HUGEGRAPH_CONTROL_PLANE_HOST:-127.0.0.1}:8686:8686"
     volumes:
       - hg-pd0-data:/hugegraph-pd/pd_data
 
   pd1:
     <<: *pd-common
     container_name: hg-pd1
     hostname: pd1
-    networks: [ hg-net ]
     environment:
       HG_PD_GRPC_HOST: pd1
       HG_PD_GRPC_PORT: "8686"
@@ -114,15 +141,16 @@ services:
       HG_PD_INITIAL_STORE_LIST: store0:8500,store1:8500,store2:8500
       HG_PD_DATA_PATH: /hugegraph-pd/pd_data
       HG_PD_INITIAL_STORE_COUNT: 3
-    ports: ["8621:8620", "8687:8686"]
+    ports:
+      - "${HUGEGRAPH_CONTROL_PLANE_HOST:-127.0.0.1}:8621:8620"
+      - "${HUGEGRAPH_CONTROL_PLANE_HOST:-127.0.0.1}:8687:8686"
     volumes:
       - hg-pd1-data:/hugegraph-pd/pd_data
 
   pd2:
     <<: *pd-common
     container_name: hg-pd2
     hostname: pd2
-    networks: [ hg-net ]
     environment:
       HG_PD_GRPC_HOST: pd2
       HG_PD_GRPC_PORT: "8686"
@@ -132,7 +160,9 @@ services:
       HG_PD_INITIAL_STORE_LIST: store0:8500,store1:8500,store2:8500
       HG_PD_DATA_PATH: /hugegraph-pd/pd_data
       HG_PD_INITIAL_STORE_COUNT: 3
-    ports: ["8622:8620", "8688:8686"]
+    ports:
+      - "${HUGEGRAPH_CONTROL_PLANE_HOST:-127.0.0.1}:8622:8620"
+      - "${HUGEGRAPH_CONTROL_PLANE_HOST:-127.0.0.1}:8688:8686"
     volumes:
       - hg-pd2-data:/hugegraph-pd/pd_data
 
@@ -148,7 +178,10 @@ services:
       HG_STORE_REST_PORT: "8520"
       HG_STORE_RAFT_ADDRESS: store0:8510
       HG_STORE_DATA_PATH: /hugegraph-store/storage
-    ports: ["8500:8500", "8510:8510", "8520:8520"]
+    ports:
+      - "${HUGEGRAPH_CONTROL_PLANE_HOST:-127.0.0.1}:8500:8500"
+      - "${HUGEGRAPH_CONTROL_PLANE_HOST:-127.0.0.1}:8510:8510"
+      - "${HUGEGRAPH_CONTROL_PLANE_HOST:-127.0.0.1}:8520:8520"
     volumes:
       - hg-store0-data:/hugegraph-store/storage
 
@@ -163,7 +196,10 @@ services:
       HG_STORE_REST_PORT: "8520"
       HG_STORE_RAFT_ADDRESS: store1:8510
       HG_STORE_DATA_PATH: /hugegraph-store/storage
-    ports: ["8501:8500", "8511:8510", "8521:8520"]
+    ports:
+      - "${HUGEGRAPH_CONTROL_PLANE_HOST:-127.0.0.1}:8501:8500"
+      - "${HUGEGRAPH_CONTROL_PLANE_HOST:-127.0.0.1}:8511:8510"
+      - "${HUGEGRAPH_CONTROL_PLANE_HOST:-127.0.0.1}:8521:8520"
     volumes:
       - hg-store1-data:/hugegraph-store/storage
 
@@ -178,7 +214,10 @@ services:
       HG_STORE_REST_PORT: "8520"
       HG_STORE_RAFT_ADDRESS: store2:8510
       HG_STORE_DATA_PATH: /hugegraph-store/storage
-    ports: ["8502:8500", "8512:8510", "8522:8520"]
+    ports:
+      - "${HUGEGRAPH_CONTROL_PLANE_HOST:-127.0.0.1}:8502:8500"
+      - "${HUGEGRAPH_CONTROL_PLANE_HOST:-127.0.0.1}:8512:8510"
+      - "${HUGEGRAPH_CONTROL_PLANE_HOST:-127.0.0.1}:8522:8520"
     volumes:
       - hg-store2-data:/hugegraph-store/storage
 
@@ -187,16 +226,28 @@ services:
     <<: *server-common
     container_name: hg-server0
     hostname: server0
-    ports: ["8080:8080"]
+    environment:
+      <<: *server-env
+      HG_SERVER_REST_URL: http://server0:8080
+    ports:
+      - "${HUGEGRAPH_SERVER_PUBLISH_HOST:-127.0.0.1}:8080:8080"
 
   server1:
     <<: *server-common
     container_name: hg-server1
     hostname: server1
-    ports: ["8081:8080"]
+    environment:
+      <<: *server-env
+      HG_SERVER_REST_URL: http://server1:8080
+    ports:
+      - "${HUGEGRAPH_SERVER_PUBLISH_HOST:-127.0.0.1}:8081:8080"
 
   server2:
     <<: *server-common
     container_name: hg-server2
     hostname: server2
-    ports: ["8082:8080"]
+    environment:
+      <<: *server-env
+      HG_SERVER_REST_URL: http://server2:8080
+    ports:
+      - "${HUGEGRAPH_SERVER_PUBLISH_HOST:-127.0.0.1}:8082:8080"

docker/docker-compose-3x3.non-auth.yml

@@ -0,0 +1,70 @@
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Opt-in override that runs the 3-node cluster WITHOUT authentication.
+#
+# The default stack authenticates, and that is the configuration to use unless
+# you have a reason not to. This override exists for throwaway local trials on
+# a trusted network: no admin password, no JWT secret, no login in Hubble.
+# Anyone who can reach the published ports can read and modify every graph.
+#
+# Usage (see "Running without authentication" in README.md):
+#
+#   HUGEGRAPH_ADMIN_PASSWORD=non-auth-placeholder \
+#   HUGEGRAPH_AUTH_TOKEN_SECRET=non-auth-placeholder \
+#     docker compose -f docker-compose-3pd-3store-3server.yml \
+#                    -f docker-compose-3x3.non-auth.yml up -d
+#
+# The two placeholders are required only because Compose interpolates the base
+# file's `:?` guards before it applies this override; `!reset` below drops both
+# variables, so neither value ever reaches a container. `!reset` needs Docker
+# Compose v2.24 or newer.
+#
+# Pass them inline on this command only. Do not put them in docker/.env. They
+# are published values, so they are not credentials, and the token placeholder
+# is deliberately shorter than the 32 bytes the Server entrypoint requires: if
+# it ever reaches an authenticated Server it aborts startup instead of signing
+# tokens with a key that is printed in this repository.
+
+# Each service is spelled out instead of sharing a YAML anchor. `!reset` does
+# not survive an anchor/alias reference on every Compose version: on 5.1.2 the
+# reset applies only to the anchored service, leaving server1 and server2 with
+# a password and token secret, so the cluster would be half authenticated. The
+# plain healthcheck override in the same block does propagate, which makes the
+# failure easy to miss. Keep these three blocks identical.
+services:
+  server0:
+    environment:
+      PASSWORD: !reset null
+      HG_SERVER_AUTH_TOKEN_SECRET: !reset null
+    healthcheck:
+      # The default healthcheck proves the image enforces authentication
+      # (401 without credentials, 200 with). That check cannot pass here, so
+      # fall back to probing the bound REST address.
+      test: ["CMD-SHELL", "curl -fsS $${HG_SERVER_REST_URL}/versions >/dev/null || exit 1"]
+
+  server1:
+    environment:
+      PASSWORD: !reset null
+      HG_SERVER_AUTH_TOKEN_SECRET: !reset null
+    healthcheck:
+      test: ["CMD-SHELL", "curl -fsS $${HG_SERVER_REST_URL}/versions >/dev/null || exit 1"]
+
+  server2:
+    environment:
+      PASSWORD: !reset null
+      HG_SERVER_AUTH_TOKEN_SECRET: !reset null
+    healthcheck:
+      test: ["CMD-SHELL", "curl -fsS $${HG_SERVER_REST_URL}/versions >/dev/null || exit 1"]

docker/docker-compose-hubble.yml

@@ -0,0 +1,70 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+# Hubble add-on for the distributed cluster defined in
+# docker-compose-3pd-3store-3server.yml. Requires the pre-created cluster
+# network (docker network create hugegraph-net). See "Hubble for the
+# 3-Node Cluster" in docker/README.md for the attach and combined flows.
+
+networks:
+  hg-net:
+    external: true
+    name: ${HUGEGRAPH_NETWORK:-hugegraph-net}
+
+volumes:
+  # Pre-created and external, like the shared network above. A fixed name
+  # alone is not enough: Compose deletes a fixed-name non-external volume on
+  # `down -v` from ANY project that declares the name, so tearing down the
+  # attach flow would silently destroy the combined flow's Hubble database.
+  # `external` makes both flows share the state and survive either teardown.
+  hg-hubble-db:
+    name: ${HUBBLE_DB_VOLUME:-hugegraph-hubble-db}
+    external: true
+  hg-hubble-upload-files:
+    name: ${HUBBLE_UPLOAD_VOLUME:-hugegraph-hubble-upload-files}
+    external: true
+
+services:
+  hubble:
+    # Pin a release via HUGEGRAPH_VERSION in docker/.env; unset, the image
+    # tag defaults to latest. Pull by default so an older cached image cannot
+    # silently satisfy an auth-sensitive deployment.
+    image: ${HUBBLE_IMAGE:-hugegraph/hubble:${HUGEGRAPH_VERSION:-latest}}
+    pull_policy: ${HUBBLE_PULL_POLICY:-always}
+    container_name: hg-hubble
+    hostname: hubble
+    restart: unless-stopped
+    networks: [hg-net]
+    ports:
+      - "${HUBBLE_PUBLISH_HOST:-127.0.0.1}:8088:8088"
+    environment:
+      # Image default jdbc:h2:file:./db writes /hubble/db.mv.db, outside
+      # the /hubble/db volume. Use an absolute path so the database stays in
+      # the mount even if a future image changes its working directory.
+      SPRING_DATASOURCE_URL: jdbc:h2:file:/hubble/db/hubble;DB_CLOSE_ON_EXIT=FALSE
+    volumes:
+      # Point HUBBLE_PROPERTIES at the non-auth variant when the cluster runs
+      # without authentication; see "Running without authentication".
+      - ${HUBBLE_PROPERTIES:-./hugegraph-hubble-3x3.properties}:/hubble/conf/hugegraph-hubble.properties:ro
+      - hg-hubble-db:/hubble/db
+      - hg-hubble-upload-files:/hubble/upload-files
+    healthcheck:
+      test: ["CMD-SHELL", "body=$$(curl -fsS http://127.0.0.1:8088/about) && printf '%s' \"$$body\" | grep -q '\"status\":200' && printf '%s' \"$$body\" | grep -q '\"name\":\"hugegraph-hubble\"'"]
+      interval: 10s
+      timeout: 5s
+      retries: 30
+      start_period: 60s