Run Krabka and read your first record

Run a local Krabka broker, then produce and consume your first record with containerized Kafka tools. Keep the broker running to try a client example.

Before you start

Install Docker with Docker Compose. Start Docker.
Use a Bash terminal with curl. On Windows, use a Bash terminal connected to Docker.
Use an empty working directory. Make sure ports 9092 and 9404 are free. Run each local step in that directory.
The supplied krabka-broker 1.0.8 image uses linux/amd64.

The single-node Compose configuration is for local evaluation. Review the operations guides before deploying your own cluster.

To try without installing software, open the browser tools. Cluster Lab runs real brokers in your browser; its phone mode is for viewing.

1. Start a local broker

Download the Compose file and start its single-node KRaft broker.

Start

curl -fsSL https://krabka.io/quickstart/docker-compose.yml -o docker-compose.yml
docker compose up -d

2. Check that the broker is ready

The Kafka tools use the broker container's network. Continue when kafka-topics.sh --list completes without an error. An empty topic list is expected before you create a topic. If startup is still in progress, repeat this check. Use docker compose logs broker to inspect a failed startup.

Check readiness

KAFKA_TOOLS=docker.io/apache/kafka@sha256:01b9a4030e54c6068e66eb3ba4cb82c0d89238629ef1c30d79b86036bf89b1b7
docker run --rm --network "container:$(docker compose ps -q broker)" "$KAFKA_TOOLS" \
  /opt/kafka/bin/kafka-topics.sh --bootstrap-server localhost:9092 --list

3. Create a topic, produce, and consume

Create quickstart-events, send hello krabka, and read one record. You can repeat these commands with the same topic.

Verify the round trip

KAFKA_TOOLS=docker.io/apache/kafka@sha256:01b9a4030e54c6068e66eb3ba4cb82c0d89238629ef1c30d79b86036bf89b1b7
KAFKA_NETWORK="container:$(docker compose ps -q broker)"
docker run --rm --network "$KAFKA_NETWORK" "$KAFKA_TOOLS" /opt/kafka/bin/kafka-topics.sh \
  --bootstrap-server localhost:9092 --create --if-not-exists --topic quickstart-events --partitions 1 --replication-factor 1
printf 'hello krabka\n' | docker run --rm -i --network "$KAFKA_NETWORK" "$KAFKA_TOOLS" \
  /opt/kafka/bin/kafka-console-producer.sh --bootstrap-server localhost:9092 --topic quickstart-events
docker run --rm --network "$KAFKA_NETWORK" "$KAFKA_TOOLS" /opt/kafka/bin/kafka-console-consumer.sh \
  --bootstrap-server localhost:9092 --topic quickstart-events --from-beginning --max-messages 1 --timeout-ms 30000

The consumer prints hello krabka and exits after one record. If it times out, confirm that readiness passes and that the producer finished successfully.

4. Inspect the cluster with Kafka admin tools

Use the Apache Kafka admin tools to describe quickstart-events, inspect the KRaft quorum, list consumer groups, and check the negotiated API versions. See the compatibility matrix for supported protocol versions.

Inspect topics, quorum, groups, and API versions

KAFKA_TOOLS=docker.io/apache/kafka@sha256:01b9a4030e54c6068e66eb3ba4cb82c0d89238629ef1c30d79b86036bf89b1b7
KAFKA_NETWORK="container:$(docker compose ps -q broker)"
docker run --rm --network "$KAFKA_NETWORK" "$KAFKA_TOOLS" /opt/kafka/bin/kafka-topics.sh --bootstrap-server localhost:9092 --describe --topic quickstart-events
docker run --rm --network "$KAFKA_NETWORK" "$KAFKA_TOOLS" /opt/kafka/bin/kafka-metadata-quorum.sh --bootstrap-server localhost:9092 describe --status
docker run --rm --network "$KAFKA_NETWORK" "$KAFKA_TOOLS" /opt/kafka/bin/kafka-consumer-groups.sh --bootstrap-server localhost:9092 --list
docker run --rm --network "$KAFKA_NETWORK" "$KAFKA_TOOLS" /opt/kafka/bin/kafka-broker-api-versions.sh --bootstrap-server localhost:9092

The topic description shows quickstart-events. The quorum command reports its leader and voters. The consumer-group list can be empty.

The broker also serves Prometheus metrics on port 9404. To collect metrics alongside traces, logs, and profiles, see krabka-o11y.

Clean up the local broker

Cleanup is optional. This stops the local broker and deletes its Docker volume, including all records. Keep the broker running to try a client example.

Clean up

docker compose down --volumes

Choose your next task

Connect your application

Use a client example, including a downloadable JavaScript project.

Operate a cluster

Read recovery and upgrade procedures for your Krabka version.

Kubernetes option

Use a disposable Kubernetes cluster with kubectl and Helm configured. These commands use the default namespace for a three-node broker cluster and krabka-system for the operator. Use a cluster without another installation of these CRDs. This example runs krabka-operator 1.0.2 and krabka-broker 1.0.8.

Start and wait for readiness

kubectl apply -f https://krabka.io/quickstart/crds.yaml
helm repo add krabka https://krabka.io/charts
helm repo update
helm install krabka-operator krabka/krabka-operator --version 1.0.2 --skip-crds \
  --namespace krabka-system --create-namespace
kubectl rollout status deployment/krabka-operator-krabka-operator -n krabka-system --timeout=5m
kubectl apply -f https://krabka.io/quickstart/krabka-cluster.yaml
kubectl wait --for=condition=Ready kafka/m20-quickstart --timeout=10m
kubectl wait --for=condition=Ready kafkatopic/quickstart --timeout=5m

Continue when both kubectl wait commands report that the Ready condition is met. The manifest creates the quickstart topic. Run Kafka tools inside the cluster because brokers advertise in-cluster names.

Verify the Kubernetes round trip

KAFKA_TOOLS=docker.io/apache/kafka@sha256:01b9a4030e54c6068e66eb3ba4cb82c0d89238629ef1c30d79b86036bf89b1b7
kubectl run kafka-tools --image="$KAFKA_TOOLS" --restart=Never --rm -i --command -- \
  /bin/bash -lc "printf 'hello krabka\n' | /opt/kafka/bin/kafka-console-producer.sh --bootstrap-server m20-quickstart-broker-headless.default.svc.cluster.local:9092 --topic quickstart && /opt/kafka/bin/kafka-console-consumer.sh --bootstrap-server m20-quickstart-broker-headless.default.svc.cluster.local:9092 --topic quickstart --from-beginning --max-messages 1 --timeout-ms 30000"

The consumer prints hello krabka. See Configure the operator to change this deployment.

Clean up the Kubernetes example

Cleanup is optional. These commands remove the example cluster, topic, operator, and Krabka CRDs. Deleting CRDs affects every resource of those types. Run this only in the disposable cluster used for this example. Check your storage policy before removing persistent volumes.

Clean up

kubectl delete kafkatopic/quickstart
kubectl delete kafka/m20-quickstart
kubectl delete kafkanodepool/brokers --ignore-not-found
helm uninstall krabka-operator -n krabka-system
kubectl delete -f https://krabka.io/quickstart/crds.yaml