Start a Local Cluster from Binary

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 from the binary distribution, store data in memory, visualize your data and more.

Before You Begin

To complete this tutorial, you need the following:

Prerequisites	Useful resources
Any supported JDK	Supported Java Virtual Machines Using Modular Java
A full Hazelcast distribution	Install Hazelcast Install Hazelcast Enterprise Edition
Your internal IP address	How to Find Your Internal IP Address

Step 1. Configure the Name of the Cluster

Cluster configuration is an important step in creating a Hazelcast cluster. In this step, you learn how to configure a cluster by customizing its name.

1. Open the hazelcast.xml file in the hazelcast-5.7.2/config directory.

2. Change the value of the hazelcast.cluster-name field to hello-world.

   xml

   <hazelcast>
     <cluster-name>hello-world</cluster-name>
   </hazelcast>

3. Save and exit the file.

4. Open the hazelcast-client.xml file in the hazelcast-5.7.2/config directory.

5. Add the same cluster-name configuration to the hazelcast-client element.

   xml

   <hazelcast-client>
     <cluster-name>hello-world</cluster-name>
   </hazelcast-client>

6. Save and exit the file.

Step 2. Start a Local Member

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

In this step, you use the cluster management scripts to start a single-member cluster and check its status.

1. Start a member.

   Mac

   shell

   bin/hz-start

   Linux

   shell

   bin/hz-start

   Windows

   shell

   bin/hz-start.bat

   You should see your cluster's name in the console:

   

2. Open a new terminal window and use the cluster command to check the state of your member.

   The --config flag tells the CLI client to connect to the cluster, using the configuration in the hazelcast-client.xml file.

   Mac

   shell

   bin/hz-cli --config config/hazelcast-client.xml cluster

   Linux

   shell

   bin/hz-cli --config config/hazelcast-client.xml cluster

   Windows

   shell

   bin/hz-cli.bat --config config/hazelcast-client.xml cluster

   You should see something like the following:

   State: ACTIVE (1)
   Version: 5.7.2
   Size: 1 (2)
   
   ADDRESS                  UUID
   [192.168.0.2]:5701       27a73154-f4bb-477a-aef2-27ffa6f03a2d (3)

   1. The state of the cluster. An active cluster is one that is operating without restrictions.
   2. The number of members in the cluster.
   3. The internal IP address and UUID of the member.

Step 3. Write Data to Memory

Hazelcast has lots of distributed data structures available for writing data to memory in 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

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

   Mac and Linux
   shell

   bin/hz-cli --config config/hazelcast-client.xml sql

   Windows
   shell

   bin/hz-cli.bat --config config/hazelcast-client.xml sql

2. Create a map and add data to it.

   sql

   CREATE MAPPING my_distributed_map TYPE IMap OPTIONS ('keyFormat'='varchar','valueFormat'='varchar');
   
   SINK INTO my_distributed_map VALUES
   ('1', 'John'),
   ('2', 'Mary'),
   ('3', 'Jane');

   OK

Java

1. Install the Java client library

2. Add the following to your file:

   java

   import com.hazelcast.client.HazelcastClient;
   import com.hazelcast.client.config.ClientConfig;
   import com.hazelcast.core.HazelcastInstance;
   import com.hazelcast.map.IMap;
   
   public class MapSample {
     public static void main(String[] args) {
   
       ClientConfig clientConfig = new ClientConfig();
       clientConfig.setClusterName("hello-world"); (1)
   
       HazelcastInstance client = HazelcastClient.newHazelcastClient(clientConfig); (2)
       IMap <String,String> map = client.getMap("my-distributed-map"); (3)
   
       (4)
       map.put("1", "John");
       map.put("2", "Mary");
       map.put("3", "Jane");
     }
   }

   1 The name of the cluster that you want to connect to.

   2 Create a client instance, using your configuration.

   3 Create a map called my-distributed-map.

   4 Write some keys and values to the map.

C++

1. Install the latest C++ client library

2. Add the following to your file:

   cpp

   #include <hazelcast/client/hazelcast_client.h>
   
   int main() {
     hazelcast::client::client_config config;
     config.set_cluster_name("hello-world"); (1)
   
     auto client = hazelcast::new_client(std::move(config)).get(); (2)
   
     auto map = client.get_map("my-distributed-map").get(); (3)
   
     (4)
     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();
   
     return 0;
   }

   1 The name of the cluster that you want to connect to.

   2 Create a client instance, using your configuration.

   3 Create a map called my-distributed-map.

   4 Write some keys and values to the map.

