imbajin commented on code in PR #2963: URL: https://github.com/apache/hugegraph/pull/2963#discussion_r2970712675
########## docker/README.md: ########## @@ -0,0 +1,263 @@ +# HugeGraph Docker Deployment + +This directory contains Docker Compose files for running HugeGraph: + +| File | Description | +|------|-------------| +| `docker-compose.yml` | Single-node cluster using pre-built images from Docker Hub | +| `docker-compose.dev.yml` | Single-node cluster built from source (for developers) | +| `docker-compose-3pd-3store-3server.yml` | 3-node distributed cluster (PD + Store + Server) | + +## Prerequisites + +- **Docker Engine** 20.10+ (or Docker Desktop 4.x+) +- **Docker Compose** v2 (included in Docker Desktop) +- **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. + +> [!IMPORTANT] +> The 12 GB minimum is for Docker Desktop (Mac/Windows). On Linux with native Docker, ensure the host has at least 12 GB of free memory. + +## Why Bridge Networking (Not Host Mode) + +Previous versions used `network_mode: host`, which only works on Linux and is incompatible with Docker Desktop on Mac/Windows. The cluster now uses a proper Docker bridge network (`hg-net`) where services communicate via container hostnames (`pd0`, `pd1`, `store0`, etc.) instead of `127.0.0.1`. This makes the cluster portable across all platforms. + +--- + +## Single-Node Setup + +Two compose files are available for running a single-node cluster (1 PD + 1 Store + 1 Server): + +### Option A: Quick Start (pre-built images) + +Uses pre-built images from Docker Hub. Best for **end users** who want to run HugeGraph quickly. + +```bash +cd docker +docker compose up -d +``` + +- Images: `hugegraph/pd:latest`, `hugegraph/store:latest`, `hugegraph/server:latest` +- `pull_policy: always` — always pulls the latest image +- PD healthcheck endpoint: `/v1/health` +- Single PD, single Store (`HG_PD_INITIAL_STORE_LIST: store:8500`), single Server +- Server healthcheck endpoint: `/versions` + +### Option B: Development Build (build from source) + +Builds images locally from source Dockerfiles. Best for **developers** who want to test local changes. + +```bash +cd docker +docker compose -f docker-compose.dev.yml up -d +``` + +- Images: built from source via `build: context: ..` with Dockerfiles +- No `pull_policy` — builds locally, doesn't pull +- Entrypoint scripts are baked into the built image (no volume mounts) +- PD healthcheck endpoint: `/v1/health` +- Otherwise identical env vars and structure to the quickstart file + +### 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 | +| **pull_policy** | `always` | not set (build) | + +**Verify** (both options): +```bash +curl http://localhost:8080/versions +``` + +--- + +## 3-Node Cluster Quickstart + +```bash +cd docker +docker compose -f docker-compose-3pd-3store-3server.yml up -d + +# To stop and remove all data volumes (clean restart) +docker compose -f docker-compose-3pd-3store-3server.yml down -v +``` + +**Startup ordering** is enforced via `depends_on` with `condition: service_healthy`: + +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 + +This ensures Raft leader election and partition assignment complete before dependent services attempt connections. Review Comment: ⚠️ `depends_on` only gates container startup on the healthcheck, and the server still runs `wait-partition.sh` after it comes up. The current sentence promises stronger ordering than the compose file enforces, so I would soften it. ```suggestion 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. ``` ########## hugegraph-pd/AGENTS.md: ########## @@ -331,7 +331,7 @@ docker run -d -p 8620:8620 -p 8686:8686 -p 8610:8610 \ hugegraph-pd:latest # For production clusters, use Docker Compose or Kubernetes -# See: hugegraph-server/hugegraph-dist/docker/example/ +# See: docker/docker-compose-3pd-3store-3server.yml and docker/README.md Review Comment: 🧹 This file is under `hugegraph-pd/`, so `docker/...` points at a non-existent `hugegraph-pd/docker/...` path. Please change these references to `../docker/...` so future agents do not follow a dead link. ```suggestion # See: ../docker/docker-compose-3pd-3store-3server.yml and ../docker/README.md ``` -- 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]
