[Bug] Docker setup broken on macOS/Windows — network_mode: host replaced with bridge networking (single-node + 3-node cluster)

[bitflicker64]

Bug Type (问题类型)

others (please edit later)

Before submit

• 我已经确认现有的 Issues 与 FAQ 中没有相同 / 重复问题 (I have confirmed and searched that there are no similar problems in the historical issue and documents)

Environment (环境信息)

PR is based on master branch (miscommunication in issue description).
Docker Desktop on macOS and Windows
Deployment method docker compose single node configuration
File docker-compose.yml

Expected & Actual behavior (期望与实际表现)

Expected Behavior

Single node cluster starts normally

Actual Behavior

Server stuck printing Hugegraph server are waiting for storage backend
Server logs show UNAVAILABLE io exception
Store reports {"leaderCount":0,"partitionCount":0}
Cluster never becomes usable even though containers run

Description

The single node Docker setup uses network_mode host. This works only on Linux.
On macOS and Windows, Docker Desktop does not support host networking the same way.
Containers fall back to bridge networking but service configuration still assumes localhost style addresses.

PD and Store advertise gRPC endpoints as 0.0.0.0 or 127.0.0.1.
These are bind addresses, not reachable service addresses inside Docker networking.
Other containers cannot connect, causing PD client failures and preventing partition creation.

Root Cause

network_mode host is Linux only
Docker Desktop ignores or emulates it differently
Services advertise non routable addresses
Server fails to communicate with PD

Fix

Switch to bridge networking and container hostnames.

docker-compose.yml

Remove network_mode host
Use default bridge network
Add environment override hugegraph.pd.peers=pd:8686

docker/pd-conf/application.yml

grpc.host set to pd
raft.address set to pd:8610
raft.peers-list set to pd:8610
initial-store-list set to store:8500

docker/store-conf/application.yml

grpc.host set to store
raft.address set to store:8510
pdserver.address=pd:8686

Why This Works

Bridge networking is cross platform
Docker resolves container names automatically
Services advertise reachable addresses

Result After Fix

PD reachable via pd:8686
Store registers as store:8500
Partitions created normally
Server reachable on localhost 8080

Related fixes discovered during this work:

Bug	Issue	Fix
getLeaderGrpcAddress() NPE in bridge mode	#2959	#2961
IpAuthHandler hostname vs IP mismatch	#2960	#2962
'Docker Logs' Not Working	#2979	#2980

---

Changes Checklist

