Kafka playground 🐘⚡

Un petit projet d'exploration Kafka + FastAPI pour produire et consommer des messages localement via Docker Compose.

Ce dépôt contient :

• un broker Kafka (Confluent) et Zookeeper
• une UI Kafka (kafka-ui)
• un microservice Producer (FastAPI)
• un microservice Consumer (Python)

🧭 Description

Ce projet vise à fournir un environnement local minimal pour tester la production et la consommation de messages Kafka. Les services sont packagés dans des images Docker et orchestrés avec docker compose.

Prérequis ✅

• Docker & Docker Compose installés
• Au moins 2–3 Go d'espace libre (images Confluent peuvent être lourdes)

Démarrage rapide 🚀

1. Construire et démarrer tous les services :

docker compose up -d --build

2. Vérifier l'état des services :

docker compose ps

3. Suivre les logs :

docker compose logs -f broker kafka-producer kafka-consumer

Si vous voulez rebuild seulement un service (ex: producer) :

docker compose up -d --build kafka-producer

📡 Accès aux services et tests

• Kafka UI : http://localhost:7777
• Producer (FastAPI) : http://localhost:5000
• Documentation OpenAPI (Swagger) pour les tests : http://localhost:5000/docs

Pour tester la production d'un message, utiliser l'endpoint /produce via Swagger UI ou curl :

curl -X POST "http://localhost:5000/produce/my_topic/my_key" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"message\":\"Hello, Kafka!\"}"

Vous devriez voir le message consommé dans les logs du consumer. Exemple de log du consumer :

kafka-consumer  | ════════════════════════════════════════════════════════════
kafka-consumer  | 📨  Nouveau message Kafka 🔔  [2025-11-04 10:45:13 UTC]
kafka-consumer  | ────────────────────────────────────────────────────────────
kafka-consumer  | 🧭  Topic     : my_topic
kafka-consumer  | 📦  Partition : 0
kafka-consumer  | 🔢  Offset    : 4
kafka-consumer  | 🗝️  Key       : my_key
kafka-consumer  | 🧾  Data      : {"hello": "Kafka"}
kafka-consumer  | ════════════════════════════════════════════════════════════

Diagnostic & commandes utiles 🔎

• Tester que le broker écoute bien (depuis le conteneur broker) :

docker compose exec broker kafka-broker-api-versions --bootstrap-server localhost:9093

• Vérifier les logs d'un service :

docker compose logs -f kafka-consumer

⚙️ Variables d'environnement (conseillées)

Voici les variables utilisées ou pertinentes dans le projet. Il est conseillé de stocker les valeurs dans un fichier .env à la racine et de l'inclure via env_file: ou docker compose --env-file .env up.

• Pour le broker (Kafka) — définies dans docker-compose.yaml :

  • KAFKA_BROKER_ID — identifiant du broker (ex: 1)
  • KAFKA_ZOOKEEPER_CONNECT — adresse Zookeeper (ex: zookeeper:2181)
  • KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR — replication factor pour __consumer_offsets
  • KAFKA_TRANSACTION_STATE_LOG_MIN_ISR
  • KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR
  • KAFKA_LISTENERS — configuration des listeners (ex: PLAINTEXT_INTERNAL://0.0.0.0:29092,PLAINTEXT_C://0.0.0.0:9093,PLAINTEXT_L://0.0.0.0:9092)
  • KAFKA_ADVERTISED_LISTENERS — advertised listeners (ex: PLAINTEXT_INTERNAL://broker:29092,PLAINTEXT_L://localhost:9092,PLAINTEXT_C://broker:9093)
  • KAFKA_LISTENER_SECURITY_PROTOCOL_MAP
  • KAFKA_INTER_BROKER_LISTENER_NAME

• Pour les services Producer / Consumer :

  • PYTHONUNBUFFERED=1 — désactive le buffering stdout de Python (déjà fixé dans docker-compose.yaml pour voir les prints immédiatement)
  • KAFKA_BOOTSTRAP_SERVERS — adresse bootstrap pour les clients (ex: broker:9093)
  • PYTHONDONTWRITEBYTECODE (optionnel) — empêche la création de __pycache__/.pyc
  • KAFKA_TOPIC (optionnel) — topic par défaut utilisé par le consumer si non précisé

• Pour kafka-ui :

  • KAFKA_CLUSTERS_0_NAME
  • KAFKA_CLUSTERS_0_BOOTSTRAPSERVERS
  • KAFKA_CLUSTERS_0_ZOOKEEPER

Exemple de fichier .env minimal :

# Broker
KAFKA_BROKER_ID=1
KAFKA_ZOOKEEPER_CONNECT=zookeeper:2181

# Clients
KAFKA_BOOTSTRAP_SERVERS=broker:9093
PYTHONUNBUFFERED=1
PYTHONDONTWRITEBYTECODE=1

# App
KAFKA_TOPIC=test-topic

Place ce fichier à la racine et démarre le compose en précisant --env-file .env si tu veux le contrôler explicitement.

Bon dev ! 🚀