C Sharp

1. Install the latest C Sharp client library

2. Add the following to your file:

   cs

   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)
   
         var client = await HazelcastClientFactory.StartNewClientAsync(options); (2)
   
         var map = client.GetMap("my-distributed-map"); (3)
   
         (4)
         map.put("1", "John");
         map.put("2", "Mary");
         map.put("3", "Jane");
       }
     }
   }

   1 The name of the cluster that you want to connect to.

   2 Create a client instance, using your configuration.

   3 Create a map called my-distributed-map.

   4 Write some keys and values to the map.

Node.js

1. Install the Node.js client library.

   shell

   npm install hazelcast-client

2. Add the following to your file:

   javascript

   const { Client } = require('hazelcast-client');
   
   (async () => {
     try {
       const client = await Client.newHazelcastClient({
         clusterName: 'hello-world', (1)
       }); (2)
   
       const map = await client.getMap('my-distributed-map'); (3)
   
       (4)
       await map.put('1', 'John');
       await map.put('2', 'Mary');
       await map.put('3', 'Jane');
   
     } catch (error) {
       console.error('Error occurred:', error);
     }
   })();

   1 The name of the cluster that you want to connect to.

   2 Create a client instance, using your configuration.

   3 Create a map called my-distributed-map.

   4 Write some keys and values to the map.

Python

1. Install the Python client library.

   shell

   pip install hazelcast-python-client

2. Add the following to your file:

   python

   import hazelcast
   
   if __name__ == "__main__":
     client = hazelcast.HazelcastClient(
     cluster_name="hello-world", (1)
     ) (2)
   
     # Create a Distributed Map in the cluster
     map = client.get_map("my-distributed-map").blocking() (3)
   
     (4)
     map.put("1", "John")
     map.put("2", "Mary")
     map.put("3", "Jane")

   1 The name of the cluster that you want to connect to.

   2 Create a client instance, using your configuration.

   3 Create a map called my-distributed-map.

   4 Write some keys and values to the map.

Go

1. Install the Python client library.

   shell

   go get github.com/hazelcast/hazelcast-go-client

2. Add the following to your file:

   go

   import (
   	"context"
   	"github.com/hazelcast/hazelcast-go-client"
   )
   
   func mapSampleRun() {
     // error handling is omitted for brevity
     config := hazelcast.Config{}
   
     config.Cluster.Name = "hello-world" (1)
   
     ctx := context.TODO()
     client, _ := hazelcast.StartNewClientWithConfig(ctx, config) (2)
   
     mp, _ := client.GetMap(ctx, "my-distributed-map") (3)
   
     (4)
     mp.Put(ctx, "1", "John")
     mp.Put(ctx, "2", "Mary")
     mp.Put(ctx, "3", "Jane")
   
   }

   1 The name of the cluster that you want to connect to.

   2 Create a client instance, using your configuration.

   3 Create a map called my-distributed-map.

   4 Write some keys and values to the map.

note

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 4. Read Data from Memory

You can read the data that you just wrote to memory by connecting to the member with a different client and requesting data from the member.

SQL

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

   Mac and Linux
   shell

   bin/hz-cli --config config/hazelcast-client.xml sql

   Windows
   shell

   bin/hz-cli.bat --config config/hazelcast-client.xml sql

2. Query all data in the map.

   sql

   SELECT * FROM my_distributed_map;

   +--------------------+--------------------+
   |__key               |this                |
   +--------------------+--------------------+
   |3                   |Jane                |
   |1                   |John                |
   |2                   |Mary                |
   +--------------------+--------------------+

3. Exit the SQL shell.

   shell

   exit

Java

java

import com.hazelcast.client.HazelcastClient;
import com.hazelcast.client.config.ClientConfig;
import com.hazelcast.core.HazelcastInstance;
import com.hazelcast.map.IMap;

public class MapSample {
  public static void main(String[] args) {

    ClientConfig clientConfig = new ClientConfig();
    clientConfig.setClusterName("hello-world");

    HazelcastInstance client = HazelcastClient.newHazelcastClient(clientConfig);

    (1)
    IMap map = client.getMap("my-distributed-map");
    for (Map.Entry<String, String> entry : map.entrySet()) {
      System.out.println(entry.getKey() + " " + entry.getValue());
    }

    client.shutdown(); (2)
  }
}

1 Request all data in the map and print it to the console.