• Added / verified required port mappings
• Updated Docker networking configuration
• Adjusted service communication to use container hostnames
• Validated environment-based configuration
• Verified PD, Store, and Server containers start correctly
• Confirmed single-node cluster reaches healthy state
• Confirmed partition assignment and leader election
• Validated multi-node (3-node) cluster deployment
• Tested on macOS (Apple M4)
• Fixed server startup timeout to allow partition assignment to complete
• Verified PD, Store and Server healthchecks pass on both single and 3-node
• Test on Linux
• Fixed IpAuthHandler hostname vs IP resolution (fix(pd): resolve hostname entries in IpAuthHandler allowlist #2962)
• Fixed getLeaderGrpcAddress() NPE (fix(pd): add timeout and null-safety to getLeaderGrpcAddress() #2961)
• Removed static IP workaround after IpAuthHandler fix
• Update Docker images to reflect entrypoint changes chore(docker): remove tmp volume mounts after image update #2976
• Update in-repo documentation — docs: update Docker deployment docs for bridge networking migration #2963
• Fix docker Logs - fix(docker): enable docker logs for pd/store/server containers #2980
• Update documentation (follow-up PR to hugegraph-doc) — doc: add docker-compose guide and update deployment docs hugegraph-doc#455

[imbajin]

Thanks for the detailed report. A quick note first: we are currently in the Lunar New Year holiday period (similar to Christmas/New Year for many maintainers), so response times may be a bit slower than usual. Thanks for your patience.

Your diagnosis is valid and this is not an isolated incident. In fact, PR #2529 already had an “avoid host network” TODO, so is a known technical debt. The direction is clear and should be handled as a proper refactor rather than incremental patching.

Also, please base the compose changes on the current master branch, not on old 1.5.0-era config files. Master already includes several recent fixes that affect practical usability (startup/config behavior), and continuing from older code can introduce avoidable drift.

Recommended docker-compose refactor direction:

1. Move single-node compose to bridge networking by default and remove host networking, so behavior is consistent across Linux/macOS/Windows Docker Desktop.
2. Separate bind vs advertise addresses: bind can stay at 0.0.0.0, but service discovery must use container-reachable names (for example pd:8686, store:8500).
3. Explicitly set hugegraph.pd.peers=pd:8686 on the server side to avoid localhost/127.0.0.1 fallback.
4. Align healthcheck endpoints to avoid false positives where containers are healthy but the cluster is not usable.
5. Keep the patch surface minimal; prefer small config overrides instead of copying full conf directories to reduce long-term maintenance cost.
6. Validation could focus on Unix environments (primarily Linux + macOS)

BTW, maybe we do need a plan for it first (before review PR #2952, to avoid large gaps)

Also I'll share a CI(action) file for u to test it in your docker environment.

[imbajin]

Example for the image build:

name: "Publish pd-store-server image(latest)"

on:
  workflow_dispatch:
    inputs:
      mvn_args:
        required: false
        default: ''
        description: 'mvn build args, like "MAVEN_ARGS=-P stage"'
 
jobs:
  build_latest:
    runs-on: ubuntu-latest
    env:
      REPOSITORY_URL: apache/hugegraph
      BRANCH: master
      PD_IMAGE_URL: hugegraph/pd:latest
      STORE_IMAGE_URL: hugegraph/store:latest
      SERVER_IMAGE_URL: hugegraph/server:latest
      MVN_ARGS: ${{inputs.mvn_args}}

    steps:
    # - name: Maximize Build Space
    #   uses: easimon/maximize-build-space@master
    #   with:
    #     root-reserve-mb: 512
    #     swap-size-mb: 1024
    #     remove-dotnet: 'true'

    - name: Set up Docker Buildx
      uses: docker/setup-buildx-action@v3

    - name: Login to Docker Hub
      uses: docker/login-action@v3
      with:
        username: ${{ secrets.DOCKERHUB_USERNAME }}
        password: ${{ secrets.DOCKERHUB_PASSWORD }}

    - name: Checkout latest
      uses: actions/checkout@v4
      with:
        repository: ${{ env.REPOSITORY_URL }}
        ref: ${{ env.BRANCH }}
        fetch-depth: 2

    - name: Build x86 PD Image
      uses: docker/build-push-action@v5
      with:
        context: .
        file: ./hugegraph-pd/Dockerfile
        load: true
        tags: ${{ env.PD_IMAGE_URL }}
        # cache-from: type=gha
        # cache-to: type=gha,mode=max
        build-args: ${{ env.MVN_ARGS }}

    - name: Build x86 Store Image
      uses: docker/build-push-action@v5
      with:
        context: .
        file: ./hugegraph-store/Dockerfile
        load: true
        tags: ${{ env.STORE_IMAGE_URL }}
        # cache-from: type=gha
        # cache-to: type=gha,mode=max
        build-args: ${{ env.MVN_ARGS }}

    - name: Build x86 Server Image
      uses: docker/build-push-action@v5
      with:
        context: .
        file: ./hugegraph-server/Dockerfile-hstore
        load: true
        tags: ${{ env.SERVER_IMAGE_URL }}
        # cache-from: type=gha
        # cache-to: type=gha,mode=max
        build-args: ${{ env.MVN_ARGS }}

    - name: Test x86 Images
      run: |
        docker images
        docker run -itd --name=pd --network host $PD_IMAGE_URL
        sleep 10s
        curl 0.0.0.0:8620 || exit
        docker run -itd --name=store --network host $STORE_IMAGE_URL
        sleep 10s
        curl 0.0.0.0:8520 || exit
        docker run -itd --name=server --network host $SERVER_IMAGE_URL
        sleep 10s
        curl 0.0.0.0:8080 || exit
        docker ps -a

    - name: Push x86 & ARM PD Images
      uses: docker/build-push-action@v5
      with:
        context: .
        file: ./hugegraph-pd/Dockerfile
        platforms: linux/amd64,linux/arm64
        push: true
        tags: ${{ env.PD_IMAGE_URL }}
        # cache-from: type=gha
        # cache-to: type=gha,mode=max
        build-args: ${{ env.MVN_ARGS }}

    - name: Push x86 & ARM Store Images
      uses: docker/build-push-action@v5
      with:
        context: .
        file: ./hugegraph-store/Dockerfile
        platforms: linux/amd64,linux/arm64
        push: true
        tags: ${{ env.STORE_IMAGE_URL }}
        # cache-from: type=gha
        # cache-to: type=gha,mode=max
        build-args: ${{ env.MVN_ARGS }}

    - name: Push x86 & ARM Server Images
      uses: docker/build-push-action@v5
      with:
        context: .
        file: ./hugegraph-server/Dockerfile-hstore
        platforms: linux/amd64,linux/arm64
        push: true
        tags: ${{ env.SERVER_IMAGE_URL }}
        # cache-from: type=gha
        # cache-to: type=gha,mode=max
        build-args: ${{ env.MVN_ARGS }}

Note, this file also has a great improvement space (legacy)

[bitflicker64]

Thanks for the detailed report. A quick note first: we are currently in the Lunar New Year holiday period (similar to Christmas/New Year for many maintainers), so response times may be a bit slower than usual. Thanks for your patience.

Your diagnosis is valid and this is not an isolated incident. In fact, PR #2529 already had an “avoid host network” TODO, so is a known technical debt. The direction is clear and should be handled as a proper refactor rather than incremental patching.

Also, please base the compose changes on the current master branch, not on old 1.5.0-era config files. Master already includes several recent fixes that affect practical usability (startup/config behavior), and continuing from older code can introduce avoidable drift.

Recommended docker-compose refactor direction:

1. Move single-node compose to bridge networking by default and remove host networking, so behavior is consistent across Linux/macOS/Windows Docker Desktop.
2. Separate bind vs advertise addresses: bind can stay at 0.0.0.0, but service discovery must use container-reachable names (for example pd:8686, store:8500).
3. Explicitly set hugegraph.pd.peers=pd:8686 on the server side to avoid localhost/127.0.0.1 fallback.
4. Align healthcheck endpoints to avoid false positives where containers are healthy but the cluster is not usable.
5. Keep the patch surface minimal; prefer small config overrides instead of copying full conf directories to reduce long-term maintenance cost.
6. Validation could focus on Unix environments (primarily Linux + macOS)

BTW, maybe we do need a plan for it first (before review PR #2952, to avoid large gaps)

Also I'll share a CI(action) file for u to test it in your docker environment.

Makes sense. Thanks for the clarification and detailed guidance. I will review the refactor direction and update my perspective based on the points you outlined.

[imbajin]

Makes sense. Thanks for the clarification and detailed guidance. I will review the refactor direction and update my perspective based on the points you outlined.

I also use a (basic) PLAN mode with LLM to generate a plan doc (for reference but not the final decision)

---

HugeGraph Docker Compose Refactor Plan

Scope: Replace the current redundant, host-network-coupled Docker setup with a
maintainable, cross-platform deployment for Server + PD + Store.

---

1. Problem Statement

Current Pain Points

#	Problem	Detail
1	Host networking	network_mode: host is Linux-only; breaks on Docker Desktop (macOS / Windows)
2	Config duplication	server1-conf / server2-conf / server3-conf, pd0.yml / pd1.yml / pd2.yml are near-identical
3	Unclear env contract	Legacy names (PD_ADDRESS, GRPC_HOST, RAFT_ADDRESS) are ambiguous and hard to debug
4	Opaque runtime	Variable effectiveness is invisible; failures surface late instead of fail-fast at startup

---

2. Design Goals

1. Cross-platform first — Linux + macOS behave consistently via bridge networking.
2. Low duplication — Eliminate static multi-copy config directories.
3. Explicit control — Core network/discovery settings validated at startup.
4. Readable & debuggable — Startup logs print all effective key-values.
5. CI-friendly — Config validation and cluster health checks are automatable.

---

3. Architecture Comparison

Before → After

  ┌─── BEFORE ─────────────────────┐       ┌─── AFTER ────────────────────────────┐
  │                                │       │                                      │
  │  docker-compose (host net)     │       │  docker-compose (bridge net)          │
  │        │                       │       │  + YAML anchors for reuse            │
  │        ▼                       │       │        │                              │
  │  many static config files      │       │        ▼                              │
  │  docker/configs/*              │       │  HG_* env contract                   │
  │        │                       │       │  (single source of truth)             │
  │        ▼                       │       │        │                              │
  │  per-node copy model           │       │        ▼                              │
  │  pd0/pd1/pd2 yml              │       │  docker-entrypoint mapping            │
  │  store0/1/2 yml               │       │  HG_* → real config keys              │
  │  server1/2/3 conf             │       │  + required checks                    │
  │        │                       │       │  + deprecated var hard-fail           │
  │        ▼                       │       │        │                              │
  │  ⚠ behavior depends on        │       │        ▼                              │
  │    host-net semantics          │       │  ✔ predictable runtime               │
  │                                │       │  ✔ easy docs / CI / less duplication  │
  └────────────────────────────────┘       └──────────────────────────────────────┘

Configuration Flow

  compose.yaml
    └─▶ environment: HG_*
          └─▶ entrypoint mapping layer
                └─▶ Spring / hugegraph config keys
                      └─▶ service startup
                            └─▶ health checks

---

4. Configuration Contract (v1)

4.1 PD Service (hugegraph/pd)

Env Var	Target Key	Req?	Default
HG_PD_GRPC_HOST	grpc.host	✔	—
HG_PD_GRPC_PORT	grpc.port	—	8686
HG_PD_REST_PORT	server.port	—	8620
HG_PD_RAFT_ADDRESS	raft.address	✔	—
HG_PD_RAFT_PEERS_LIST	raft.peers-list	✔	—
HG_PD_INITIAL_STORE_LIST	pd.initial-store-list	✔ ¹	—
HG_PD_DATA_PATH	pd.data-path	—	/hugegraph-pd/pd_data

¹ Required at bootstrap only.

4.2 Store Service (hugegraph/store)

Env Var	Target Key	Req?	Default
HG_STORE_PD_ADDRESS	pdserver.address	✔	—
HG_STORE_GRPC_HOST	grpc.host	✔	—
HG_STORE_GRPC_PORT	grpc.port	—	8500
HG_STORE_REST_PORT	server.port	—	8520
HG_STORE_RAFT_ADDRESS	raft.address	✔	—
HG_STORE_DATA_PATH	app.data-path	—	/hugegraph-store/storage

4.3 Server Service (hugegraph/server)

Env Var	Target Key	Req?	Default
HG_SERVER_BACKEND	hugegraph.backend	—	hstore
HG_SERVER_PD_PEERS	hugegraph.pd.peers	✔ ²	—

² Required when backend is hstore.

4.4 Deprecated Variables (hard-fail on detect)

PD_ADDRESS · GRPC_HOST · RAFT_ADDRESS · RAFT_PEERS · (any undocumented legacy alias)

Policy: If any deprecated variable is detected at startup, the entrypoint
exits immediately with migration guidance.

---

5. Reference Compose A — Single Node

Target file: docker/docker-compose.yml

version: "3.9"
name: hugegraph-single

networks:
  hg-net:
    driver: bridge

volumes:
  hg-pd-data:
  hg-store-data:

services:
  pd:
    image: hugegraph/pd:${HUGEGRAPH_VERSION:-1.7.0}
    container_name: hg-pd
    hostname: pd
    restart: unless-stopped
    networks: [hg-net]
    environment:
      HG_PD_GRPC_HOST: pd
      HG_PD_GRPC_PORT: "8686"
      HG_PD_REST_PORT: "8620"
      HG_PD_RAFT_ADDRESS: pd:8610
      HG_PD_RAFT_PEERS_LIST: pd:8610
      HG_PD_INITIAL_STORE_LIST: store:8500
      HG_PD_DATA_PATH: /hugegraph-pd/pd_data
    ports:
      - "8620:8620"
      - "8686:8686"
    volumes:
      - hg-pd-data:/hugegraph-pd/pd_data
    healthcheck:
      test: ["CMD-SHELL", "curl -fsS http://localhost:8620/v1/health >/dev/null || exit 1"]
      interval: 10s
      timeout: 5s
      retries: 12

  store:
    image: hugegraph/store:${HUGEGRAPH_VERSION:-1.7.0}
    container_name: hg-store
    hostname: store
    restart: unless-stopped
    networks: [hg-net]
    depends_on:
      pd:
        condition: service_healthy
    environment:
      HG_STORE_PD_ADDRESS: pd:8686
      HG_STORE_GRPC_HOST: store
      HG_STORE_GRPC_PORT: "8500"
      HG_STORE_REST_PORT: "8520"
      HG_STORE_RAFT_ADDRESS: store:8510
      HG_STORE_DATA_PATH: /hugegraph-store/storage
    ports:
      - "8520:8520"
      - "8500:8500"
      - "8510:8510"
    volumes:
      - hg-store-data:/hugegraph-store/storage
    healthcheck:
      test: ["CMD-SHELL", "curl -fsS http://localhost:8520/v1/health >/dev/null || exit 1"]
      interval: 10s
      timeout: 5s
      retries: 12

  server:
    image: hugegraph/server:${HUGEGRAPH_VERSION:-1.7.0}
    container_name: hg-server
    hostname: server
    restart: unless-stopped
    networks: [hg-net]
    depends_on:
      store:
        condition: service_healthy
    environment:
      HG_SERVER_BACKEND: hstore
      HG_SERVER_PD_PEERS: pd:8686
    ports:
      - "8080:8080"
    healthcheck:
      test: ["CMD-SHELL", "curl -fsS http://localhost:8080/versions >/dev/null || exit 1"]
      interval: 10s
      timeout: 5s
      retries: 20

---

6. Reference Compose B — 3 PD + 3 Store + 3 Server

Target file: docker/docker-compose-3pd-3store-3server.yml

Uses YAML anchors (x-*-common) to eliminate per-node duplication.
Only hostname, ports, and volumes differ between instances.

📄 Click to expand full 3×3 compose file

version: "3.9"
name: hugegraph-3x3

# ── Shared service templates ──────────────────────────────────────────

x-pd-common: &pd-common
  image: hugegraph/pd:${HUGEGRAPH_VERSION:-1.7.0}
  restart: unless-stopped
  networks: [hg-net]
  healthcheck:
    test: ["CMD-SHELL", "curl -fsS http://localhost:8620/v1/health >/dev/null || exit 1"]
    interval: 10s
    timeout: 5s
    retries: 12

x-store-common: &store-common
  image: hugegraph/store:${HUGEGRAPH_VERSION:-1.7.0}
  restart: unless-stopped
  networks: [hg-net]
  depends_on:
    pd0: { condition: service_healthy }
    pd1: { condition: service_healthy }
    pd2: { condition: service_healthy }
  healthcheck:
    test: ["CMD-SHELL", "curl -fsS http://localhost:8520/v1/health >/dev/null || exit 1"]
    interval: 10s
    timeout: 5s
    retries: 15

x-server-common: &server-common
  image: hugegraph/server:${HUGEGRAPH_VERSION:-1.7.0}
  restart: unless-stopped
  networks: [hg-net]
  depends_on:
    store0: { condition: service_healthy }
    store1: { condition: service_healthy }
    store2: { condition: service_healthy }
  environment:
    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"]
    interval: 10s
    timeout: 5s
    retries: 20

# ── Services ──────────────────────────────────────────────────────────

services:
  # --- PD cluster (3 nodes) ---
  pd0:
    <<: *pd-common
    container_name: hg-pd0
    hostname: pd0
    environment:
      HG_PD_GRPC_HOST: pd0
      HG_PD_GRPC_PORT: "8686"
      HG_PD_REST_PORT: "8620"
      HG_PD_RAFT_ADDRESS: pd0:8610
      HG_PD_RAFT_PEERS_LIST: pd0:8610,pd1:8610,pd2:8610
      HG_PD_INITIAL_STORE_LIST: store0:8500,store1:8500,store2:8500
      HG_PD_DATA_PATH: /hugegraph-pd/pd_data
    ports: ["8620:8620", "8686:8686"]
    volumes: [hg-pd0-data:/hugegraph-pd/pd_data]

  pd1:
    <<: *pd-common
    container_name: hg-pd1
    hostname: pd1
    environment:
      HG_PD_GRPC_HOST: pd1
      HG_PD_GRPC_PORT: "8686"
      HG_PD_REST_PORT: "8620"
      HG_PD_RAFT_ADDRESS: pd1:8610
      HG_PD_RAFT_PEERS_LIST: pd0:8610,pd1:8610,pd2:8610
      HG_PD_INITIAL_STORE_LIST: store0:8500,store1:8500,store2:8500
      HG_PD_DATA_PATH: /hugegraph-pd/pd_data
    ports: ["8621:8620", "8687:8686"]
    volumes: [hg-pd1-data:/hugegraph-pd/pd_data]

  pd2:
    <<: *pd-common
    container_name: hg-pd2
    hostname: pd2
    environment:
      HG_PD_GRPC_HOST: pd2
      HG_PD_GRPC_PORT: "8686"
      HG_PD_REST_PORT: "8620"
      HG_PD_RAFT_ADDRESS: pd2:8610
      HG_PD_RAFT_PEERS_LIST: pd0:8610,pd1:8610,pd2:8610
      HG_PD_INITIAL_STORE_LIST: store0:8500,store1:8500,store2:8500
      HG_PD_DATA_PATH: /hugegraph-pd/pd_data
    ports: ["8622:8620", "8688:8686"]
    volumes: [hg-pd2-data:/hugegraph-pd/pd_data]

  # --- Store cluster (3 nodes) ---
  store0:
    <<: *store-common
    container_name: hg-store0
    hostname: store0
    environment:
      HG_STORE_PD_ADDRESS: pd0:8686,pd1:8686,pd2:8686
      HG_STORE_GRPC_HOST: store0
      HG_STORE_GRPC_PORT: "8500"
      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"]
    volumes: [hg-store0-data:/hugegraph-store/storage]

  store1:
    <<: *store-common
    container_name: hg-store1
    hostname: store1
    environment:
      HG_STORE_PD_ADDRESS: pd0:8686,pd1:8686,pd2:8686
      HG_STORE_GRPC_HOST: store1
      HG_STORE_GRPC_PORT: "8500"
      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"]
    volumes: [hg-store1-data:/hugegraph-store/storage]

  store2:
    <<: *store-common
    container_name: hg-store2
    hostname: store2
    environment:
      HG_STORE_PD_ADDRESS: pd0:8686,pd1:8686,pd2:8686
      HG_STORE_GRPC_HOST: store2
      HG_STORE_GRPC_PORT: "8500"
      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"]
    volumes: [hg-store2-data:/hugegraph-store/storage]

  # --- Server cluster (3 nodes) ---
  server0:
    <<: *server-common
    container_name: hg-server0
    hostname: server0
    ports: ["8080:8080"]

  server1:
    <<: *server-common
    container_name: hg-server1
    hostname: server1
    ports: ["8081:8080"]

  server2:
    <<: *server-common
    container_name: hg-server2
    hostname: server2
    ports: ["8082:8080"]

networks:
  hg-net:
    driver: bridge

volumes:
  hg-pd0-data:
  hg-pd1-data:
  hg-pd2-data:
  hg-store0-data:
  hg-store1-data:
  hg-store2-data:

---

7. Entrypoint Mapping Scripts

Each entrypoint follows the same pattern:

1. Hard-fail on deprecated env vars → exit with migration hint
2. Require mandatory vars → fail-fast if missing
3. Default optional vars
4. Map HG_* → SPRING_APPLICATION_JSON (or properties file for Server)
5. Log all effective config values
6. Start the service

📄 7.1 PD Entrypoint — hugegraph-pd/hg-pd-dist/docker/docker-entrypoint.sh

#!/bin/bash
set -euo pipefail

log() { echo "[hugegraph-pd-entrypoint] $*"; }

fail_on_deprecated() {
    local old_name="$1" new_name="$2"
    if [[ -n "${!old_name:-}" ]]; then
        echo "ERROR: deprecated env '${old_name}' detected. Use '${new_name}' instead." >&2
        exit 2
    fi
}

require_env() {
    local name="$1"
    if [[ -z "${!name:-}" ]]; then
        echo "ERROR: missing required env '${name}'" >&2; exit 2
    fi
}

json_escape() {
    local s="$1"
    s=${s//\\/\\\\}; s=${s//\"/\\\"}; s=${s//$'\n'/}
    printf "%s" "$s"
}

# ── Guard deprecated vars ─────────────────────────────────────────────
fail_on_deprecated "GRPC_HOST"               "HG_PD_GRPC_HOST"
fail_on_deprecated "RAFT_ADDRESS"            "HG_PD_RAFT_ADDRESS"
fail_on_deprecated "RAFT_PEERS"              "HG_PD_RAFT_PEERS_LIST"
fail_on_deprecated "PD_INITIAL_STORE_LIST"   "HG_PD_INITIAL_STORE_LIST"

# ── Required vars ─────────────────────────────────────────────────────
require_env "HG_PD_GRPC_HOST"
require_env "HG_PD_RAFT_ADDRESS"
require_env "HG_PD_RAFT_PEERS_LIST"
require_env "HG_PD_INITIAL_STORE_LIST"

# ── Defaults ──────────────────────────────────────────────────────────
: "${HG_PD_GRPC_PORT:=8686}"
: "${HG_PD_REST_PORT:=8620}"
: "${HG_PD_DATA_PATH:=/hugegraph-pd/pd_data}"

# ── Build SPRING_APPLICATION_JSON ─────────────────────────────────────
SPRING_APPLICATION_JSON="$(cat <<JSON
{
  "grpc":   { "host": "$(json_escape "${HG_PD_GRPC_HOST}")",
              "port": "$(json_escape "${HG_PD_GRPC_PORT}")" },
  "server": { "port": "$(json_escape "${HG_PD_REST_PORT}")" },
  "raft":   { "address":    "$(json_escape "${HG_PD_RAFT_ADDRESS}")",
              "peers-list": "$(json_escape "${HG_PD_RAFT_PEERS_LIST}")" },
  "pd":     { "data-path":          "$(json_escape "${HG_PD_DATA_PATH}")",
              "initial-store-list": "$(json_escape "${HG_PD_INITIAL_STORE_LIST}")" }
}
JSON
)"
export SPRING_APPLICATION_JSON

log "effective config:"
log "  grpc.host=${HG_PD_GRPC_HOST}"
log "  grpc.port=${HG_PD_GRPC_PORT}"
log "  server.port=${HG_PD_REST_PORT}"
log "  raft.address=${HG_PD_RAFT_ADDRESS}"
log "  raft.peers-list=${HG_PD_RAFT_PEERS_LIST}"
log "  pd.initial-store-list=${HG_PD_INITIAL_STORE_LIST}"
log "  pd.data-path=${HG_PD_DATA_PATH}"

./bin/start-hugegraph-pd.sh -j "${JAVA_OPTS:-}"
tail -f /dev/null

📄 7.2 Store Entrypoint — hugegraph-store/hg-store-dist/docker/docker-entrypoint.sh

#!/bin/bash
set -euo pipefail

log() { echo "[hugegraph-store-entrypoint] $*"; }

fail_on_deprecated() {
    local old_name="$1" new_name="$2"
    if [[ -n "${!old_name:-}" ]]; then
        echo "ERROR: deprecated env '${old_name}' detected. Use '${new_name}' instead." >&2
        exit 2
    fi
}

require_env() {
    local name="$1"
    if [[ -z "${!name:-}" ]]; then
        echo "ERROR: missing required env '${name}'" >&2; exit 2
    fi
}

json_escape() {
    local s="$1"
    s=${s//\\/\\\\}; s=${s//\"/\\\"}; s=${s//$'\n'/}
    printf "%s" "$s"
}

# ── Guard deprecated vars ─────────────────────────────────────────────
fail_on_deprecated "PD_ADDRESS"   "HG_STORE_PD_ADDRESS"
fail_on_deprecated "GRPC_HOST"    "HG_STORE_GRPC_HOST"
fail_on_deprecated "RAFT_ADDRESS" "HG_STORE_RAFT_ADDRESS"
fail_on_deprecated "RAFT_PEERS"   "HG_PD_RAFT_PEERS_LIST"

# ── Required vars ─────────────────────────────────────────────────────
require_env "HG_STORE_PD_ADDRESS"
require_env "HG_STORE_GRPC_HOST"
require_env "HG_STORE_RAFT_ADDRESS"

# ── Defaults ──────────────────────────────────────────────────────────
: "${HG_STORE_GRPC_PORT:=8500}"
: "${HG_STORE_REST_PORT:=8520}"
: "${HG_STORE_DATA_PATH:=/hugegraph-store/storage}"

# ── Build SPRING_APPLICATION_JSON ─────────────────────────────────────
SPRING_APPLICATION_JSON="$(cat <<JSON
{
  "pdserver": { "address": "$(json_escape "${HG_STORE_PD_ADDRESS}")" },
  "grpc":     { "host": "$(json_escape "${HG_STORE_GRPC_HOST}")",
                "port": "$(json_escape "${HG_STORE_GRPC_PORT}")" },
  "raft":     { "address": "$(json_escape "${HG_STORE_RAFT_ADDRESS}")" },
  "server":   { "port": "$(json_escape "${HG_STORE_REST_PORT}")" },
  "app":      { "data-path": "$(json_escape "${HG_STORE_DATA_PATH}")" }
}
JSON
)"
export SPRING_APPLICATION_JSON

log "effective config:"
log "  pdserver.address=${HG_STORE_PD_ADDRESS}"
log "  grpc.host=${HG_STORE_GRPC_HOST}"
log "  grpc.port=${HG_STORE_GRPC_PORT}"
log "  raft.address=${HG_STORE_RAFT_ADDRESS}"
log "  server.port=${HG_STORE_REST_PORT}"
log "  app.data-path=${HG_STORE_DATA_PATH}"

./bin/start-hugegraph-store.sh -j "${JAVA_OPTS:-}"
tail -f /dev/null

📄 7.3 Server Entrypoint — hugegraph-server/hugegraph-dist/docker/docker-entrypoint.sh

#!/bin/bash
set -euo pipefail

DOCKER_FOLDER="./docker"
INIT_FLAG_FILE="init_complete"
GRAPH_CONF="./conf/graphs/hugegraph.properties"

mkdir -p "${DOCKER_FOLDER}"

log() { echo "[hugegraph-server-entrypoint] $*"; }

fail_on_deprecated() {
    local old_name="$1" new_name="$2"
    if [[ -n "${!old_name:-}" ]]; then
        echo "ERROR: deprecated env '${old_name}' detected. Use '${new_name}' instead." >&2
        exit 2
    fi
}

set_prop() {
    local key="$1" val="$2" file="$3"
    if grep -q -E "^[[:space:]]*${key}[[:space:]]*=" "${file}"; then
        sed -ri "s#^([[:space:]]*${key}[[:space:]]*=).*#\\1${val}#" "${file}"
    else
        echo "${key}=${val}" >> "${file}"
    fi
}

# ── Guard deprecated vars ─────────────────────────────────────────────
fail_on_deprecated "BACKEND"  "HG_SERVER_BACKEND"
fail_on_deprecated "PD_PEERS" "HG_SERVER_PD_PEERS"

# ── Map env → properties file ─────────────────────────────────────────
[[ -n "${HG_SERVER_BACKEND:-}"  ]] && set_prop "backend"  "${HG_SERVER_BACKEND}"  "${GRAPH_CONF}"
[[ -n "${HG_SERVER_PD_PEERS:-}" ]] && set_prop "pd.peers" "${HG_SERVER_PD_PEERS}" "${GRAPH_CONF}"

# ── Build wait-storage env ─────────────────────────────────────────────
WAIT_ENV=()
[[ -n "${HG_SERVER_BACKEND:-}"  ]] && WAIT_ENV+=("hugegraph.backend=${HG_SERVER_BACKEND}")
[[ -n "${HG_SERVER_PD_PEERS:-}" ]] && WAIT_ENV+=("hugegraph.pd.peers=${HG_SERVER_PD_PEERS}")

# ── Init store (once) ─────────────────────────────────────────────────
if [[ ! -f "${DOCKER_FOLDER}/${INIT_FLAG_FILE}" ]]; then
    if (( ${#WAIT_ENV[@]} > 0 )); then
        env "${WAIT_ENV[@]}" ./bin/wait-storage.sh
    else
        ./bin/wait-storage.sh
    fi

    if [[ -z "${PASSWORD:-}" ]]; then
        log "init hugegraph with non-auth mode"
        ./bin/init-store.sh
    else
        log "init hugegraph with auth mode"
        ./bin/enable-auth.sh
        echo "${PASSWORD}" | ./bin/init-store.sh
    fi
    touch "${DOCKER_FOLDER}/${INIT_FLAG_FILE}"
else
    log "HugeGraph initialization already done. Skipping re-init..."
fi

./bin/start-hugegraph.sh -j "${JAVA_OPTS:-}"
tail -f /dev/null

---

8. Changes Checklist

8.1 Compose Files

• Replace network_mode: host → bridge networking
• Add explicit port mappings and health checks
• Replace per-node static config mounts → HG_* env mappings
• Use YAML anchors in 3×3 compose for reusable templates

8.2 Entrypoints

• Add HG_* → config key mapping logic
• Add required variable checks (fail-fast)
• Add deprecated variable hard-fail
• Print effective startup config for troubleshooting

8.3 Documentation Sync

Update these files to remove deprecated env naming:

File	Lines to update
hugegraph-store/README.md	L361
hugegraph-store/docs/deployment-guide.md	L687-689, L726-728, L889-893
hugegraph-pd/README.md	(if legacy aliases shown)
Root README.md / docker docs	(if legacy aliases appear)

---

9. Verification Matrix

9.1 Local / Manual

# ── Single-node ──
docker compose -f docker/docker-compose.yml config
docker compose -f docker/docker-compose.yml up -d

curl -fsS http://localhost:8620/v1/health   # PD
curl -fsS http://localhost:8520/v1/health   # Store
curl -fsS http://localhost:8080/versions    # Server

# ── 3×3 cluster ──
docker compose -f docker/docker-compose-3pd-3store-3server.yml config
docker compose -f docker/docker-compose-3pd-3store-3server.yml up -d

# Verify all 9 containers healthy
# Verify server nodes reach PD cluster via HG_SERVER_PD_PEERS

9.2 CI Expectations

Platform	Requirement
Linux	Mandatory docker compose smoke checks
macOS	Mandatory compose smoke checks (if runner supports Docker)
Fallback	If macOS Docker runner unavailable: manual gate + publish logs

---

10. Migration Notice (PR Template)

This PR introduces a strict Docker env contract using HG_* variables.

Legacy variables are REMOVED and no longer supported:
  PD_ADDRESS / GRPC_HOST / RAFT_ADDRESS / RAFT_PEERS

Please migrate to:
  HG_PD_*  ·  HG_STORE_*  ·  HG_SERVER_*

Startup now fails fast if deprecated variables are detected.

---

11. Reviewer Checklist

• Compose files no longer use network_mode: host
• Core discovery/network keys are set via explicit HG_* env vars
• Entrypoints hard-fail on deprecated env names
• Entrypoints print effective config values before startup
• No bulk duplicated conf directories for node-specific overrides
• README and deployment guides match the new contract
• Linux + macOS verification evidence attached

---

12. Non-Goals

• Does not alter HugeGraph Java public APIs
• Does not redesign cluster semantics or consistency logic
• Focuses solely on Docker deployment clarity, portability, and maintainability

[bitflicker64]

Understood. I’ll go through the plan doc. Thanks for sharing this for reference.

[bitflicker64]

Also, please base the compose changes on the current master branch, not on old 1.5.0-era config files. Master already includes several recent fixes that affect practical usability (startup/config behavior), and continuing from older code can introduce avoidable drift.

PR is based on master branch (miscommunication in issue description).

[bitflicker64]

@imbajin Happy Lunar New Year! Wishing you a great Year of the Fire Horse. 🐎✨