This is a prerelease version.

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

JDK 8+

A full Hazelcast distribution

Your local IP address

Step 1. Configure a 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. Create a copy of the default hazelcast.yaml file.

    • Mac

    • Linux

    • Windows

    cd hazelcast-5.0-BETA-1
    cp config/hazelcast.yaml config/my-awesome-cluster.yaml
    cd hazelcast-5.0-BETA-1
    cp config/hazelcast.yaml config/my-awesome-cluster.yaml
    cd hazelcast-5.0-BETA-1
    copy config/hazelcast.yaml config/my-awesome-cluster.yaml
  2. Change the value of the hazelcast/cluster-name field to your chosen name.

    hazelcast:
      # The name of the cluster. All members of a single cluster must have the
      # same cluster name configured and a client connecting to this cluster
      # must use it as well.
      cluster-name: hello-world
  3. Save and exit the file.

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

    • Linux

    • Windows

    bin/hz-start
    bin/hz-start
    bin/hz-start.bat

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

    Platform console displays the cluster name 'hello-world'

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

    • Mac

    • Linux

    • Windows

    bin/hz-cli cluster
    bin/hz-cli cluster
    bin/hz-cli.bat cluster

    You should see something like the following:

    State: ACTIVE (1)
    Version: 5.0-BETA-1
    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 IP address and ID 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

  • Java

  • C++

  • C Sharp

  • Node.js

  • Python

  • Go

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

    Mac and Linux
    bin/hz-cli sql
    Windows
    bin/hz-cli.bat sql
  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 4. 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

    • Linux

    • Windows

    management-center/bin/start.sh
    management-center/bin/start.sh
    management-center/bin/start.bat
  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.

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

    cd hazelcast-5.0-BETA-1
    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.

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

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