2 Disconnect from the member.

C++

cpp

#include <hazelcast/client/hazelcast_client.h>

int main() {
  hazelcast::client::client_config config;
  config.set_cluster_name("hello-world");

  auto client = hazelcast::new_client(std::move(config)).get();

  auto map = client.get_map("my-distributed-map").get();

  (1)
  auto map = client.get_map("my-distributed-map").get();
  auto entries = map->entry_set<std::string, std::string>().get();
  for (auto &entry : map->entry_set<std::string, std::string>().get()) {
    std::cout << entry.first << " " << entry.second << std::endl;
  }

  client.shutdown(); (2)

  return 0;
}

1 Request all data in the map and print it to the console.

2 Disconnect from the member.

C Sharp

cs

using Hazelcast.Client;
using System;
using System.Threading.Tasks;

namespace Hazelcast.Examples.Org.Website.Samples
{
  public class MapSample
  {
    public static async Task Main(string[] args)
    {
      var options = new HazelcastOptionsBuilder().Build();
      options.ClusterName = "hello-world";

      await using var client = await HazelcastClientFactory.StartNewClientAsync(options);

      (1)
      var map = await client.GetMapAsync<string, string>("my-distributed-map");
      foreach (var entry in await map.GetEntriesAsync())
        Console.WriteLine($"{entry.Key}: {entry.Value}");

      client.Shutdown(); (2)
    }
  }
}

1 Request all data in the map and print it to the console.

2 Disconnect from the member.

Node.js

javascript

const { Client } = require('hazelcast-client');

(async () => {
  try {
    const client = await Client.newHazelcastClient({
      clusterName: 'hello-world',
    });

    (1)
    const map = await client.getMap('my-distributed-map');
    for (const [key, value] of await map.entrySet()) {
        console.log(`${key} ${value}`);
    }

    await hz.shutdown(); (2)

  } catch (error) {
    console.error('Error occurred:', error);
  }
})();

1 Request all data in the map and print it to the console.

2 Disconnect from the member.

Python

python

import hazelcast

if __name__ == "__main__":
  client = hazelcast.HazelcastClient(
  cluster_name="hello-world",
  )

  (1)
  my_map = client.get_map("my-distributed-map").blocking()
  for key, value in my_map.entry_set():
    print(key, value)

  client.shutdown() (2)

1 Request all data in the map and print it to the console.

2 Disconnect from the member.

Go

go

import (
	"context"
	"fmt"
	"github.com/hazelcast/hazelcast-go-client"
)

func mapSampleRun() {
  config := hazelcast.Config{}

  config.Cluster.Name = "hello-world"

  ctx := context.TODO()
  client, err := hazelcast.StartNewClientWithConfig(ctx, config)

  (1)
  myMap, err := client.GetMap(ctx, "my-distributed-map")
  if err != nil {
    panic(err)
  }
  myMap.Put(ctx, "1", "John")
  myMap.Put(ctx, "2", "Mary")
  myMap.Put(ctx, "3", "Jane")
  entries, err := myMap.GetEntrySet(ctx)
  if err != nil {
    // handle the error
  }
  for key, value := range entries {
    fmt.Println(key, value)
  }

  _ = client.Shutdown(ctx) (2)
}

1 Request all data in the map and print it to the console.

2 Disconnect from the member.

Step 5. 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.

   Mac

   shell

   management-center/bin/hz-mc start

   Linux

   shell

   management-center/bin/hz-mc start

   Windows

   shell

   management-center/bin/mc-start.cmd

2. In a web browser, go to localhost:8080 and enable dev mode.

   

3. Enter your cluster's name (hello-world) and your internal IP address.

   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.

   

4. Click View Cluster and go to Clients.

   You should see that two clients are connected to your cluster member: Management Center and the Hazelcast client that you used to write data to a map.

5. 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.

   

   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 6. 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 run the start script to start another member.

   shell

   cd hazelcast-5.7.2
   bin/hz-start

2. Repeat the previous step to start another member.

   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.

   

   note

   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, go to 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.

   

   You should see that entries and their backups are distributed evenly across each member. This process is called partitioning.

Step 7. 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:

• Get started with SQL by learning how to query data in your cluster.
• Get started with Data Processing by learning how to use the Java Jet API.

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:

• Caching data
• Distributed computing
• Distributed queries
• Ingesting data

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

• Cluster states
• Clients
• Data partitioning
• Maps and other data structures
• Management Center
• Network partitioning