imbajin commented on code in PR #3149:
URL: https://github.com/apache/hugegraph/pull/3149#discussion_r3892317694
##########
docker/README.md:
##########
@@ -1,436 +1,362 @@
-# HugeGraph Docker Deployment
+# HugeGraph Docker Compose
-This directory contains Docker Compose files for running HugeGraph:
+## Users
-| File | Description |
-|------|-------------|
-| `docker-compose.yml` | PD, Store, Server, and Hubble using pre-built images |
-| `docker-compose.dev.yml` | PD, Store, and Server built from source, plus
Hubble |
-| `docker-compose-3pd-3store-3server.yml` | 3-node distributed cluster (PD +
Store + Server) |
+### Choose a topology
-## Prerequisites
+Run commands in this directory:
-- **Docker Engine** 20.10+ (or Docker Desktop 4.x+)
-- **Docker Compose** v2 (included in Docker Desktop)
-- **OpenSSL CLI** (used to generate the initial administrator password)
-- **Memory**: Allocate at least **12 GB** to Docker Desktop (Settings →
Resources → Memory). The 3-node cluster runs 9 JVM processes (3 PD + 3 Store +
3 Server) which are memory-intensive. Insufficient memory causes OOM kills that
appear as silent Raft failures.
+```bash
+cd docker
+```
-> [!IMPORTANT]
-> The 12 GB minimum is for Docker Desktop. On Linux with native Docker, ensure
the host has at least 12 GB of free memory.
----
+| Topology | Compose file | Services | When to use it |
+| --- | --- | --- | --- |
+| Standalone | `docker-compose.yml` | 1 RocksDB Server + 1 Hubble | Default;
start here |
+| Minimal HStore | `docker-compose-hstore.yml` | 1 PD + 1 Store + 1 Server + 1
Hubble | Distributed local development |
+| HA | `docker-compose-3pd-3store-3server.yml` | 3 PD + 3 Store + 3 Server + 1
Hubble | Reference and evaluation |
-## Single-Node Setup
+Standalone uses `hugegraph/hugegraph:${HUGEGRAPH_VERSION:-latest}`. The HStore
+topologies use the matching `hugegraph/pd`, `hugegraph/store`, and
+`hugegraph/server` tags. Hubble is selected independently with
+`${HUBBLE_IMAGE:-hugegraph/hubble:latest}`.
-Two compose files run one PD, one Store, one Server, and one Hubble instance:
+### Create the authentication environment
-Create a Compose environment file once so every lifecycle command can resolve
the required administrator password:
+Create `.env` once. Replace `replace-with-your-password` with an administrator
+password that you choose; the command generates and persists a random 32-byte
+JWT secret. For this simple single-quoted format, do not use a password that
+contains a single quote or newline.
```bash
(
set -eu
- cd docker
- if [ -e .env ]; then
- echo "docker/.env already exists; reusing it"
- else
- command -v openssl >/dev/null 2>&1
- admin_password="$(openssl rand -base64 12)"
- if [ "${#admin_password}" -ne 16 ]; then
- echo "Failed to generate a 16-character password" >&2
- exit 1
- fi
- install -m 600 /dev/null .env
- {
- printf "HUGEGRAPH_ADMIN_PASSWORD='%s'\n" "${admin_password}"
- } >> .env
- unset admin_password
- fi
- chmod 600 .env
- if ! env -u HUGEGRAPH_ADMIN_PASSWORD \
- docker compose -f docker-compose.yml config --quiet ||
- ! env -u HUGEGRAPH_ADMIN_PASSWORD \
- docker compose -f docker-compose.dev.yml config --quiet; then
- echo "docker/.env is incomplete; repair or move it, then retry" >&2
+ command -v openssl >/dev/null
+ jwt_secret="$(openssl rand -hex 32)"
+ test "${#jwt_secret}" -eq 64
+ umask 077
+ test ! -e .env || {
+ echo ".env already exists; edit it instead of overwriting it" >&2
exit 1
- fi
+ }
+ printf "HUGEGRAPH_ADMIN_PASSWORD='%s'\nHUGEGRAPH_AUTH_TOKEN_SECRET='%s'\n" \
+ 'replace-with-your-password' "${jwt_secret}" > .env
)
```
-Compose automatically reads `docker/.env` for `up`, `ps`, `stop`, and `down`.
The generated password is a 16-character, Compose-safe random value. The file
is excluded from Git and Docker build contexts; keep its permissions restricted
and source production credentials from your secret manager instead of
committing them.
+Do not commit `.env`. Keeping the same JWT secret preserves authentication
+tokens when containers are recreated. For authenticated topologies with
+multiple Server replicas, all replicas receive this same secret. The HA
+topology fails fast if authentication is enabled without this shared secret.
-### Option A: Quick Start (pre-built images)
+A non-empty `HUGEGRAPH_ADMIN_PASSWORD` enables Server authentication, and
+Hubble detects that mode automatically. Omitting the variable or setting it to
+an empty value disables authentication. Auth-off is only suitable for a
+trusted local environment; never expose it to a public or untrusted network.
+Hubble listens on host loopback by default. Set `HUBBLE_PUBLISH_HOST` only
+behind an HTTPS reverse proxy and trusted network controls.
-Uses pre-built images from Docker Hub. Best for **end users** who want to run
HugeGraph quickly. Set `HUGEGRAPH_VERSION` to the same published release for
PD, Store, Server, and Hubble. The authenticated PD/Hubble integration is not
present in `1.7.x`; if no later compatible release is available, use Option B.
+`HUGEGRAPH_ADMIN_PASSWORD` initializes the built-in `admin` account on its
+first authenticated startup. Changing `.env` does not rotate an existing
+administrator password; use the HugeGraph user API for credential changes.
+
+For the verification commands below, set the password in your current shell:
```bash
-(
- cd docker
- HUGEGRAPH_VERSION='<compatible-release-after-1.7.x>' \
- docker compose up -d
-)
+ADMIN_PASSWORD='the-same-password-used-in-.env'
```
-- Images: matching `hugegraph/pd`, `hugegraph/store`, `hugegraph/server`, and
`hugegraph/hubble` tags from the selected compatible release
-- `pull_policy: always` — always pulls the specified image tag
-
-> **Note**: Do not use `latest` to claim a reproducible deployment. Pin a
compatible release tag and keep it unchanged for later lifecycle commands.
-- PD healthcheck endpoint: `/v1/health`
-- Hubble is available at `http://localhost:8088`; sign in as `admin` with the
required `HUGEGRAPH_ADMIN_PASSWORD`
-- Hubble binds to host loopback by default. Set `HUBBLE_PUBLISH_HOST`
explicitly only behind an HTTPS reverse proxy and trusted network controls.
-- Hubble uses PD discovery and the Docker-network Server address
-- Server healthcheck endpoint: `/versions`
+### Standalone
-### Option B: Development Build (build from source)
+This is the recommended quickstart.
-Builds images locally from source Dockerfiles. Best for **developers** who
want to test local changes. Build the matching `hugegraph-toolchain` Hubble
source as `local/hugegraph-hubble:dev` before starting this stack.
+Start:
-The publishing pipeline uses [`docker/bake.hcl`](./bake.hcl) from the
repository root to compile the Java reactor once and build the PD, Store,
HStore Server, and standalone Server runtime images from that shared result.
+```bash
+docker compose -f docker-compose.yml up -d --wait
+```
-Run Bake commands from the repository root. Use `--print` to inspect the
resolved targets without building, or run the default group to build all four
amd64/arm64 images. Loading both platforms under the same local tags requires
Docker's containerd image store.
+Status:
```bash
-# Inspect the resolved build graph
-docker buildx bake --file docker/bake.hcl --print
+docker compose -f docker-compose.yml ps
+```
+
+Verify Server readiness, authentication, and Hubble:
-# Build the default multi-platform target group
-IMAGE_TAG=local docker buildx bake --file docker/bake.hcl
+```bash
+curl -fsS http://localhost:8080/versions
+test "$(curl -sS -o /dev/null -w '%{http_code}' \
+ http://localhost:8080/graphspaces/DEFAULT/graphs)" = 401
+test "$(curl -sS -u "admin:${ADMIN_PASSWORD}" -o /dev/null -w '%{http_code}' \
+ http://localhost:8080/graphspaces/DEFAULT/graphs)" = 200
+curl -fsS http://localhost:8088/about
```
-Local source changes are included because Bake uses the current repository
working tree as its build context. For routine development, override all
targets to the host architecture so the four images still share one Maven build
without requiring the multi-platform containerd image store.
+Open `http://localhost:8088` and sign in as `admin` with the password from
+`.env`.
+
+Stop containers while keeping them:
```bash
-# x86_64 host
-IMAGE_TAG=local docker buildx bake --file docker/bake.hcl --set
'*.platform=linux/amd64'
+docker compose -f docker-compose.yml stop
+```
-# ARM64 host
-IMAGE_TAG=local docker buildx bake --file docker/bake.hcl --set
'*.platform=linux/arm64'
+Remove containers and the network while keeping data:
+
+```bash
+docker compose -f docker-compose.yml down
```
-These local commands can read existing Registry caches but do not publish
images or write remote caches because `EXPORT_CACHE` defaults to `false`.
+Delete containers, the network, and all topology data:
```bash
-(
- cd docker
- HUBBLE_IMAGE=local/hugegraph-hubble:dev \
- HUBBLE_PULL_POLICY=never \
- docker compose -f docker-compose.dev.yml up -d
-)
+docker compose -f docker-compose.yml down -v
```
Review Comment:
The repetition is intentional user-facing completeness: each topology
section remains directly copyable for start, status, verification, stop, down,
and destructive cleanup. Consolidating it would save documentation lines but
require placeholders or cross-section substitution, so it is not a functional
fix and is outside this minimal pass.
##########
docker/README.md:
##########
@@ -1,436 +1,362 @@
-# HugeGraph Docker Deployment
+# HugeGraph Docker Compose
-This directory contains Docker Compose files for running HugeGraph:
+## Users
-| File | Description |
-|------|-------------|
-| `docker-compose.yml` | PD, Store, Server, and Hubble using pre-built images |
-| `docker-compose.dev.yml` | PD, Store, and Server built from source, plus
Hubble |
-| `docker-compose-3pd-3store-3server.yml` | 3-node distributed cluster (PD +
Store + Server) |
+### Choose a topology
-## Prerequisites
+Run commands in this directory:
-- **Docker Engine** 20.10+ (or Docker Desktop 4.x+)
-- **Docker Compose** v2 (included in Docker Desktop)
-- **OpenSSL CLI** (used to generate the initial administrator password)
-- **Memory**: Allocate at least **12 GB** to Docker Desktop (Settings →
Resources → Memory). The 3-node cluster runs 9 JVM processes (3 PD + 3 Store +
3 Server) which are memory-intensive. Insufficient memory causes OOM kills that
appear as silent Raft failures.
+```bash
+cd docker
+```
-> [!IMPORTANT]
-> The 12 GB minimum is for Docker Desktop. On Linux with native Docker, ensure
the host has at least 12 GB of free memory.
----
+| Topology | Compose file | Services | When to use it |
+| --- | --- | --- | --- |
+| Standalone | `docker-compose.yml` | 1 RocksDB Server + 1 Hubble | Default;
start here |
+| Minimal HStore | `docker-compose-hstore.yml` | 1 PD + 1 Store + 1 Server + 1
Hubble | Distributed local development |
+| HA | `docker-compose-3pd-3store-3server.yml` | 3 PD + 3 Store + 3 Server + 1
Hubble | Reference and evaluation |
-## Single-Node Setup
+Standalone uses `hugegraph/hugegraph:${HUGEGRAPH_VERSION:-latest}`. The HStore
+topologies use the matching `hugegraph/pd`, `hugegraph/store`, and
+`hugegraph/server` tags. Hubble is selected independently with
+`${HUBBLE_IMAGE:-hugegraph/hubble:latest}`.
-Two compose files run one PD, one Store, one Server, and one Hubble instance:
+### Create the authentication environment
-Create a Compose environment file once so every lifecycle command can resolve
the required administrator password:
+Create `.env` once. Replace `replace-with-your-password` with an administrator
+password that you choose; the command generates and persists a random 32-byte
+JWT secret. For this simple single-quoted format, do not use a password that
+contains a single quote or newline.
```bash
(
set -eu
- cd docker
- if [ -e .env ]; then
- echo "docker/.env already exists; reusing it"
- else
- command -v openssl >/dev/null 2>&1
- admin_password="$(openssl rand -base64 12)"
- if [ "${#admin_password}" -ne 16 ]; then
- echo "Failed to generate a 16-character password" >&2
- exit 1
- fi
- install -m 600 /dev/null .env
- {
- printf "HUGEGRAPH_ADMIN_PASSWORD='%s'\n" "${admin_password}"
- } >> .env
- unset admin_password
- fi
- chmod 600 .env
- if ! env -u HUGEGRAPH_ADMIN_PASSWORD \
- docker compose -f docker-compose.yml config --quiet ||
- ! env -u HUGEGRAPH_ADMIN_PASSWORD \
- docker compose -f docker-compose.dev.yml config --quiet; then
- echo "docker/.env is incomplete; repair or move it, then retry" >&2
+ command -v openssl >/dev/null
+ jwt_secret="$(openssl rand -hex 32)"
+ test "${#jwt_secret}" -eq 64
+ umask 077
+ test ! -e .env || {
+ echo ".env already exists; edit it instead of overwriting it" >&2
exit 1
- fi
+ }
+ printf "HUGEGRAPH_ADMIN_PASSWORD='%s'\nHUGEGRAPH_AUTH_TOKEN_SECRET='%s'\n" \
+ 'replace-with-your-password' "${jwt_secret}" > .env
)
```
-Compose automatically reads `docker/.env` for `up`, `ps`, `stop`, and `down`.
The generated password is a 16-character, Compose-safe random value. The file
is excluded from Git and Docker build contexts; keep its permissions restricted
and source production credentials from your secret manager instead of
committing them.
+Do not commit `.env`. Keeping the same JWT secret preserves authentication
+tokens when containers are recreated. For authenticated topologies with
+multiple Server replicas, all replicas receive this same secret. The HA
+topology fails fast if authentication is enabled without this shared secret.
-### Option A: Quick Start (pre-built images)
+A non-empty `HUGEGRAPH_ADMIN_PASSWORD` enables Server authentication, and
+Hubble detects that mode automatically. Omitting the variable or setting it to
+an empty value disables authentication. Auth-off is only suitable for a
+trusted local environment; never expose it to a public or untrusted network.
+Hubble listens on host loopback by default. Set `HUBBLE_PUBLISH_HOST` only
+behind an HTTPS reverse proxy and trusted network controls.
-Uses pre-built images from Docker Hub. Best for **end users** who want to run
HugeGraph quickly. Set `HUGEGRAPH_VERSION` to the same published release for
PD, Store, Server, and Hubble. The authenticated PD/Hubble integration is not
present in `1.7.x`; if no later compatible release is available, use Option B.
+`HUGEGRAPH_ADMIN_PASSWORD` initializes the built-in `admin` account on its
+first authenticated startup. Changing `.env` does not rotate an existing
+administrator password; use the HugeGraph user API for credential changes.
+
+For the verification commands below, set the password in your current shell:
```bash
-(
- cd docker
- HUGEGRAPH_VERSION='<compatible-release-after-1.7.x>' \
- docker compose up -d
-)
+ADMIN_PASSWORD='the-same-password-used-in-.env'
```
-- Images: matching `hugegraph/pd`, `hugegraph/store`, `hugegraph/server`, and
`hugegraph/hubble` tags from the selected compatible release
-- `pull_policy: always` — always pulls the specified image tag
-
-> **Note**: Do not use `latest` to claim a reproducible deployment. Pin a
compatible release tag and keep it unchanged for later lifecycle commands.
-- PD healthcheck endpoint: `/v1/health`
-- Hubble is available at `http://localhost:8088`; sign in as `admin` with the
required `HUGEGRAPH_ADMIN_PASSWORD`
-- Hubble binds to host loopback by default. Set `HUBBLE_PUBLISH_HOST`
explicitly only behind an HTTPS reverse proxy and trusted network controls.
-- Hubble uses PD discovery and the Docker-network Server address
-- Server healthcheck endpoint: `/versions`
+### Standalone
-### Option B: Development Build (build from source)
+This is the recommended quickstart.
-Builds images locally from source Dockerfiles. Best for **developers** who
want to test local changes. Build the matching `hugegraph-toolchain` Hubble
source as `local/hugegraph-hubble:dev` before starting this stack.
+Start:
-The publishing pipeline uses [`docker/bake.hcl`](./bake.hcl) from the
repository root to compile the Java reactor once and build the PD, Store,
HStore Server, and standalone Server runtime images from that shared result.
+```bash
+docker compose -f docker-compose.yml up -d --wait
+```
-Run Bake commands from the repository root. Use `--print` to inspect the
resolved targets without building, or run the default group to build all four
amd64/arm64 images. Loading both platforms under the same local tags requires
Docker's containerd image store.
+Status:
```bash
-# Inspect the resolved build graph
-docker buildx bake --file docker/bake.hcl --print
+docker compose -f docker-compose.yml ps
+```
+
+Verify Server readiness, authentication, and Hubble:
-# Build the default multi-platform target group
-IMAGE_TAG=local docker buildx bake --file docker/bake.hcl
+```bash
+curl -fsS http://localhost:8080/versions
+test "$(curl -sS -o /dev/null -w '%{http_code}' \
+ http://localhost:8080/graphspaces/DEFAULT/graphs)" = 401
+test "$(curl -sS -u "admin:${ADMIN_PASSWORD}" -o /dev/null -w '%{http_code}' \
+ http://localhost:8080/graphspaces/DEFAULT/graphs)" = 200
+curl -fsS http://localhost:8088/about
```
-Local source changes are included because Bake uses the current repository
working tree as its build context. For routine development, override all
targets to the host architecture so the four images still share one Maven build
without requiring the multi-platform containerd image store.
+Open `http://localhost:8088` and sign in as `admin` with the password from
+`.env`.
+
+Stop containers while keeping them:
```bash
-# x86_64 host
-IMAGE_TAG=local docker buildx bake --file docker/bake.hcl --set
'*.platform=linux/amd64'
+docker compose -f docker-compose.yml stop
+```
-# ARM64 host
-IMAGE_TAG=local docker buildx bake --file docker/bake.hcl --set
'*.platform=linux/arm64'
+Remove containers and the network while keeping data:
+
+```bash
+docker compose -f docker-compose.yml down
```
-These local commands can read existing Registry caches but do not publish
images or write remote caches because `EXPORT_CACHE` defaults to `false`.
+Delete containers, the network, and all topology data:
```bash
-(
- cd docker
- HUBBLE_IMAGE=local/hugegraph-hubble:dev \
- HUBBLE_PULL_POLICY=never \
- docker compose -f docker-compose.dev.yml up -d
-)
+docker compose -f docker-compose.yml down -v
```
-- PD, Store, and Server images are built from this repository
-- Hubble uses `HUBBLE_IMAGE` because its source is in `hugegraph-toolchain`
-- Server entrypoint scripts are baked into the built image; Hubble mounts the
Docker-local PD configuration
-- PD healthcheck endpoint: `/v1/health`
-- Otherwise identical env vars and structure to the quickstart file
+### Minimal HStore
-Use the same release tag for Option A lifecycle commands:
+Start:
```bash
-(
- cd docker
- export HUGEGRAPH_VERSION='<same-compatible-release>'
- docker compose ps
- docker compose stop
- docker compose down
-)
+docker compose -f docker-compose-hstore.yml up -d --wait
```
-Use the development Compose file for every Option B lifecycle command:
+Status:
```bash
-(
- cd docker
- docker compose -f docker-compose.dev.yml ps
- docker compose -f docker-compose.dev.yml stop
- docker compose -f docker-compose.dev.yml down
-)
+docker compose -f docker-compose-hstore.yml ps
```
-### Key Differences
-
-| | `docker-compose.yml` (quickstart) | `docker-compose.dev.yml` (dev build) |
-|---|---|---|
-| **Images** | Pull from Docker Hub | Build from source |
-| **Who it's for** | End users | Developers |
-| **Server pull_policy** | `always` | `build` |
-| **Hubble pull_policy** | `always` | `never` in the workflow above (`missing`
in the Compose file by default) |
+Verify PD, Store, Server authentication, and Hubble:
-**Verify** (both options):
```bash
-curl http://localhost:8080/versions
+curl -fsS http://localhost:8620/v1/health
+curl -fsS http://localhost:8520/v1/health
+curl -fsS http://localhost:8080/versions
+test "$(curl -sS -o /dev/null -w '%{http_code}' \
+ http://localhost:8080/graphspaces/DEFAULT/graphs)" = 401
+test "$(curl -sS -u "admin:${ADMIN_PASSWORD}" -o /dev/null -w '%{http_code}' \
+ http://localhost:8080/graphspaces/DEFAULT/graphs)" = 200
curl -fsS http://localhost:8088/about
```
-To validate local images without Compose replacing them with remote `latest`:
+Open `http://localhost:8088` and sign in as `admin` with the password from
+`.env`.
+
+Stop containers while keeping them:
```bash
-(
- cd docker
- HUGEGRAPH_SERVER_IMAGE=local/hugegraph-server:test \
- HUGEGRAPH_SERVER_PULL_POLICY=never \
- HUBBLE_IMAGE=local/hugegraph-hubble:test \
- HUBBLE_PULL_POLICY=never \
- docker compose up -d --wait
-)
+docker compose -f docker-compose-hstore.yml stop
```
----
+Remove containers and the network while keeping data:
+
+```bash
+docker compose -f docker-compose-hstore.yml down
+```
-## 3-Node Cluster Quickstart
+Delete containers, the network, and all topology data:
```bash
-cd docker
-HUGEGRAPH_VERSION=1.7.0 docker compose -f
docker-compose-3pd-3store-3server.yml up -d
+docker compose -f docker-compose-hstore.yml down -v
+```
-# To stop and remove all data volumes (clean restart)
-docker compose -f docker-compose-3pd-3store-3server.yml down -v
+### HA reference
+
+The HA topology is resource-intensive. Running it locally is not required on
+resource-constrained machines, but its Compose configuration must always render
+successfully. This PR validates HA by rendering and static review only; it does
+not start HA locally or in default CI.
+
+Start:
+
+```bash
+docker compose -f docker-compose-3pd-3store-3server.yml up -d --wait
```
-**Startup ordering** is enforced via `depends_on` with `condition:
service_healthy`:
+Status:
-1. **PD nodes** start first and must pass healthchecks (`/v1/health`)
-2. **Store nodes** start after all PD nodes are healthy
-3. **Server nodes** start after all Store nodes are healthy
+```bash
+docker compose -f docker-compose-3pd-3store-3server.yml ps
+```
-This ensures PD and Store are healthy before the server starts. The server
entrypoint still performs a best-effort partition wait after launch, so
partition assignment may take a little longer.
+Verify all published PD, Store, and Server endpoints, Server authentication,
+and Hubble:
+
+```bash
+for port in 8620 8621 8622; do
+ curl -fsS "http://localhost:${port}/v1/health";
+done
+for port in 8520 8521 8522; do
+ curl -fsS "http://localhost:${port}/v1/health";
+done
+for port in 8080 8081 8082; do
+ curl -fsS "http://localhost:${port}/versions";
+ test "$(curl -sS -o /dev/null -w '%{http_code}' \
+ "http://localhost:${port}/graphspaces/DEFAULT/graphs";)" = 401
+ test "$(curl -sS -u "admin:${ADMIN_PASSWORD}" -o /dev/null \
+ -w '%{http_code}' \
+ "http://localhost:${port}/graphspaces/DEFAULT/graphs";)" = 200
+done
+curl -fsS http://localhost:8088/about
+```
-**Verify the cluster is healthy**:
+Open `http://localhost:8088` and sign in as `admin` with the password from
+`.env`.
+
+Stop containers while keeping them:
```bash
-# Check PD health
-curl http://localhost:8620/v1/health
+docker compose -f docker-compose-3pd-3store-3server.yml stop
+```
-# Check Store health
-curl http://localhost:8520/v1/health
+Remove containers and the network while keeping data:
-# Check Server (Graph API)
-curl http://localhost:8080/versions
+```bash
+docker compose -f docker-compose-3pd-3store-3server.yml down
+```
-# List registered stores via PD
-curl http://localhost:8620/v1/stores
+Delete containers, the network, and all topology data:
-# List partitions
-curl http://localhost:8620/v1/partitions
+```bash
+docker compose -f docker-compose-3pd-3store-3server.yml down -v
```
----
-
-## Environment Variable Reference
-
-Configuration is injected via environment variables. The old
`docker/configs/application-pd*.yml` and
`docker/configs/application-store*.yml` files are no longer used.
-
-### PD Environment Variables
-
-| Variable | Required | Default | Maps To (`application.yml`) | Description |
-|----------|----------|---------|-----------------------------|-------------|
-| `HG_PD_GRPC_HOST` | Yes | — | `grpc.host` | This node's hostname/IP for gRPC
|
-| `HG_PD_RAFT_ADDRESS` | Yes | — | `raft.address` | This node's Raft address
(e.g. `pd0:8610`) |
-| `HG_PD_RAFT_PEERS_LIST` | Yes | — | `raft.peers-list` | All PD peers (e.g.
`pd0:8610,pd1:8610,pd2:8610`) |
-| `HG_PD_INITIAL_STORE_LIST` | Yes | — | `pd.initial-store-list` | Expected
stores (e.g. `store0:8500,store1:8500,store2:8500`) |
-| `HG_PD_GRPC_PORT` | No | `8686` | `grpc.port` | gRPC server port |
-| `HG_PD_REST_PORT` | No | `8620` | `server.port` | REST API port |
-| `HG_PD_DATA_PATH` | No | `/hugegraph-pd/pd_data` | `pd.data-path` | Metadata
storage path |
-| `HG_PD_INITIAL_STORE_COUNT` | No | `1` | `pd.initial-store-count` | Min
stores for cluster availability |
-
-**Deprecated aliases** (still work but log a warning):
-
-| Deprecated | Use Instead |
-|------------|-------------|
-| `GRPC_HOST` | `HG_PD_GRPC_HOST` |
-| `RAFT_ADDRESS` | `HG_PD_RAFT_ADDRESS` |
-| `RAFT_PEERS` | `HG_PD_RAFT_PEERS_LIST` |
-| `PD_INITIAL_STORE_LIST` | `HG_PD_INITIAL_STORE_LIST` |
-
-### Store Environment Variables
-
-| Variable | Required | Default | Maps To (`application.yml`) | Description |
-|----------|----------|---------|-----------------------------|-------------|
-| `HG_STORE_PD_ADDRESS` | Yes | — | `pdserver.address` | PD gRPC addresses
(e.g. `pd0:8686,pd1:8686,pd2:8686`) |
-| `HG_STORE_GRPC_HOST` | Yes | — | `grpc.host` | This node's hostname (e.g.
`store0`) |
-| `HG_STORE_RAFT_ADDRESS` | Yes | — | `raft.address` | This node's Raft
address (e.g. `store0:8510`) |
-| `HG_STORE_GRPC_PORT` | No | `8500` | `grpc.port` | gRPC server port |
-| `HG_STORE_REST_PORT` | No | `8520` | `server.port` | REST API port |
-| `HG_STORE_DATA_PATH` | No | `/hugegraph-store/storage` | `app.data-path` |
Data storage path |
-
-**Deprecated aliases** (still work but log a warning):
-
-| Deprecated | Use Instead |
-|------------|-------------|
-| `PD_ADDRESS` | `HG_STORE_PD_ADDRESS` |
-| `GRPC_HOST` | `HG_STORE_GRPC_HOST` |
-| `RAFT_ADDRESS` | `HG_STORE_RAFT_ADDRESS` |
-
-### Server Environment Variables
-
-| Variable | Required | Default | Maps To | Description |
-|----------|----------|---------|-----------------------------|-------------|
-| `HG_SERVER_BACKEND` | Yes | — | `backend` in `hugegraph.properties` |
Storage backend (e.g. `hstore`) |
-| `HG_SERVER_PD_PEERS` | Yes | — | `pd.peers` | PD cluster addresses (e.g.
`pd0:8686,pd1:8686,pd2:8686`) |
-| `HG_SERVER_CLUSTER` | No | — | `cluster` in `rest-server.properties` | PD
discovery application name; single-node Compose uses `hg` to match Hubble |
-| `HG_SERVER_USE_PD` | No | — | `usePD` in `rest-server.properties` | Enables
Server PD registration and discovery |
-| `HG_SERVER_REST_URL` | No | — | `restserver.url` | Address registered with
PD and used by clients |
-| `HG_SERVER_MIN_FREE_MEMORY` | No | — | `restserver.min_free_memory` |
Minimum free-memory guard in MB; local Compose uses `0` |
-| `HG_SERVER_AUTH_TOKEN_SECRET` | No | generated in auth mode |
`auth.token_secret` | Shared JWT secret for REST and embedded Gremlin
authentication; explicit values must be at least 32 bytes |
-| `STORE_REST` | No | — | Used by `wait-partition.sh` | Store REST endpoint
for partition verification (e.g. `store0:8520`) |
-| `PASSWORD` | No | — | Enables auth and sets `auth.admin_pa` | Initial
administrator password; disabled init-store does not read it from stdin, but
the entrypoint still applies it to the PD bootstrap path |
-| `HG_SERVER_INIT_STORE_ENABLED` | No | `true` | `init_store.enabled` in
`rest-server.properties` | Set `false` in PD/HStore deployments so init-store
skips local backend and admin initialization |
-
-> **The built-in authenticator with `HG_SERVER_INIT_STORE_ENABLED=false`
requires `usePD=true` and an HStore-backed `auth.graph_store`, unless
`auth.remote_url` delegates auth elsewhere.** With init-store skipped, the
server creates the built-in admin in PD metadata, and only an HStore auth graph
uses the PD-backed auth manager that can read that account. init-store exits
non-zero when the combination is unusable, rather than leaving a server nobody
can log in to. A custom `auth.authenticator` is exempt because it manages its
own identities.
->
-> `docker/init_complete` is written by init-store itself, and only after it
has initialized. A skipped run therefore records nothing, whether it was
disabled by the variable or by the property in a mounted
`rest-server.properties`, so a later re-enable is still able to initialize. The
marker only short-circuits re-initialization: init-store runs on every
container start, and a disabled one performs the fail-closed check above first,
so a marker left by an earlier release or an earlier enabled run cannot bypass
it.
->
-> The entrypoint maps **`PASSWORD` to `auth.admin_pa`** before init-store
runs. A disabled init-store does not read the password from standard input, but
the PD startup path uses the explicit `auth.admin_pa` value when it first
creates the administrator. Changing it later does not rotate an existing
password.
-
-The single-node Compose files also accept these deployment-level overrides:
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `HUGEGRAPH_SERVER_IMAGE` | `hugegraph/server:<version>` | Complete Server
image reference |
-| `HUGEGRAPH_SERVER_PULL_POLICY` | `always` (`build` for dev) | Server pull
policy |
-| `HUBBLE_IMAGE` | `hugegraph/hubble:<version>` | Complete Hubble image
reference |
-| `HUBBLE_PULL_POLICY` | `always` (`missing` for dev) | Hubble pull policy |
-| `HUBBLE_PUBLISH_HOST` | `127.0.0.1` | Hubble host bind address; remote
access requires an HTTPS reverse proxy |
-| `HUGEGRAPH_ADMIN_PASSWORD` | required (`docker/.env`) | Initial admin
password; no public default is provided |
-| `HUGEGRAPH_AUTH_TOKEN_SECRET` | generated | JWT signing secret; explicit
values must be at least 32 bytes |
-
-When authentication is enabled and no token secret is supplied, the Server
entrypoint generates a random secret and writes it to both authentication
configurations. The value is reused on container restart while the container
filesystem is preserved. To preserve tokens across container recreation,
generate a compatible secret once and add it to the mode-600 `docker/.env`:
+### Select image versions
+
+Set a HugeGraph release for Server, PD, and Store without changing Hubble:
```bash
-(
- set -euo pipefail
- cd docker
-
secret_pattern='^[[:space:]]*(export[[:space:]]+)?HUGEGRAPH_AUTH_TOKEN_SECRET[[:space:]]*='
- secret_count="$(grep -Ec "${secret_pattern}" .env || true)"
- case "${secret_count}" in
- 0)
- command -v openssl >/dev/null 2>&1
- token_secret="$(openssl rand -hex 32)"
- LC_ALL=C
- if (( ${#token_secret} != 64 )); then
- echo "Failed to generate a 64-character token secret" >&2
- exit 1
- fi
- printf "HUGEGRAPH_AUTH_TOKEN_SECRET='%s'\n" \
- "${token_secret}" >> .env
- unset token_secret
- echo "Generated HUGEGRAPH_AUTH_TOKEN_SECRET"
- ;;
- 1)
- token_secret="$(
- sed -nE \
- "s/${secret_pattern}'([^']*)'[[:space:]]*$/\\2/p" .env
- )"
- LC_ALL=C
- if (( ${#token_secret} < 32 )); then
- echo "Existing token secret must use the documented single-quoted" \
- "format and contain at least 32 bytes; .env was not changed" >&2
- exit 1
- fi
- unset token_secret
- echo "HUGEGRAPH_AUTH_TOKEN_SECRET already exists; reusing it"
- ;;
- *)
- echo "Duplicate HUGEGRAPH_AUTH_TOKEN_SECRET entries; repair .env" >&2
- exit 1
- ;;
- esac
- chmod 600 .env
-)
+HUGEGRAPH_VERSION=1.7.0 \
+docker compose -f docker-compose-hstore.yml up -d
+```
+
+Select Hubble independently:
+
+```bash
+HUBBLE_IMAGE=hugegraph/hubble:latest \
+docker compose -f docker-compose.yml up -d
```
-The entrypoint rejects shorter explicit values before changing either Server
configuration file.
+The Hubble `latest` image is expected to work with HugeGraph Server 1.7 and
+Server `latest`; compatibility with versions older than 1.7 is not promised.
+Pin immutable image references when reproducibility is required.
-**Deprecated aliases** (still work but log a warning):
+### Data persistence
-| Deprecated | Use Instead |
-|------------|-------------|
-| `BACKEND` | `HG_SERVER_BACKEND` |
-| `PD_PEERS` | `HG_SERVER_PD_PEERS` |
+Each topology creates its own normal Compose network and named volumes. No
+network or volume needs to be created in advance.
----
+Standalone stores RocksDB data at `/hugegraph-server/rocksdb-data`. The HStore
+topologies keep PD and Store data in topology-local volumes. Hubble uses
+`jdbc:h2:file:/hubble/data/hubble;DB_CLOSE_ON_EXIT=FALSE` and stores uploaded
+files under `/hubble/data/upload-files`.
-## Port Reference
+`docker compose down` keeps named-volume data. `docker compose down -v`
+intentionally deletes it.
-The table below reflects the published host ports in
`docker-compose-3pd-3store-3server.yml`. The single-node Compose file publishes
`8620`, `8520`, `8080`, and Hubble `8088`; Hubble defaults to host loopback.
+## Developers
-| Service | Container Port | Host Port | Protocol | Purpose |
-|---------|---------------|-----------|----------|---------|
-| pd0 | 8620 | 8620 | HTTP | REST API |
-| pd0 | 8686 | 8686 | gRPC | PD gRPC |
-| pd0 | 8610 | — | TCP | Raft (internal only) |
-| pd1 | 8620 | 8621 | HTTP | REST API |
-| pd1 | 8686 | 8687 | gRPC | PD gRPC |
-| pd2 | 8620 | 8622 | HTTP | REST API |
-| pd2 | 8686 | 8688 | gRPC | PD gRPC |
-| store0 | 8500 | 8500 | gRPC | Store gRPC |
-| store0 | 8510 | 8510 | TCP | Raft |
-| store0 | 8520 | 8520 | HTTP | REST API |
-| store1 | 8500 | 8501 | gRPC | Store gRPC |
-| store1 | 8510 | 8511 | TCP | Raft |
-| store1 | 8520 | 8521 | HTTP | REST API |
-| store2 | 8500 | 8502 | gRPC | Store gRPC |
-| store2 | 8510 | 8512 | TCP | Raft |
-| store2 | 8520 | 8522 | HTTP | REST API |
-| server0 | 8080 | 8080 | HTTP | Graph API |
-| server1 | 8080 | 8081 | HTTP | Graph API |
-| server2 | 8080 | 8082 | HTTP | Graph API |
+### Images and Compose files
----
+| Image | Build file |
+| --- | --- |
+| `hugegraph/hugegraph` (standalone RocksDB Server) |
`hugegraph-server/Dockerfile` |
+| `hugegraph/server` (HStore Server) | `hugegraph-server/Dockerfile-hstore` |
+| `hugegraph/pd` | `hugegraph-pd/Dockerfile` |
+| `hugegraph/store` | `hugegraph-store/Dockerfile` |
-## Healthcheck Endpoints
+Hubble is built from the separate HugeGraph Toolchain repository and is
+selected here with `HUBBLE_IMAGE`.
-| Service | Endpoint | Expected |
-|---------|----------|----------|
-| PD | `GET /v1/health` | `200 OK` |
-| Store | `GET /v1/health` | `200 OK` |
-| Server | `GET /versions` | `200 OK` with version JSON |
-| Hubble | `GET /about` | `200` JSON with Hubble name and version |
+The Compose mapping is intentionally small:
----
+- `docker-compose.yml` is the standalone user default.
+- `docker-compose-hstore.yml` is the minimal 1 PD + 1 Store + 1 Server base.
+- `docker-compose-3pd-3store-3server.yml` is the HA reference.
+- `docker-compose.dev.yml` is a thin source-build override for the minimal
+ HStore topology. It does not duplicate runtime services, networks, volumes,
+ health checks, or Hubble.
-## Troubleshooting
+Build and start the minimal topology from local source:
-### Containers Exiting or Restarting (OOM Kills)
+```bash
+docker compose \
+ -f docker-compose-hstore.yml \
+ -f docker-compose.dev.yml \
+ up -d --build --wait
+```
-**Symptom**: Containers exit with code 137, or restart loops. Raft logs show
election timeouts.
+Use both files for every later lifecycle command, for example:
-**Cause**: Docker Desktop does not have enough memory. The 9 JVM processes
require at least 12 GB.
+```bash
+docker compose \
+ -f docker-compose-hstore.yml \
+ -f docker-compose.dev.yml \
+ down
+```
-**Fix**: Docker Desktop → Settings → Resources → Memory → set to **12 GB** or
higher. Restart Docker Desktop.
+The development overlay builds `hugegraph/pd:dev`, `hugegraph/store:dev`, and
+`hugegraph/server:dev`. To reuse those local images and a locally built Hubble
+without pulling replacements:
```bash
-# Check if containers were OOM killed
-docker inspect hg-pd0 | grep -i oom
-docker stats --no-stream
+HUGEGRAPH_VERSION=dev \
+HUGEGRAPH_PULL_POLICY=never \
+HUBBLE_IMAGE=local/hugegraph-hubble:test \
+HUBBLE_PULL_POLICY=never \
+docker compose -f docker-compose-hstore.yml up -d --wait
```
-### Raft Leader Election Failure
+### Hubble configuration
+
+The three small files under `conf/hubble/` contain only topology-specific
+discovery settings and container paths:
-**Symptom**: PD logs show repeated `Leader election timeout`. Store nodes
cannot register.
+- `conf/hubble/standalone.properties` uses direct Server mode.
+- `conf/hubble/hstore.properties` uses one PD and one Store REST target.
+- `conf/hubble/hstore-ha.properties` uses all three PD peers and all three
+ allowed Store REST targets.
-**Cause**: PD nodes cannot reach each other on the Raft port (8610), or
`HG_PD_RAFT_PEERS_LIST` is misconfigured.
+Hubble detects Server authentication through the Server API. Do not add an
+`auth.enabled` property or duplicate auth-on/auth-off configurations.
-**Fix**:
-1. Verify all PD containers are running: `docker compose -f
docker-compose-3pd-3store-3server.yml ps`
-2. Check PD logs: `docker logs hg-pd0`
-3. Verify network connectivity: `docker exec hg-pd0 ping pd1`
-4. Ensure `HG_PD_RAFT_PEERS_LIST` is identical on all PD nodes
+### Render and smoke checks
-### Partition Assignment Not Completing
+Render every topology with auth-on inputs before submitting a change:
-**Symptom**: Server starts but graph operations fail. Store logs show
`partition not found`.
+```bash
+for file in \
+ docker-compose.yml \
+ docker-compose-hstore.yml \
+ docker-compose-3pd-3store-3server.yml
+do
+ docker compose -f "${file}" config --quiet
+done
+docker compose \
+ -f docker-compose-hstore.yml \
+ -f docker-compose.dev.yml \
+ config --quiet
Review Comment:
Confirmed and fixed in 9cf8de733. The hand-written loop could render
auth-off while claiming auth-on. The README now calls bash test-compose.sh
render, which injects deterministic auth-on inputs and checks all three
topologies plus the developer overlay with the same contracts used by CI.
##########
docker/README.md:
##########
@@ -1,436 +1,362 @@
-# HugeGraph Docker Deployment
+# HugeGraph Docker Compose
-This directory contains Docker Compose files for running HugeGraph:
+## Users
-| File | Description |
-|------|-------------|
-| `docker-compose.yml` | PD, Store, Server, and Hubble using pre-built images |
-| `docker-compose.dev.yml` | PD, Store, and Server built from source, plus
Hubble |
-| `docker-compose-3pd-3store-3server.yml` | 3-node distributed cluster (PD +
Store + Server) |
+### Choose a topology
-## Prerequisites
+Run commands in this directory:
-- **Docker Engine** 20.10+ (or Docker Desktop 4.x+)
-- **Docker Compose** v2 (included in Docker Desktop)
-- **OpenSSL CLI** (used to generate the initial administrator password)
-- **Memory**: Allocate at least **12 GB** to Docker Desktop (Settings →
Resources → Memory). The 3-node cluster runs 9 JVM processes (3 PD + 3 Store +
3 Server) which are memory-intensive. Insufficient memory causes OOM kills that
appear as silent Raft failures.
+```bash
+cd docker
+```
-> [!IMPORTANT]
-> The 12 GB minimum is for Docker Desktop. On Linux with native Docker, ensure
the host has at least 12 GB of free memory.
----
+| Topology | Compose file | Services | When to use it |
+| --- | --- | --- | --- |
+| Standalone | `docker-compose.yml` | 1 RocksDB Server + 1 Hubble | Default;
start here |
+| Minimal HStore | `docker-compose-hstore.yml` | 1 PD + 1 Store + 1 Server + 1
Hubble | Distributed local development |
+| HA | `docker-compose-3pd-3store-3server.yml` | 3 PD + 3 Store + 3 Server + 1
Hubble | Reference and evaluation |
-## Single-Node Setup
+Standalone uses `hugegraph/hugegraph:${HUGEGRAPH_VERSION:-latest}`. The HStore
+topologies use the matching `hugegraph/pd`, `hugegraph/store`, and
+`hugegraph/server` tags. Hubble is selected independently with
+`${HUBBLE_IMAGE:-hugegraph/hubble:latest}`.
-Two compose files run one PD, one Store, one Server, and one Hubble instance:
+### Create the authentication environment
-Create a Compose environment file once so every lifecycle command can resolve
the required administrator password:
+Create `.env` once. Replace `replace-with-your-password` with an administrator
+password that you choose; the command generates and persists a random 32-byte
+JWT secret. For this simple single-quoted format, do not use a password that
+contains a single quote or newline.
```bash
(
set -eu
- cd docker
- if [ -e .env ]; then
- echo "docker/.env already exists; reusing it"
- else
- command -v openssl >/dev/null 2>&1
- admin_password="$(openssl rand -base64 12)"
- if [ "${#admin_password}" -ne 16 ]; then
- echo "Failed to generate a 16-character password" >&2
- exit 1
- fi
- install -m 600 /dev/null .env
- {
- printf "HUGEGRAPH_ADMIN_PASSWORD='%s'\n" "${admin_password}"
- } >> .env
- unset admin_password
- fi
- chmod 600 .env
- if ! env -u HUGEGRAPH_ADMIN_PASSWORD \
- docker compose -f docker-compose.yml config --quiet ||
- ! env -u HUGEGRAPH_ADMIN_PASSWORD \
- docker compose -f docker-compose.dev.yml config --quiet; then
- echo "docker/.env is incomplete; repair or move it, then retry" >&2
+ command -v openssl >/dev/null
+ jwt_secret="$(openssl rand -hex 32)"
+ test "${#jwt_secret}" -eq 64
Review Comment:
Confirmed these lines are defensive rather than strictly necessary under set
-eu, but keeping them. They make the OpenSSL dependency and the expected
64-hex-character invariant explicit in the copied bootstrap block, at a cost of
two simple lines and without adding another code path.
##########
docker/test-compose.sh:
##########
@@ -0,0 +1,403 @@
+#!/usr/bin/env bash
+#
+# 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.
+#
+
+set -Eeuo pipefail
+
+DOCKER_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PASSWORD="ci-compose-password"
+SECRET="0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+VERSION="ci-version"
+RENDER_HUBBLE_IMAGE="example.invalid/hugegraph/hubble:ci"
+DATASOURCE="jdbc:h2:file:/hubble/data/hubble;DB_CLOSE_ON_EXIT=FALSE"
+CURL_TIMEOUTS=(--connect-timeout 5 --max-time 15)
+ACTIVE_PROJECT=""
+ACTIVE_FILES=()
+RENDER_DIR=""
+
+compose_auth() {
+ env HUGEGRAPH_VERSION="${VERSION}" \
+ HUBBLE_IMAGE="${RENDER_HUBBLE_IMAGE}" \
+ HUGEGRAPH_ADMIN_PASSWORD="${PASSWORD}" \
+ HUGEGRAPH_AUTH_TOKEN_SECRET="${SECRET}" \
+ docker compose "$@"
+}
+
+render() {
+ local output="$1"
+ shift
+ compose_auth "$@" config --format json > "${output}"
+}
+
+assert_file_property() {
+ local file="$1"
+ local property="$2"
+ grep -Fqx "${property}" "${file}"
+}
+
+assert_common() {
+ local rendered="$1"
+ local services="$2"
+ local volumes="$3"
+
+ jq -e \
+ --arg password "${PASSWORD}" \
+ --arg secret "${SECRET}" \
Review Comment:
Thanks for the mutation check; agreed that these contracts and
smoke-auth-off should stay. No removal was made. The independent pass also
added the missing one-line HG_SERVER_CLUSTER == hg assertion for the minimal
HStore render in 9cf8de733.
##########
docker/docker-compose-3pd-3store-3server.yml:
##########
@@ -58,6 +59,18 @@ x-store-common: &store-common
retries: 40
start_period: 120s
+x-server-environment: &server-environment
+ STORE_REST: store0:8520
+ HG_SERVER_BACKEND: hstore
+ HG_SERVER_PD_PEERS: pd0:8686,pd1:8686,pd2:8686
+ HG_SERVER_CLUSTER: hg
+ HG_SERVER_USE_PD: "true"
+ HG_SERVER_MIN_FREE_MEMORY: "0"
+ HG_SERVER_INIT_STORE_ENABLED: "false"
+ HG_SERVER_REQUIRE_AUTH_TOKEN_SECRET: "true"
+ HG_SERVER_AUTH_TOKEN_SECRET: ${HUGEGRAPH_AUTH_TOKEN_SECRET:-}
+ PASSWORD: ${HUGEGRAPH_ADMIN_PASSWORD:-}
Review Comment:
Agreed: this is a possible follow-up cleanup, not a request against this PR.
PD/Store anchor refactoring is outside the changed behavior and would expand
the review surface for a small line-count gain, so it remains unchanged.
--
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]
