Single-node Kafka with KRaft for dev and test: setup and the settings that differ from production

#1. Configure a combined node

config/server.properties (Kafka 4.x layout; 3.x uses config/kraft/server.properties):

process.roles=broker,controller
node.id=1
controller.quorum.voters=1@kafka-dev:9093
listeners=PLAINTEXT://:9092,CONTROLLER://:9093
advertised.listeners=PLAINTEXT://kafka-dev:9092
controller.listener.names=CONTROLLER
log.dirs=/var/lib/kafka/data
num.partitions=3

# single node: replication must be 1
offsets.topic.replication.factor=1
transaction.state.log.replication.factor=1
transaction.state.log.min.isr=1
default.replication.factor=1
min.insync.replicas=1

log.retention.hours=72

#2. Format storage and start

KAFKA_CLUSTER_ID="$(bin/kafka-storage.sh random-uuid)"
bin/kafka-storage.sh format -t "$KAFKA_CLUSTER_ID" -c config/server.properties
bin/kafka-server-start.sh -daemon config/server.properties

bin/kafka-topics.sh --bootstrap-server kafka-dev:9092 --create --topic orders --partitions 3 --replication-factor 1
bin/kafka-console-producer.sh --bootstrap-server kafka-dev:9092 --topic orders

Or with Docker: the official apache/kafka image starts a single KRaft node with sensible defaults.

#3. Most common dev problem: advertised listeners

Clients connect to the bootstrap address, then reconnect to the advertised address. If advertised.listeners says localhost:9092, clients on other machines or containers fail with timeouts. Advertise a name the clients can resolve.

#4. Don't copy these settings to production

#5. Keep dev useful

• Topic configs (partitions, retention, compaction) as code, applied by the same tool as production (Terraform provider, a topics YAML + script).
• Schema Registry in dev too, so compatibility rules are tested early.

Warning

A single-node broker has no redundancy: disk loss = data loss, restart = outage. That's fine for dev/test. For anything customers depend on, see the Kafka HA post.