Installer Apache Cassandra avec Docker Compose et cqlsh

L'installation native d'Apache Cassandra sur un système d'exploitation hôte exige de configurer un environnement d'exécution Java (OpenJDK 11 ou 17), de paramétrer des variables système, d'installer un interpréteur Python compatible pour l'outil de console et d'éditer manuellement le volumineux fichier de configuration cassandra.yaml.

Pour développer et expérimenter sereinement dans un cadre reproductible et isolé, la conteneurisation avec Docker et Docker Compose est la méthode la plus rapide et la plus propre.

---

1. Les ports réseau d'Apache Cassandra

Avant de démarrer un conteneur, il est indispensable de comprendre le rôle des ports exposés par un nœud Cassandra :

flowchart LR
    App[Applications Python / Java] -->|Port 9042 : Protocole Client CQL| N1[Nœud Cassandra]
    CLI[Console cqlsh] -->|Port 9042 : Protocole Client CQL| N1
    N1 <-->|Port 7000 : Protocole Gossip Inter-Nœuds| N2[Nœud Voisin]
    Admin[Outil nodetool] -->|Port 7199 : Métriques JMX| N1

• Port 9042 (Transport natif CQL) : Le port d'écoute principal pour tous les clients externes (cqlsh, pilotes Python, Java, Go, C#).
• Port 7000 (Communication inter-nœuds) : Utilisé par le cluster pour échanger les messages Gossip et transférer les répliques de données.
• Port 7001 (Inter-nœuds sécurisé) : Le même protocole de cluster, chiffré via TLS/SSL.
• Port 7199 (Port JMX - Java Management Extensions) : Utilisé par l'outil d'administration système en ligne de commande nodetool.

---

2. Le fichier docker-compose.yml

Créez un répertoire de travail nommé cassandra-workspace sur votre machine, puis créez à l'intérieur le fichier docker-compose.yml suivant :

docker-compose.yml

version: '3.8'

services:
  cassandra:
    container_name: analytics-cassandra-1
    image: cassandra:5.0
    restart: always
    environment:
      # Nom logique du cluster partagé par tous les nœuds
      - CASSANDRA_CLUSTER_NAME=AnalyticsCluster
      # Nom du Datacenter et du Rack logique
      - CASSANDRA_DC=datacenter1
      - CASSANDRA_RACK=rack1
      - CASSANDRA_ENDPOINT_SNITCH=GossipingPropertyFileSnitch
      # Optimisation de la mémoire vive pour machine de développement (évite la saturation RAM)
      - MAX_HEAP_SIZE=1024M
      - HEAP_NEWSIZE=256M
    ports:
      - "9042:9042" # Port client CQL natif
    volumes:
      - cassandra-data-volume:/var/lib/cassandra
    networks:
      - analytics-network
    healthcheck:
      test: ["CMD", "cqlsh", "-e", "DESCRIBE KEYSPACES"]
      interval: 15s
      timeout: 10s
      retries: 10

volumes:
  cassandra-data-volume:

networks:
  analytics-network:
    driver: bridge

[!NOTE] Par défaut en production, Cassandra alloue automatiquement la moitié de la mémoire vive physique totale du serveur à son tas Java (JVM Heap). Les variables MAX_HEAP_SIZE=1024M et HEAP_NEWSIZE=256M plafonnent ici l'empreinte mémoire à 1 Go, évitant ainsi de ralentir votre poste de travail personnel pendant l'apprentissage.

---

3. Démarrage et initialisation du cluster

Ouvrez un terminal dans le dossier contenant votre fichier et lancez le démarrage du service en arrière-plan :

docker compose up -d

[!IMPORTANT] Cassandra est une application distribuée complexe dont le processus de démarrage prend entre 20 et 45 secondes (initialisation du CommitLog, démarrage des démons de communication Gossip et ouverture du port CQL).

Pour suivre les logs d'initialisation en direct :

docker compose logs -f cassandra

Dès que vous observez la ligne suivante dans les journaux, le serveur est prêt à recevoir vos commandes :

Startup complete, forcing unmap of past segments...
Created default superuser role 'cassandra'
Starting listening for CQL clients on /0.0.0.0:9042 (encrypted: false)...

---

4. Supervision du nœud avec l'utilitaire nodetool

nodetool est le couteau suisse d'administration d'Apache Cassandra. Il communique directement avec la JVM via le port JMX pour auditer la topologie et la santé du cluster.

Pour vérifier l'état de votre nœud, exécutez :

docker exec -it analytics-cassandra-1 nodetool status

Sortie obtenue dans le terminal :

Sortie attendue de nodetool status

Datacenter: datacenter1
=======================
Status=Up/Down
|/ State=Normal/Leaving/Joining/Moving
--  Address     Load       Tokens  Owns (effective)  Host ID                               Rack
UN  172.20.0.2  104.3 KiB  16      100.0%            a1b2c3d4-e5f6-7890-abcd-ef1234567890  rack1

Comprendre le code de statut :

• U (Up) : Le nœud est en ligne et accessible sur le réseau.
• N (Normal) : L'état du nœud est nominal (il ne subit ni opération de désaffectation Leaving, ni intégration Joining).
• Tokens : Le nombre de jetons virtuels (vnodes) assignés au nœud sur l'anneau de hachage.
• Owns (effective) : Indique le pourcentage de l'espace de clés dont ce nœud est responsable (100 % dans le cadre d'un cluster mono-nœud de test).

---

5. Connexion interactive avec le shell cqlsh

Le shell officiel cqlsh (Cassandra Query Language Shell) est l'interpréteur de commandes interactif permettant d'exécuter des scripts et des requêtes CQL.

Lancez la connexion directement au cœur du conteneur :

docker exec -it analytics-cassandra-1 cqlsh

La bannière officielle de bienvenue s'affiche :

Connected to AnalyticsCluster at 127.0.0.1:9042
[cqlsh 6.2.0 | Cassandra 5.0.0 | CQL spec 3.4.7 | Native protocol v5]
Use HELP for help.
cqlsh>

Commandes d'inspection fondamentales dans cqlsh :

-- 1. Afficher les métadonnées globales du cluster
DESCRIBE CLUSTER;

-- 2. Lister les Keyspaces (bases de données) présents
DESCRIBE KEYSPACES;

-- 3. Consulter les versions des composants internes
SHOW VERSION;

Sortie de DESCRIBE CLUSTER; :

Cluster: AnalyticsCluster
Partitioner: Murmur3Partitioner
Snitch: GossipingPropertyFileSnitch

[!NOTE] Le Murmur3Partitioner est la fonction de hachage cryptographique interne chargée de calculer le token d'une partition (une valeur entière comprise entre \(-2^{63}\) et \(+2^{63}-1\)). C'est ce calcul qui détermine quel nœud physique héberge chaque ligne de données sur l'anneau.

Pour quitter le shell interactif et revenir à votre terminal hôte :

exit;

---

6. Gestion du cycle de vie du conteneur

Voici les commandes quotidiennes indispensables pour administrer votre environnement Docker :

• Mettre en pause le service (sans perte de données) :

  docker compose stop
  

• Relancer le service existant :

  docker compose start
  

• Arrêter et supprimer le conteneur (les données du volume restent préservées) :

  docker compose down
  

• Réinitialisation totale (purge définitive des données et des volumes) :

  docker compose down -v
  

---

Votre environnement Apache Cassandra est parfaitement configuré et opérationnel ! Rendez-vous dans le chapitre suivant pour maîtriser le langage CQL et appréhender les règles incontournables de la modélisation distribuée.

Partagez sur les réseaux sociaux

Commentaires