Run commands in this directory:

cd docker

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}.

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.

(
  set -eu
  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
  }
  printf "HUGEGRAPH_ADMIN_PASSWORD='%s'\nHUGEGRAPH_AUTH_TOKEN_SECRET='%s'\n" \
    'replace-with-your-password' "${jwt_secret}" > .env
)

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.

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.

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:

ADMIN_PASSWORD='the-same-password-used-in-.env'

This is the recommended quickstart.

Start:

docker compose -f docker-compose.yml up -d --wait

Status:

docker compose -f docker-compose.yml ps

Verify Server readiness, authentication, and Hubble:

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

Open http://localhost:8088 and sign in as admin with the password from .env.

Stop containers while keeping them:

docker compose -f docker-compose.yml stop

Remove containers and the network while keeping data:

docker compose -f docker-compose.yml down

Delete containers, the network, and all topology data:

docker compose -f docker-compose.yml down -v

Start:

docker compose -f docker-compose-hstore.yml up -d --wait

Status:

docker compose -f docker-compose-hstore.yml ps

Verify PD, Store, Server authentication, and Hubble:

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

Open http://localhost:8088 and sign in as admin with the password from .env.

Stop containers while keeping them:

docker compose -f docker-compose-hstore.yml stop

Remove containers and the network while keeping data:

docker compose -f docker-compose-hstore.yml down

Delete containers, the network, and all topology data:

docker compose -f docker-compose-hstore.yml down -v

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:

docker compose -f docker-compose-3pd-3store-3server.yml up -d --wait

Status:

docker compose -f docker-compose-3pd-3store-3server.yml ps

Verify all published PD, Store, and Server endpoints, Server authentication, and Hubble:

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

Open http://localhost:8088 and sign in as admin with the password from .env.

Stop containers while keeping them:

docker compose -f docker-compose-3pd-3store-3server.yml stop

Remove containers and the network while keeping data:

docker compose -f docker-compose-3pd-3store-3server.yml down

Delete containers, the network, and all topology data:

docker compose -f docker-compose-3pd-3store-3server.yml down -v

Set a HugeGraph release for Server, PD, and Store without changing Hubble:

HUGEGRAPH_VERSION=1.7.0 \
docker compose -f docker-compose-hstore.yml up -d

Select Hubble independently:

HUBBLE_IMAGE=hugegraph/hubble:latest \
docker compose -f docker-compose.yml up -d

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.

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.

docker compose down keeps named-volume data. docker compose down -v intentionally deletes it.

Hubble is built from the separate HugeGraph Toolchain repository and is selected here with HUBBLE_IMAGE.

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.

Build and start the minimal topology from local source:

docker compose \
  -f docker-compose-hstore.yml \
  -f docker-compose.dev.yml \
  up -d --build --wait

Use both files for every later lifecycle command, for example:

docker compose \
  -f docker-compose-hstore.yml \
  -f docker-compose.dev.yml \
  down

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:

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

The three small files under conf/hubble/ contain only topology-specific discovery settings and container paths:

• 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.

Hubble detects Server authentication through the Server API. Do not add an auth.enabled property or duplicate auth-on/auth-off configurations.

Render every topology with auth-on inputs before submitting a change:

bash test-compose.sh render

The HA render is mandatory even when local resources are insufficient to start its ten containers.

Run focused auth-on smoke checks for standalone and minimal HStore with the corresponding up -d --wait, status, authentication, Hubble /about, and down -v commands from the Users section:

bash test-compose.sh smoke

Run the required local auth-off checks separately:

bash test-compose.sh smoke-auth-off

The auth-off mode is intentionally excluded from the default CI matrix and must remain on a trusted local machine. Both smoke modes remove only the isolated Compose projects and volumes that they create.