This is a prerelease version.

Start a Local Cluster in Docker

This tutorial introduces you to Hazelcast in a client/server topology. At the end of this tutorial, you’ll know how to start a cluster in Docker, store data in memory, visualize your data and more.

Before You Begin

To complete this tutorial, you need the following:

Prerequisites Useful resources

Docker

Your local IP address

Step 1. Start a Local Member

Hazelcast clusters consist of servers that we call members. These members communicate with each other to form a distributed network. It’s these members that store and process your data in memory.

In this step, you use the Hazelcast Docker image to start a local single-member cluster called hello-world.

  1. Create a new Docker network called hazelcast-network.

    docker network create hazelcast-network

    This network makes it easier for you to connect to your cluster and add other services that need to communicate with your cluster.

  2. To start a member, execute the Docker run command. Replace the $LOCAL_IP placeholder with your local IP address.

    docker run \
        -it \
        --network hazelcast-network \
        --rm \
        -e HZ_CLUSTERNAME=hello-world \
        -e HZ_NETWORK_PUBLICADDRESS=$LOCAL_IP:5701 \
        -p 5701:5701 hazelcast/hazelcast:5.0-BETA-1

    Hazelcast parameters:

    • HZ_CLUSTERNAME: Sets the name of your cluster.

    • HZ_NETWORK_PUBLICADDRESS: Sets the public IP address of the member to allow members and clients in the same local network to connect to it.

      Docker parameters:

    • -it: Starts an interactive session, allowing you to stop the member with Ctrl+C.

    • --rm: Tells Docker to remove the container from its local cache after it exits.

    • --network: Allows you to connect to clusters, using an alias.

You should see your cluster name in the console:

Platform console displays the cluster name 'hello-world'

Step 2. Write Data to Memory

Hazelcast has lots of distributed data structures available for writing data to memory on your cluster.

One of the most popular ways of writing data to memory is to use a distributed map.

