# Cassandra Cluster

> Apache Cassandra distributed NoSQL database cluster setup.

- Category: Database Stacks
- Difficulty: advanced
- Components: cassandra
- Tags: cassandra, nosql, distributed, cluster
- Source: https://docker.recipes/databases/cassandra-cluster

## Overview

Apache Cassandra is a highly scalable, distributed NoSQL database originally developed by Facebook and later open-sourced to the Apache Software Foundation. Designed to handle massive amounts of data across multiple commodity servers, Cassandra eliminates single points of failure through its peer-to-peer distributed architecture and provides tunable consistency levels for optimal performance across different use cases.

This three-node Cassandra cluster configuration creates a production-grade distributed database setup where each node operates as an equal peer in the ring topology. The cluster uses cassandra-1 as the seed node to bootstrap the ring formation, with all nodes sharing the same cluster name and automatically discovering each other through Cassandra's gossip protocol. The setup enables linear scalability, automatic data distribution, and fault tolerance with configurable replication factors.

This stack is ideal for organizations running write-heavy applications, time-series data collection systems, or any application requiring guaranteed uptime with global distribution capabilities. Companies dealing with IoT sensor data, financial transactions, social media platforms, or recommendation engines will benefit from Cassandra's ability to handle millions of writes per second while maintaining low-latency reads across geographically distributed locations.

## Features

- Linear horizontal scalability with no performance degradation
- Masterless architecture with no single point of failure
- Tunable consistency levels from eventual to strong consistency
- Multi-datacenter replication with rack-aware topology
- CQL (Cassandra Query Language) support for SQL-like operations
- Time-series data optimization with TTL and compaction strategies
- Wide column store model supporting complex data structures
- Gossip protocol for automatic node discovery and health monitoring

## Use cases

- IoT sensor data collection and time-series analytics platforms
- Financial transaction processing systems requiring high availability
- Social media platforms handling millions of user interactions
- E-commerce recommendation engines with real-time personalization
- Gaming leaderboards and player statistics tracking
- Log aggregation and monitoring systems for distributed applications
- Content delivery networks requiring global data distribution

## Prerequisites

- Minimum 8GB RAM total (2GB per node) for production workloads
- Port 9042 available for CQL client connections
- Understanding of Cassandra's eventual consistency model and CAP theorem
- Basic knowledge of CQL syntax and data modeling concepts
- Familiarity with nodetool commands for cluster management
- At least 20GB free disk space for initial data storage per node

## docker-compose.yml

```yaml
services:
  cassandra-1:
    image: cassandra:4.1
    container_name: cassandra-1
    restart: unless-stopped
    environment:
      CASSANDRA_CLUSTER_NAME: ${CLUSTER_NAME}
      CASSANDRA_SEEDS: cassandra-1
    volumes:
      - cassandra1_data:/var/lib/cassandra
    ports:
      - "9042:9042"
    networks:
      - cassandra-network

  cassandra-2:
    image: cassandra:4.1
    container_name: cassandra-2
    restart: unless-stopped
    environment:
      CASSANDRA_CLUSTER_NAME: ${CLUSTER_NAME}
      CASSANDRA_SEEDS: cassandra-1
    volumes:
      - cassandra2_data:/var/lib/cassandra
    depends_on:
      - cassandra-1
    networks:
      - cassandra-network

  cassandra-3:
    image: cassandra:4.1
    container_name: cassandra-3
    restart: unless-stopped
    environment:
      CASSANDRA_CLUSTER_NAME: ${CLUSTER_NAME}
      CASSANDRA_SEEDS: cassandra-1
    volumes:
      - cassandra3_data:/var/lib/cassandra
    depends_on:
      - cassandra-2
    networks:
      - cassandra-network

volumes:
  cassandra1_data:
  cassandra2_data:
  cassandra3_data:

networks:
  cassandra-network:
    driver: bridge
```

## .env

```bash
CLUSTER_NAME=MyCluster
```

## Usage notes

- Docs: https://cassandra.apache.org/doc/latest/
- Connect via cqlsh: docker exec -it cassandra-1 cqlsh
- Check cluster status: docker exec -it cassandra-1 nodetool status
- Wait 1-2 minutes between node starts for proper cluster formation
- Default CQL port 9042 - use for application connections
- Backup: nodetool snapshot, restore with sstableloader

## Troubleshooting

- Node shows as DOWN in nodetool status: Check if containers started in sequence with proper delays between node initialization
- Connection refused on port 9042: Wait 2-3 minutes after cluster startup for native transport to become available
- Cluster forms with wrong datacenter names: Set CASSANDRA_DC and CASSANDRA_RACK environment variables explicitly
- High memory usage or OOM errors: Increase container memory limits and tune JVM heap settings via CASSANDRA_HEAP_SIZE
- Nodes not discovering each other: Verify CASSANDRA_SEEDS points to correct seed node hostnames within Docker network
- Write/read timeouts during operations: Adjust consistency levels in CQL queries or increase request timeout values

