Deploying on Docker
In this deployment guide, you will learn how to form a cluster from Hazelcast member containers running on more than one Docker host in the same local area network (LAN).
Starting a Cluster
The default network mode in Docker is bridge. In this mode, all containers run in a single network that is not accessible outside of the Docker host. If you run member Docker containers on different hosts, you must allow them to discover and connect to each other using one of the following methods:
-
Host network mode (Linux only)
-
Port mapping
These methods open Hazelcast members to the public. Anybody who can reach the Docker host over the network can connect to Hazelcast ports of the running members and perform actions - such as data manipulation or shutting down the members. |
Host Network Mode
To allow members and clients on different hosts to discover each other with multicast, you can use the host
network mode. This mode allows members to share the host’s network stack from their Docker containers.
Members will discover and connect to each other automatically only if your local network supports multicast. If your network does not support multicast, members will not form a cluster. In this case, you can try port mapping.
In this mode, each member is available on the internal (private) IP address of the Docker host.
Port Mapping
To allow members and clients on different hosts to discover each other over TCP/IP, you can map ports from the Docker host (the device that’s running Docker) and tell Hazelcast to listen to your internal IP address.
You’ll need the internal IP address of your Docker host. |
-
Configure your members to connect over TCP/IP.
The default configuration file in Docker containers is /opt/hazelcast/config/hazelcast-docker.xml
. If you want to use another file, you can specify the path to it relative to thehazelcast
directory, using theHAZELCAST_CONFIG
environment variable. You can see an example of this property under Custom Hazelcast Configuration File.1 Disable multicast. 2 Enable TCP/IP. 3 List the socket address of all your Docker hosts. -
Start a member on the first Docker host.
-
Start another member on the second host.
In the member logs, you should see that your members connected to each other:
Starting Management Center
Hazelcast Management Center provides an easy way to manage and monitor a Hazelcast cluster from a web page. See the Getting Started guide for more information.
Configuration
You can configure various aspects of your cluster and environment with Docker.
We recommend that you use the default configuration file as a starting point.
Memory
By default, Hazelcast configures the JVM with -XX:MaxRAMPercentage=80.0
.
This limits the JVM heap to 80% of the RAM available to the container.
We recommend you leave this as-is and control Hazelcast’s memory size with the
Docker parameter --memory
. For example, this will start Hazelcast with 1.6
GB assigned to the JVM:
JAVA_OPTS
To change the JVM parameters directly, use the JAVA_OPTS
environment
variable. Hazelcast passes it to the JVM when starting. For example:
Make sure to leave enough free RAM for metaspace and other overheads.
Custom Hazelcast Configuration File
You can configure Hazelcast with your own YAML or XML file
by replacing the default ones in the container at
/opt/hazelcast
:
Now edit the file and apply it when starting Hazelcast:
Extend Hazelcast’s CLASSPATH with Custom JARS and Files
If you have to add more classes or files to Hazelcast’s classpath, one way to
do it is to put them in a directory such as ext
, mount it to the
container, and set the CLASSPATH
environment variable:
If you have just one file to add, it’s simpler to mount it directly to the
Hazelcast lib
directory:
Changing Logging Level
You can set the logging level using the LOGGING_LEVEL
environment
variable:
Available logging levels are (from highest to lowest): FATAL
, ERROR
,
WARN
, INFO
, DEBUG
, TRACE
. The default logging level is INFO
.
If you need more control over logging, you can supply your own
log4j2.properties
file. Use the default one as the starting point:
Edit the file and mount it when starting Hazelcast:
Building a Custom Image from the Slim Image
Hazelcast offers a slim Docker image that contains only the core Hazelcast engine. When image size is a concern, you can use it as the starting point to build your custom image with just the extensions you need.
This example creates a Docker image for Hazelcast with the Kafka extension.
To build an image from a Dockerfile, use the following command, which gives the image the name hazelcast-with-kafka
:
To start a Docker container from the image:
For more information about Dockerfile, see the Docker documentation.