Deployment

The clustered cache requires Apache Kafka to be available for inter-node communication. Each application node connects to the same Kafka cluster and automatically discovers other cache nodes.

There are many ways to deploy the application, but here we show two common approaches: locally with Docker Compose and in a Kubernetes cluster.

Building the Docker Image

Build the Docker image:

docker build --tag cluster-hibernate-cache-demo:1.0.0 .
You can skip this step by using the prebuilt Docker image mstoer/cluster-hibernate-cache-demo:1.0.0.

Deploying to Local Docker

Deploying to a local Docker environment is a quick and easy way to test the clustered cache without needing any online services.

Docker Compose File

services:

  postgres:
    image: postgres:18.3
    ports:
      - "5432:5432"
    environment:
      POSTGRES_PASSWORD: "mysecretpassword"
      POSTGRES_DB: "es-cluster-demo"

  kafka:
    image: apache/kafka:4.1.2
    # In the docker network other containers communicate with kafka via kafka:9094, apps from outside via localhost:9092
    ports:
      - "9092:9092"
    environment:
      KAFKA_NODE_ID: "1"
      KAFKA_PROCESS_ROLES: "broker,controller"
      # Listener Configs
      KAFKA_LISTENERS: "PLAINTEXT://kafka:9094,PLAINTEXT_HOST://localhost:9092,CONTROLLER://kafka:9093"
      KAFKA_ADVERTISED_LISTENERS: "PLAINTEXT://kafka:9094,PLAINTEXT_HOST://localhost:9092"
      KAFKA_CONTROLLER_LISTENER_NAMES: "CONTROLLER"
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: "CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT,PLAINTEXT_HOST:PLAINTEXT"
      KAFKA_CONTROLLER_QUORUM_VOTERS: "1@kafka:9093"
      # Broker/Controller Configs
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: "1"
      KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: "1"
      KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: "1"
      KAFKA_SHARE_COORDINATOR_STATE_TOPIC_REPLICATION_FACTOR: "1"
      KAFKA_SHARE_COORDINATOR_STATE_TOPIC_MIN_ISR: "1"
      KAFKA_GROUP_INITIAL_REBALANCE_DELAY_MS: "0" # We use only 1 client per group so don't wait for rebalance
      # Default Topic Configs
      KAFKA_DEFAULT_REPLICATION_FACTOR: "1"
      KAFKA_MIN_INSYNC_REPLICAS: "1"
      KAFKA_NUM_PARTITIONS: "1"

  app:
    depends_on:
      - kafka
      - postgres
    deploy:
      mode: replicated
      replicas: 3
    image: mstoer/cluster-hibernate-cache-demo:1.0.0
    ports:
      - ":8080"
    environment:
      DATASOURCES_DEFAULT_PASSWORD: "mysecretpassword"
      DATASOURCES_DEFAULT_URL: "jdbc:postgresql://postgres:5432/es-cluster-demo"
      KAFKA_BOOTSTRAP_SERVERS: "kafka:9094"

To use your own image edit the app service in the docker-compose.yaml file, replacing image: mstoer/cluster-hibernate-cache-demo:1.0.0 with image: cluster-hibernate-cache-demo:1.0.0.

Start the Services

docker-compose up -d

Restart the Application Containers

Sometimes the application nodes start too early and crash since they can’t reach the database during initial startup. Restart them by rerunning:

docker-compose up -d

Find the Application Ports

The application nodes are assigned random host ports. To find out which ports they are running on:

docker container ls

Look for the app containers in the output. The PORTS column shows the host port on the left side and the container port (always 8080) on the right side. Send REST requests to the host port to reach the application.

Deploying to Kubernetes

For Kubernetes deployments, a StatefulSet is used for the application nodes to ensure stable network identities.

If you built your own Docker image, upload it to an image registry and update the image reference in the deployment manifest at spec.template.spec.containers[].image.

Apply the Deployment Manifest

kubectl apply -f deployment.yaml

This deploys all necessary Kubernetes resources including PostgreSQL, Kafka, and the application nodes.

Restart Crashed Application Pods

The application pods may have crashed while trying to connect to the non-existent database. Delete them to trigger a restart:

kubectl delete pod node-0 node-1 node-2

Access the Application Nodes

Use port-forwarding to connect to individual cache nodes:

# Connect to node-0
kubectl port-forward pod/node-0 8080:8080

# Connect to node-1
kubectl port-forward pod/node-1 8081:8080

# Connect to node-2
kubectl port-forward pod/node-2 8082:8080

Or use this service to connect to random nodes:

kubectl port-forward svc/node 8080:80
Ensure that the Kafka bootstrap.servers address is reachable from all application pods. In Kubernetes, use the DNS name (e.g., kafka-0.kafka:9092).