# Hazelcast

> In-memory data grid with distributed caching and computing.

- Category: Database Stacks
- Difficulty: intermediate
- Components: hazelcast, management-center
- Tags: hazelcast, in-memory, cache, distributed, grid
- Source: https://docker.recipes/databases/hazelcast

## Overview

Hazelcast is an open-source in-memory data grid platform that provides distributed caching, computing, and storage capabilities across clusters of servers. Originally developed in 2008, Hazelcast enables applications to share data and computation across multiple nodes, offering both high availability and horizontal scalability. The platform supports various data structures including maps, queues, topics, and sets, all distributed and replicated across cluster members for fault tolerance. This Docker stack combines the core Hazelcast server with the Management Center web interface, creating a complete distributed caching solution. The Hazelcast node handles data storage, replication, and client connections, while the Management Center provides real-time monitoring, cluster management, and administrative tools through a web dashboard. The two components communicate over the internal network, with the Management Center automatically discovering and connecting to cluster members. This combination is ideal for development teams building distributed applications that require low-latency data access, session sharing, or real-time analytics. The stack provides immediate value for microservices architectures needing shared state, Java applications requiring distributed caching, and organizations implementing event-driven architectures with stream processing capabilities.

## Features

- Distributed hash maps with automatic partitioning and replication across cluster nodes
- Built-in Jet stream processing engine for real-time data analytics and ETL operations
- SQL query support for distributed data structures using standard ANSI SQL syntax
- Near-cache implementation providing client-side caching for sub-millisecond access times
- Management Center web interface with cluster topology visualization and performance metrics
- Automatic cluster member discovery and dynamic scaling without manual configuration
- Event-driven architecture support with distributed topics and reliable message delivery
- CP Subsystem for strong consistency guarantees using Raft consensus algorithm

## Use cases

- Microservices session storage sharing user sessions across multiple application instances
- Real-time leaderboards and gaming statistics requiring ultra-low latency data access
- Financial trading platforms needing distributed reference data caching and risk calculations
- E-commerce applications caching product catalogs and inventory data across regions
- IoT data ingestion and stream processing for sensor data analytics and alerting
- Application-level database query result caching to reduce database load
- Distributed computing workloads requiring map-reduce style data processing across nodes

## Prerequisites

- Minimum 2GB RAM available as Hazelcast requires substantial memory for in-memory operations
- Port 5701 available for Hazelcast client connections and cluster communication
- Port 8080 free for Management Center web interface access
- Java application development knowledge for implementing Hazelcast clients
- Understanding of distributed systems concepts like partitioning and replication
- Network connectivity between client applications and Docker host for cluster access

## docker-compose.yml

```yaml
services:
  hazelcast:
    image: hazelcast/hazelcast:latest
    container_name: hazelcast
    restart: unless-stopped
    environment:
      HZ_CLUSTERNAME: dev
    ports:
      - "5701:5701"
    networks:
      - hz-network

  management-center:
    image: hazelcast/management-center:latest
    container_name: hz-management
    restart: unless-stopped
    environment:
      MC_DEFAULT_CLUSTER: dev
      MC_DEFAULT_CLUSTER_MEMBERS: hazelcast:5701
    ports:
      - "8080:8080"
    depends_on:
      - hazelcast
    networks:
      - hz-network

networks:
  hz-network:
    driver: bridge
```

## .env

```bash
# Hazelcast default configuration
```

## Usage notes

- Docs: https://docs.hazelcast.com/
- Management Center at http://localhost:8080 | Client port 5701
- Near-cache support - client-side caching for lowest latency
- SQL over distributed data - query maps with standard SQL
- Jet engine for stream processing and real-time analytics
- Automatic cluster discovery and data partitioning

## Troubleshooting

- Management Center shows 'Unable to connect to cluster': Verify HZ_CLUSTERNAME matches MC_DEFAULT_CLUSTER environment variables
- Client connection refused on port 5701: Check Docker host firewall and ensure port mapping is active with netstat -tulpn
- Cluster member not visible in Management Center: Confirm MC_DEFAULT_CLUSTER_MEMBERS points to correct container name and port
- OutOfMemoryError in Hazelcast logs: Increase Docker container memory limits or reduce map size configurations
- Split-brain scenario with multiple clusters: Ensure consistent cluster naming and implement proper network partitioning handling
- Slow query performance on distributed maps: Enable indexes on frequently queried fields and optimize SQL predicates