Maps store key/value pairs called entries, which are replicated and distributed across a cluster.

  • SQL

  • Java

  • C++

  • C Sharp

  • Node.js

  • Python

  • Go

  1. In a new terminal window, start the SQL shell.

    Replace the $LOCAL_IP placeholder with your member’s local IP address.

    docker run --network hazelcast-network -it --rm hazelcast/hazelcast:5.0-SNAPSHOT hazelcast --targets hello-world@$LOCAL_IP sql

    The --targets parameter tells the SQL shell to connect to the member at the given IP address in a cluster called hello-world.

  2. Use the following SQL statement to create a map and add data to it.

    CREATE MAPPING myDistributedMap TYPE IMap OPTIONS ('keyFormat'='varchar','valueFormat'='varchar');
    
    SINK INTO myDistributedMap VALUES('1', 'John');
    SINK INTO myDistributedMap VALUES('2', 'Mary');
    SINK INTO myDistributedMap VALUES('3', 'Jane');
  3. Use the following command to exit the SQL shell.

    exit
  1. Install the Java client library

  2. Add the following to your file:

    import com.hazelcast.client.HazelcastClient;
    import com.hazelcast.client.config.ClientConfig;
    import com.hazelcast.core.HazelcastInstance;
    import com.hazelcast.core.IMap;
    
    public class MapSample {
      public static void main(String[] args) {
    
        ClientConfig clientConfig = new ClientConfig();
        clientConfig.setClusterName("hello-world"); (1)
        clientConfig.getNetworkConfig().addAddress("$LOCAL_IP"); (2)
    
        HazelcastInstance hz = HazelcastClient.newHazelcastClient(); (3)
        IMap map = hz.getMap("my-distributed-map"); (4)
    
        (5)
        map.put("1", "John");
        map.put("2", "Mary");
        map.put("3", "Jane");
    
        hz.shutdown(); (6)
      }
    }
    1 The name of the cluster that you want to connect to.
    2 The IP address of a member. In this tutorial, you are running the member on the same network as the client, so replace this placeholder with your member’s local IP address.
    3 Create a client instance, using your configuration.
    4 Create a map called my-distributed-map.
    5 Write some keys and values to the map.
    6 Disconnect from the member.
  1. Install the latest C++ client library

  2. Add the following to your file:

    #include <hazelcast/client/hazelcast_client.h>
    
    int main() {
      hazelcast::client::client_config config;
      config.set_cluster_name("hello-world"); (1)
      config.get_network_config().add_address(address("$LOCAL_IP")); (2)
    
      auto hz = hazelcast::new_client(std::move(config)).get(); (3)
    
      auto map = hz.get_map("my-distributed-map").get(); (4)
    
      (5)
      map->put<std::string, std::string>("1", "John").get();
      map->put<std::string, std::string>("2", "Mary").get();
      map->put<std::string, std::string>("3", "Jane").get();
    
      hz.shutdown(); (6)
    
      return 0;
    }
    1 The name of the cluster that you want to connect to.
    2 The IP address of a member. In this tutorial, you are running the member on the same network as the client, so replace this placeholder with your member’s local IP address.
    3 Create a client instance, using your configuration.
    4 Create a map called my-distributed-map.
    5 Write some keys and values to the map.
    6 Disconnect from the member.
  1. Install the latest C Sharp client library

  2. Add the following to your file:

    using Hazelcast.Client;
    
    namespace Hazelcast.Examples.Org.Website.Samples
    {
      public class MapSample
      {
        public static void Run(string[] args)
        {
          var options = new HazelcastOptionsBuilder().Build();
          options.ClusterName = "hello-world"; (1)
          options.Networking.Addresses.Add("$LOCAL_IP"); (2)
    
          var hz = await HazelcastClientFactory.StartNewClientAsync(options); (3)
    
          var map = hz.GetMap("my-distributed-map"); (4)
    
          (5)
          map.put("1", "John");
          map.put("2", "Mary");
          map.put("3", "Jane");
    
          hz.Shutdown(); (6)
        }
      }
    }
    1 The name of the cluster that you want to connect to.
    2 The IP address of a member. In this tutorial, you are running the member on the same network as the client, so replace this placeholder with your member’s local IP address.
    3 Create a client instance, using your configuration.
    4 Create a map called my-distributed-map.
    5 Write some keys and values to the map.
    6 Disconnect from the member.
  1. Install the Node.js client library.

    npm install hazelcast-client
  2. Add the following to your file:

    const { Client } = require('hazelcast-client');
    
    (async () => {
      try {
        const hz = await Client.newHazelcastClient({
          clusterName: 'hello-world', (1)
          network: {
            clusterMembers: [
              '$LOCAL_IP' (2)
            ]
          }
        }); (3)
    
        const map = await hz.getMap('my-distributed-map'); (4)
    
        (5)
        await map.put('1', 'John');
        await map.put('2', 'Mary');
        await map.put('3', 'Jane');
    
        await hz.shutdown(); (6)
    
      } catch (error) {
        console.error('Error occurred:', error);
      }
    })();
    1 The name of the cluster that you want to connect to.
    2 The IP address of a member. In this tutorial, you are running the member on the same network as the client, so replace this placeholder with your member’s local IP address.
    3 Create a client instance, using your configuration.
    4 Create a map called my-distributed-map.
    5 Write some keys and values to the map.
    6 Disconnect from the member.
  1. Install the Python client library.

    pip install hazelcast-python-client
  2. Add the following to your file:

    import hazelcast
    
    if __name__ == "__main__":
      hz = hazelcast.HazelcastClient(
      cluster_name="hello-world", (1)
      cluster_members=[
          "$LOCAL_IP", (2)
      ]) (3)
    
      # Create a Distributed Map in the cluster
      map = hz.get_map("my-distributed-map").blocking() (4)
    
      (5)
      map.put("1", "John")
      map.put("2", "Mary")
      map.put("3", "Jane")
    
      (6)
      hz.shutdown()
    1 The name of the cluster that you want to connect to.
    2 The IP address of a member. In this tutorial, you are running the member on the same network as the client, so replace this placeholder with your member’s local IP address.
    3 Create a client instance, using your configuration.
    4 Create a map called my-distributed-map.
    5 Write some keys and values to the map.
    6 Disconnect from the member.
  1. Install the Python client library.

    go get github.com/hazelcast/hazelcast-go-client
  2. Add the following to your file:

    import "github.com/hazelcast/hazelcast-go-client"
    
    func mapSampleRun() {
      cb := hazelcast.NewConfigBuilder()
    
      cb.Cluster().SetName("hello-world"). (1)
      SetAddrs("$LOCAL_IP") (2)
    
      hz, err := hazelcast.StartNewClientWithConfig(cb) (3)
    
    	mp, _ := hz.GetMap("my-distributed-map") (4)
    
      (5)
    	mp.Put("1", "John")
    	mp.Put("2", "Mary")
    	mp.Put("3", "Jane")
    
    	hz.Shutdown() (6)
    }
    1 The name of the cluster that you want to connect to.
    2 The IP address of a member. In this tutorial, you are running the member on the same network as the client, so replace this placeholder with your member’s local IP address.
    3 Create a client instance, using your configuration.
    4 Create a map called my-distributed-map.
    5 Write some keys and values to the map.
    6 Disconnect from the member.
