Skip to content

fix(docker): migrate single-node compose from host to bridge networking#2952

Open
bitflicker64 wants to merge 2 commits intoapache:masterfrom
bitflicker64:docker-fix-bridge-network
Open

fix(docker): migrate single-node compose from host to bridge networking#2952
bitflicker64 wants to merge 2 commits intoapache:masterfrom
bitflicker64:docker-fix-bridge-network

Conversation

@bitflicker64
Copy link
Contributor

Purpose of the PR

Fix single node Docker deployment failing on macOS and Windows due to Linux only host networking.

close #2951

Main Changes

  • Remove network_mode host from single node docker compose setup

  • Use default bridge networking

  • Add explicit port mappings

    • 8080 Server HTTP
    • 8520 Store HTTP
    • 8620 PD HTTP
  • Add configuration volume mounts

    • docker pd-conf
    • docker store-conf
    • docker server-conf
  • Replace localhost and non routable addresses with container hostnames

    • PD grpc host set to pd
    • Store grpc host set to store
    • Server pd peers set to pd 8686
  • Update healthcheck endpoints

Problem

The original single node Docker configuration uses network_mode host.

This only works on native Linux. Docker Desktop on macOS and Windows does not implement host networking the same way. Containers start but HugeGraph services advertise incorrect addresses such as 127.0.0.1 or 0.0.0.0.

Resulting failures:

  • Server stuck in loop waiting for storage backend
  • PD client UNAVAILABLE io exception errors
  • Store reports zero partitions
  • Cluster never becomes usable even though containers are running

The issue is not process failure but invalid service discovery and advertised endpoints.

Root Cause

  • network_mode host is Linux specific
  • Docker Desktop falls back to bridge networking
  • HugeGraph components still advertise localhost style addresses
  • Other containers cannot route to those addresses

Solution

Switch to bridge networking and advertise container resolvable hostnames.

Docker DNS resolves service names automatically. Services bind normally while exposing correct internal endpoints.

Verification

Observed behavior after changes on Docker Desktop macOS:

Container state

docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

server   Up healthy   0.0.0.0:8080->8080
store    Up healthy   0.0.0.0:8520->8520
pd       Up healthy   0.0.0.0:8620->8620

Server startup sequence

Hugegraph server are waiting for storage backend
Initializing HugeGraph Store
Starting HugeGraphServer ... OK
Started

Endpoints

Server:

curl http://localhost:8080

Returns service metadata.

Store:

curl http://localhost:8520

Returns non zero leader and partition count:

{"leaderCount":12,"partitionCount":12}

PD:

curl http://localhost:8620

Returns expected auth response, confirming service availability.

Cluster becomes operational after initialization delay.

Why This Works

  • Bridge networking is cross platform
  • Container names become stable service addresses
  • No platform dependent networking behavior
  • Services advertise routable endpoints

Does this PR potentially affect the following parts

  • Modify configurations
  • Dependencies
  • The public API
  • Other affects
  • Nope

Documentation Status

  • Doc No Need

Replace network_mode: host with explicit port mappings and add configuration
volumes for PD, Store, and Server services to support macOS/Windows Docker.

- Remove host network mode from all services
- Add explicit port mappings (8620, 8520, 8080)
- Add configuration directories with volume mounts
- Update healthcheck endpoints
- Add PD peers environment variable

Enables HugeGraph cluster to run on all Docker platforms.
@dosubot dosubot bot added size:XL This PR changes 500-999 lines, ignoring generated files. pd PD module store Store module labels Feb 15, 2026
@dosubot dosubot bot added size:XXL This PR changes 1000+ lines, ignoring generated files. and removed size:XL This PR changes 500-999 lines, ignoring generated files. labels Feb 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

pd PD module size:XXL This PR changes 1000+ lines, ignoring generated files. store Store module

Projects

Status: In progress

Development

Successfully merging this pull request may close these issues.

[Bug] Single node Docker setup does not work on macOS and Windows because of host networking

1 participant