Recommended Free Tools
To scale Hazelcast with Docker Compose, run multiple Hazelcast members on the same user-defined Compose network and give every member the same cluster name. For a local cluster, you can scale a service that does not publish a fixed host port; if you need to connect from outside Docker, define members separately and map each one to a different host port. Keep member ports private unless access is required, and treat a multi-member cluster on one Docker host as a test setup—not production fault isolation.
Choose how to run the members
There are two practical single-host patterns. Use Compose replicas for a cluster that clients reach only from containers on the same network. Use separate Compose services when you need distinct host port mappings or want each member to be easy to identify. A fixed host port cannot be published by every replica of the same service: the replicas would compete for that host port.
| Pattern | Discovery and access | Failure-domain separation | Operational complexity | Best fit |
|---|---|---|---|---|
| Scaled Compose service | Members share a Compose network; do not publish one fixed host port for every replica. | All members remain on one Docker host. | Lowest for a local cluster. | Development, testing, or container-only access. |
| Separate Compose services | Members share a Compose network; each can have a distinct host port. | All members remain on one Docker host. | More service definitions and port assignments. | Testing host-level client access or an explicitly mapped local topology. |
| Multi-host Docker deployment | Requires reachable advertised addresses and explicit discovery and port planning. | Can span hosts if deployed and operated that way. | Higher; routing and firewall rules matter. | Docker deployments that need members on different hosts. |
| Kubernetes | Uses Kubernetes networking and an environment-appropriate discovery setup. | Depends on the cluster and its placement configuration. | A separate orchestration path. | Deployments designed around Kubernetes, not a copy of local Compose networking. |
Scale a cluster for container-only access
The following Compose file puts the members on a user-defined bridge network and leaves the Hazelcast member port unpublished to the host. The official Hazelcast Docker tutorial for version 5.7.0 uses the hazelcast/hazelcast:5.7.0 image and the HZ_CLUSTERNAME environment variable.
services:
hazelcast:
image: hazelcast/hazelcast:5.7.0
environment:
HZ_CLUSTERNAME: compose-cluster
networks:
- hz
networks:
hz:
driver: bridgeSave the file as compose.yaml, then start three members:
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problems#1 Best Overall
docker compose up -d --scale hazelcast=3All replicas inherit the same cluster name and join the same Compose network. Hazelcast’s local Docker tutorial describes members on that shared network discovering and connecting to one another. The member port is available to containers on the network, but this configuration does not publish it as a host port.
Publish distinct host ports when outside clients need access
If a client running on the Docker host must connect directly to individual members, use separate services so each member can map container port 5701 to a different host port. Hazelcast’s three-member tutorial uses host ports 5701, 5702, and 5703 for this pattern.
services:
member1:
image: hazelcast/hazelcast:5.7.0
environment:
HZ_CLUSTERNAME: compose-cluster
ports:
- "5701:5701"
networks:
- hz
member2:
image: hazelcast/hazelcast:5.7.0
environment:
HZ_CLUSTERNAME: compose-cluster
ports:
- "5702:5701"
networks:
- hz
member3:
image: hazelcast/hazelcast:5.7.0
environment:
HZ_CLUSTERNAME: compose-cluster
ports:
- "5703:5701"
networks:
- hz
networks:
hz:
driver: bridgeStart the services with docker compose up -d. The host-side ports must be unique, even though each container listens on port 5701. For clients in other containers on the same Compose network, use the appropriate service name and container port; host-published ports are for access through the Docker host.
Set the address other members or clients should use
A member’s container address is not always reachable from outside its Docker network. In that case, set HZ_NETWORK_PUBLICADDRESS to the address and port that the intended peers or clients can actually reach. Hazelcast’s official Docker repository describes a custom public address as critical for autodiscovery in setups that need it.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Do not copy a public address from another machine or deployment. Choose an address routable from the specific peers or clients that need to use it. For a local, shared Compose network, container-to-container connectivity is the relevant path; for host or cross-host access, the advertised address must match the reachable host and port arrangement.
Verify membership and rebalance
- Start the members using the chosen Compose pattern.
- Inspect each container’s logs with
docker compose logs -f hazelcastfor a scaled service, or substitute a service name such asmember1for the separate-service pattern. Check that the members report the expected cluster and connect to one another. - Use Hazelcast Management Center or equivalent metrics to inspect member count, partition distribution, and backups. When members join, Hazelcast redistributes entries and creates copies on other members according to the cluster’s backup configuration.
A higher member count is not simply extra empty capacity: existing data and backup copies are distributed across the cluster as membership changes. Hazelcast’s three-member tutorial illustrates a configuration where backup memory matches entry memory; that example is specific to its described setup, not a universal sizing ratio.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Deploying members on different Docker hosts
A default Docker bridge network exists on one Docker host; it does not by itself connect Compose services across machines. Hazelcast documents host networking or port mapping as approaches for cross-host members. With port mapping, plan explicit TCP/IP discovery, disable multicast, list the Docker-host addresses, publish the member port, and configure each member’s public address so peers can reach it.
Discovery is how members find one another; after the cluster forms, Hazelcast member communication uses TCP/IP regardless of the discovery mechanism. Consequently, a discovery configuration alone is not enough: routing, published ports, advertised addresses, and firewall rules must also permit the required peer traffic.
Protect the cluster ports
Publishing a Hazelcast member port can expose a powerful interface to anyone who can reach the Docker host. Hazelcast warns that reachable members may allow data manipulation or member shutdown. Publish ports only when necessary, restrict access with host firewalls or network controls to trusted clients and peers, and avoid broad public exposure. A Compose network shared only by the required containers is preferable when host access is unnecessary.
Know when Compose is the wrong scaling boundary
Adding members within one Compose project can help test partitioning, backup behavior, and client connectivity, but all those containers still depend on one Docker host. Hazelcast explicitly characterizes multiple members on one Docker host as useful for testing, not suitable for production. For production fault isolation, use a deployment that distributes members across failure domains and follow Hazelcast’s Docker deployment or Kubernetes guidance for the chosen environment.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