The configuration builder is not thread-safe. Complete the configuration in a single go routine. Do not pass the builder to other go routines without synchronizing them.

Step 3. Set up Management Center

Management Center is a user interface for managing and monitoring your cluster.

In this step, you start a local instance of Management Center and use it to view your cluster’s statistics.

  1. Start Management Center. Replace the $LOCAL_IP placeholder with your local IP address.

    docker run \
        -e HZ_CLUSTERNAME=hello-world -e HZ_NETWORK_PUBLICADDRESS=$LOCAL_IP:5701 \
        -p 8080:8080 hazelcast/management-center:latest-snapshot
  2. In a web browser, go to localhost:8080 and enable dev mode.

    Enabling dev mode in Management center

  3. Enter your cluster name and the local IP address of your member.

    You should see that you cluster is in an active state and has a single member. An active cluster is one that is operating without restrictions. To learn more about cluster states, see Cluster States.

    An active cluster in Management Center

  4. Click View Cluster and go to Storage > Maps.

You should see that your cluster has a map called my-distributed-map with three entries (keys and values). You’ll also see the total amount of memory that those entries are taking up in your cluster.

Map metrics in Management Center

For now, the backup memory is 0 because you don’t have any other members in your cluster on which to back up your map entries.

To back up your map, you need to scale up your cluster.

Step 4. Scale your Cluster

If your cluster starts to run out of memory, you can add more members to it and they will distribute their data across the new members.

Your cluster will even create a copy of any map entries and distribute them across other members of the cluster. This way, your data is secure in case of a single member failure.

In this step, you add two more members to your cluster.

  1. Open a new terminal and execute the Docker run command again to start another member.

    Each container must publish port 5701 to a different port on the host machine. On this member, port 5701 is published to port 5702 on the host machine.
    docker run \
        --name my-second-member --network hazelcast-network \
        -e HZ_CLUSTERNAME=hello-world \
        -e HZ_NETWORK_PUBLICADDRESS=$LOCAL_IP:5702 \
        -p 5702:5701 hazelcast/hazelcast:5.0-BETA-1
  2. Start another member.

    docker run \
        --name my-third-member --network hazelcast-network \
        -e HZ_CLUSTERNAME=hello-world \
        -e HZ_NETWORK_PUBLICADDRESS=$LOCAL_IP:5703 \
        -p 5703:5701 hazelcast/hazelcast:5.0-BETA-1

    You should see that your members find and connect to each other automatically to form your hello-world cluster. You can learn more about how members do this in Discovery Mechanisms.

    Console message displays three members connected to the same cluster

    Running more than one member on a single host is useful for testing Hazelcast, but it’s not suitable for production.
  3. Back in Management Center, open Storage > Maps again.

    You should see that the backup memory is the same as the entry memory, meaning that all your map entries have now been copied and distributed among the other two cluster members.

  4. To see how your map entries are distributed among members in your cluster, click my-distributed-map.

    Entries and their backups are distributed evenly across the other members

    You should see that entries and their backups are distributed evenly across each member. This process is called partitioning. You can learn more about this subject in Data Partitioning.

Step 5. Simulate a Member Failure

If a member fails for any reason, the other cluster members use their backups to repartition the data across the remaining cluster members.

In the terminal of one of your running members, press Ctrl+C to shut down the member.

You should the Hazelcast Shutdown is completed message in the console.

In Management Center, you should also see that the amount of entry memory and backup memory has not changed. All your map entries are still in memory despite a member being shut down. The remaining Hazelcast members have repartitioned the data.

Next Steps

Now that you have a local cluster, you can continue your journey with the following tutorials:

If you just want to go straight into deploying a production-ready cluster, see our production checklist.

Explore the tools Hazelcast offers for the following use cases:

Or, if you’re interested in learning more about topics that we introduced in this tutorial, see the following resources: