Copilot commented on code in PR #2963: URL: https://github.com/apache/hugegraph/pull/2963#discussion_r2970049480
########## docker/README.md: ########## @@ -0,0 +1,259 @@ +# 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 +``` Review Comment: This command uses `-f docker-compose-dev.yml`, but the repo’s dev compose file is `docker-compose.dev.yml`. Update the command (or rename the file) so users can run it as written. ########## AGENTS.md: ########## @@ -231,7 +231,7 @@ For distributed development: 3. Build Store: `mvn clean package -pl hugegraph-store -am -DskipTests` 4. Build Server with HStore backend: `mvn clean package -pl hugegraph-server -am -DskipTests` -See Docker Compose example: `hugegraph-server/hugegraph-dist/docker/example/` +See Docker Compose examples: `docker/` directory. Single-node quickstart (pre-built images): `docker/docker-compose.yml`. Single-node dev build (from source): `docker/docker-compose-dev.yml`. 3-node cluster: `docker/docker-compose-3pd-3store-3server.yml`. See `docker/README.md` for full setup guide. Review Comment: This references `docker/docker-compose-dev.yml`, but the compose file in the repo is `docker/docker-compose.dev.yml`. Update the filename (or rename the compose file) to avoid a broken path in the docs. ```suggestion See Docker Compose examples: `docker/` directory. Single-node quickstart (pre-built images): `docker/docker-compose.yml`. Single-node dev build (from source): `docker/docker-compose.dev.yml`. 3-node cluster: `docker/docker-compose-3pd-3store-3server.yml`. See `docker/README.md` for full setup guide. ``` ########## hugegraph-store/docs/deployment-guide.md: ########## @@ -672,163 +672,73 @@ curl http://localhost:8080/versions ### Docker Compose: Complete Cluster -File: `docker-compose.yml` +For a production-like 3-node distributed deployment, use the compose file at `docker/docker-compose-3pd-3store-3server.yml` in the repository root. See [docker/README.md](../../docker/README.md) for the full setup guide. + +> **Prerequisites**: Allocate at least **12 GB** memory to Docker Desktop (Settings → Resources → Memory). The cluster runs 9 JVM processes. + +```bash +cd docker +docker compose -f docker-compose-3pd-3store-3server.yml up -d +``` + +The compose file uses a Docker bridge network (`hg-net`) with container hostnames for service discovery. Configuration is injected via environment variables using the `HG_*` prefix: + +**PD environment variables** (per node): + +```yaml +environment: + HG_PD_GRPC_HOST: pd0 # maps to grpc.host + HG_PD_GRPC_PORT: "8686" # maps to grpc.port + HG_PD_REST_PORT: "8620" # maps to server.port + HG_PD_RAFT_ADDRESS: pd0:8610 # maps to raft.address + HG_PD_RAFT_PEERS_LIST: pd0:8610,pd1:8610,pd2:8610 # maps to raft.peers-list + HG_PD_INITIAL_STORE_LIST: store0:8500,store1:8500,store2:8500 # maps to pd.initial-store-list + HG_PD_DATA_PATH: /hugegraph-pd/pd_data # maps to pd.data-path + HG_PD_INITIAL_STORE_COUNT: 3 # maps to pd.initial-store-count +``` + +**Store environment variables** (per node): + +```yaml +environment: + HG_STORE_PD_ADDRESS: pd0:8686,pd1:8686,pd2:8686 # maps to pdserver.address + HG_STORE_GRPC_HOST: store0 # maps to grpc.host + HG_STORE_GRPC_PORT: "8500" # maps to grpc.port + HG_STORE_REST_PORT: "8520" # maps to server.port + HG_STORE_RAFT_ADDRESS: store0:8510 # maps to raft.address + HG_STORE_DATA_PATH: /hugegraph-store/storage # maps to app.data-path +``` + +**Server environment variables**: ```yaml -version: '3.8' - -services: - # PD Cluster (3 nodes) - pd1: - image: hugegraph/hugegraph-pd:1.7.0 - container_name: hugegraph-pd1 - ports: - - "8686:8686" - - "8620:8620" - - "8610:8610" - environment: - - GRPC_HOST=pd1 - - RAFT_ADDRESS=pd1:8610 - - RAFT_PEERS=pd1:8610,pd2:8610,pd3:8610 - networks: - - hugegraph-net - - pd2: - image: hugegraph/hugegraph-pd:1.7.0 - container_name: hugegraph-pd2 - ports: - - "8687:8686" - environment: - - GRPC_HOST=pd2 - - RAFT_ADDRESS=pd2:8610 - - RAFT_PEERS=pd1:8610,pd2:8610,pd3:8610 - networks: - - hugegraph-net - - pd3: - image: hugegraph/hugegraph-pd:1.7.0 - container_name: hugegraph-pd3 - ports: - - "8688:8686" - environment: - - GRPC_HOST=pd3 - - RAFT_ADDRESS=pd3:8610 - - RAFT_PEERS=pd1:8610,pd2:8610,pd3:8610 - networks: - - hugegraph-net - - # Store Cluster (3 nodes) - store1: - image: hugegraph/hugegraph-store:1.7.0 - container_name: hugegraph-store1 - ports: - - "8500:8500" - - "8510:8510" - - "8520:8520" - environment: - - PD_ADDRESS=pd1:8686,pd2:8686,pd3:8686 - - GRPC_HOST=store1 - - RAFT_ADDRESS=store1:8510 - volumes: - - store1-data:/hugegraph-store/storage - depends_on: - - pd1 - - pd2 - - pd3 - networks: - - hugegraph-net - - store2: - image: hugegraph/hugegraph-store:1.7.0 - container_name: hugegraph-store2 - ports: - - "8501:8500" - environment: - - PD_ADDRESS=pd1:8686,pd2:8686,pd3:8686 - - GRPC_HOST=store2 - - RAFT_ADDRESS=store2:8510 - volumes: - - store2-data:/hugegraph-store/storage - depends_on: - - pd1 - - pd2 - - pd3 - networks: - - hugegraph-net - - store3: - image: hugegraph/hugegraph-store:1.7.0 - container_name: hugegraph-store3 - ports: - - "8502:8500" - environment: - - PD_ADDRESS=pd1:8686,pd2:8686,pd3:8686 - - GRPC_HOST=store3 - - RAFT_ADDRESS=store3:8510 - volumes: - - store3-data:/hugegraph-store/storage - depends_on: - - pd1 - - pd2 - - pd3 - networks: - - hugegraph-net - - # Server (2 nodes) - server1: - image: hugegraph/hugegraph:1.7.0 - container_name: hugegraph-server1 - ports: - - "8080:8080" - environment: - - BACKEND=hstore - - PD_PEERS=pd1:8686,pd2:8686,pd3:8686 - depends_on: - - store1 - - store2 - - store3 - networks: - - hugegraph-net - - server2: - image: hugegraph/hugegraph:1.7.0 - container_name: hugegraph-server2 - ports: - - "8081:8080" - environment: - - BACKEND=hstore - - PD_PEERS=pd1:8686,pd2:8686,pd3:8686 - depends_on: - - store1 - - store2 - - store3 - networks: - - hugegraph-net - -networks: - hugegraph-net: - driver: bridge - -volumes: - store1-data: - store2-data: - store3-data: +environment: + HG_SERVER_BACKEND: hstore # maps to backend + HG_SERVER_PD_PEERS: pd0:8686,pd1:8686,pd2:8686 # maps to pd.peers + STORE_REST: store0:8520 # used by wait-partition.sh ``` +**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 + +> **Note**: The deprecated env var names (`GRPC_HOST`, `RAFT_ADDRESS`, `RAFT_PEERS`, `PD_ADDRESS`, `BACKEND`, `PD_PEERS`) still work but log a warning. Use the `HG_*` prefixed names for new deployments. + **Deploy**: ```bash # Start cluster -docker-compose up -d +docker compose up -d # Check status -docker-compose ps +docker compose ps # View logs -docker-compose logs -f store1 +docker compose logs -f store1 # Stop cluster -docker-compose down +docker compose down ``` Review Comment: The “Deploy” commands drop the `-f docker-compose-3pd-3store-3server.yml` flag, so `docker compose up/ps/logs/down` will operate on `docker-compose.yml` (single-node) instead of the 3-node cluster file. Keep the `-f` flag for all subsequent compose commands (or instruct users to set `COMPOSE_FILE`). ########## hugegraph-server/hugegraph-dist/docker/README.md: ########## @@ -105,12 +104,27 @@ If you want to customize the preloaded data, please mount the groovy scripts (no 3. Stop Open-Telemetry-Collector ```bash - cd hugegraph-server/hugegraph-dist/docker/example - docker-compose -f docker-compose-trace.yaml -p hugegraph-trace stop + docker compose -f hugegraph-server/hugegraph-dist/docker/example/docker-compose-trace.yaml -p hugegraph-trace stop ``` Review Comment: These commands reference the compose file via a long relative path (`-f hugegraph-server/.../docker-compose-trace.yaml`) but the README doesn’t specify the expected working directory. Consider restoring the `cd hugegraph-server/hugegraph-dist/docker/example` step (or adjust the `-f` path) so the commands work when run from this README’s directory as well as from the repo root. ########## docker/README.md: ########## @@ -0,0 +1,259 @@ +# 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) | Review Comment: `docker-compose-dev.yml` is referenced here, but the repository contains `docker/docker-compose.dev.yml` (dot, not dash). Either rename the file or update these references so the documented commands match the actual compose file name. ```suggestion | `docker-compose.dev.yml` | Single-node cluster built from source (for developers) | ``` ########## hugegraph-store/AGENTS.md: ########## @@ -129,7 +129,7 @@ bin/restart-hugegraph-store.sh 2. HugeGraph Store cluster (3+ nodes) 3. Proper configuration pointing Store nodes to PD cluster -See Docker Compose example: `hugegraph-server/hugegraph-dist/docker/example/` +See Docker Compose examples in the repository root `../docker/` directory. Single-node quickstart (pre-built images): `../docker/docker-compose.yml`. Single-node dev build (from source): `../docker/docker-compose-dev.yml`. 3-node cluster: `../docker/docker-compose-3pd-3store-3server.yml`. See `../docker/README.md` for the full setup guide. Review Comment: This references `../docker/docker-compose-dev.yml`, but the compose file in the repo is `docker/docker-compose.dev.yml`. Update the filename (or rename the compose file) to avoid a broken path in the docs. ```suggestion See Docker Compose examples in the repository root `../docker/` directory. Single-node quickstart (pre-built images): `../docker/docker-compose.yml`. Single-node dev build (from source): `../docker/docker-compose.dev.yml`. 3-node cluster: `../docker/docker-compose-3pd-3store-3server.yml`. See `../docker/README.md` for the full setup guide. ``` -- 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]
