Skip Navigation

Tools

Sample Docker Compose

Run a single-broker Kafka in Docker on your own machine, connect KafkIO to it, and adapt or clean it up.

KafkIO includes a Docker Compose file for a single-broker Kafka on your own machine, already set up so that KafkIO (or any other client on the same machine) can connect to it. Use it to try KafkIO without touching a shared cluster, to experiment with topics and messages you can throw away, or as a known-good reference when your own Kafka in Docker connects and then times out.

You need Docker with the Compose plugin (Docker Desktop includes it on Windows and macOS). KafkIO doesn't run Docker for you: it only shows the file.

Opening the sample

Choose Tools ▸ Sample Docker Compose 1:

KafkIO's main window with the Tools menu open. It lists Show Config In, Show Logs In, JKS Converter, Network Tool and Sample Docker Compose; Sample Docker Compose is highlighted. Behind it, Storefront Staging and Local Kafka (Docker) are connected, and a duplicated Local Kafka (Docker) (Topics) tab is open beside the main Local Kafka (Docker) tab. 1
The Tools menu.
  1. Sample Docker Compose opens the sample in its own window.

The Sample Docker Compose link under the Docker note on the Kafka General tab of the cluster dialog opens the same window (see Kafka in Docker). It doesn't block the rest of KafkIO, so you can keep it open while you add the cluster, and its pin button keeps it on top of other windows. Choosing the menu item again while it's open brings it to the front.

What the sample sets up

The Sample Docker Compose window. At the top, notes say that Kafka in Docker must listen on 0.0.0.0 and advertise a host-resolvable address such as localhost, so that clients on the host can connect without DNS issues. Below, under Single Broker Cluster, a note says to connect with bootstrap servers 127.0.0.1:9092 or localhost:9092. Beside it is a 21-line Docker Compose file for one apache/kafka broker, with a Copy link under it and a Close button. 1 2 3
The Sample Docker Compose window.
  1. The bootstrap servers to use in KafkIO: localhost:9092 or 127.0.0.1:9092.
  2. The Compose file. It's read-only here: copy it and change your copy.
  3. Copy puts the whole file on the clipboard.

The file in full:

services:
  broker:
    image: apache/kafka:latest
    hostname: broker
    container_name: broker
    ports:
      - "9092:9092"
    environment:
      KAFKA_NODE_ID: 1
      KAFKA_PROCESS_ROLES: broker,controller
      KAFKA_LISTENERS: PLAINTEXT_EXT://0.0.0.0:9092,CONTROLLER://broker:9093
      KAFKA_INTER_BROKER_LISTENER_NAME: 'PLAINTEXT_EXT'
      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT_EXT://localhost:9092
      KAFKA_CONTROLLER_LISTENER_NAMES: CONTROLLER
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: CONTROLLER:PLAINTEXT,PLAINTEXT_EXT:PLAINTEXT
      KAFKA_CONTROLLER_QUORUM_VOTERS: 1@broker:9093
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
      KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: 1
      KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: 1
      KAFKA_GROUP_INITIAL_REBALANCE_DELAY_MS: 0
      KAFKA_NUM_PARTITIONS: 3

It runs one container, broker, from the official Apache Kafka image. That one node is both the broker and its own controller (KRaft mode, no ZooKeeper), with no security: plain, unauthenticated connections, which is fine on your own machine and nowhere else. What each part does:

SettingWhat it does
image: apache/kafka:latest The official Apache Kafka image, whichever version is newest when Docker first downloads it.
ports: "9092:9092" Publishes the container's port 9092 on your machine's port 9092. This is the port KafkIO connects to.
KAFKA_PROCESS_ROLES, KAFKA_NODE_ID, KAFKA_CONTROLLER_QUORUM_VOTERS, KAFKA_CONTROLLER_LISTENER_NAMES Make node 1 both a broker and the only controller of its own KRaft cluster.
KAFKA_LISTENERS Two listeners: PLAINTEXT_EXT for clients on port 9092, bound to 0.0.0.0 so connections forwarded from your machine reach it, and CONTROLLER on port 9093, used only inside the container and not published.
KAFKA_ADVERTISED_LISTENERS The address the broker tells clients to use after they first connect: localhost:9092, which works from your machine. This is the line that makes the sample work with KafkIO.
KAFKA_LISTENER_SECURITY_PROTOCOL_MAP, KAFKA_INTER_BROKER_LISTENER_NAME Both listeners use PLAINTEXT (no TLS, no login); the client listener doubles as the broker's own.
KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR, KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR, KAFKA_TRANSACTION_STATE_LOG_MIN_ISR Set Kafka's internal topics (consumer offsets, transactions) to one replica, since there's only one broker. Kafka's default of 3 would leave consumer groups and transactions unable to work.
KAFKA_GROUP_INITIAL_REBALANCE_DELAY_MS: 0 Consumers join a group at once instead of after Kafka's default 3-second wait.
KAFKA_NUM_PARTITIONS: 3 Topics that Kafka creates on its own get 3 partitions instead of 1. Kafka creates a topic when a client produces to one that doesn't exist yet (automatic topic creation is on, Kafka's default). KafkIO's Create Topic always sets a partition count, so it isn't affected.

Why the listener settings matter, and what goes wrong when they're different, is explained in Listeners and advertised listeners.

Running it

  1. Save the file

    Click Copy and paste the text into a new file called docker-compose.yml, in a folder of its own (Compose names the project after the folder).

  2. Start Kafka

    In a terminal in that folder, run:

    docker compose up -d

    The first time, Docker downloads the apache/kafka image, which takes a minute or so. The broker itself is ready a few seconds after the container starts. To check on it:

    docker compose ps
docker compose logs broker

    The log ends with Kafka Server started when it's ready.

Connecting KafkIO

  1. Add the cluster

    Click Add Cluster, give it a name (for example Local Kafka (Docker)), and set Bootstrap servers to localhost:9092. Leave the Kafka Security tab at PLAINTEXT, its default. A green colour is a good habit for a local cluster (see General Connection Settings).

  2. Test and save

    Click Test Connection: it should report A connection was successfully made! Then Save, and double-click the cluster to connect (see Adding a cluster).

Once connected, the Brokers section shows the single broker at the address it advertises:

KafkIO connected to the sample, shown as a green cluster called Local Kafka (Docker) under Storefront Staging in the cluster list, with its Brokers section open. The cards show 1 broker, active controller 1, version 4.0-IV3, 3 of 3 partitions online and controller type KRaft. The table has one row: broker 1, 365 bytes in 3 segments, 3 leaders, 3 replicas, port 9092, host localhost. A duplicated Local Kafka (Docker) (Topics) tab is open beside it. 1 2
The sample's broker in KafkIO, with an orders topic added.
  1. The new cluster, connected, alongside your other clusters.
  2. Port 9092 and host localhost: the advertised listener. If this ever shows a name like broker, your clients can't reach it (see If it doesn't connect).

The cluster starts with no topics of your own. Create one with Create Topic in the Topics section (Creating Topics), then produce a few messages to it. The Quick Start walks through both. Duplicating the cluster's tab (here, Local Kafka (Docker) (Topics)) lets you watch topics and brokers side by side.

Changing the sample

Port 9092 is already taken
Another Kafka (or anything else) on port 9092 makes docker compose up fail with a "port is already allocated" or similar error. Either stop it, or move the sample to another host port by changing two lines, and use localhost:19092 in KafkIO: 
    ports:
      - "19092:9092"
...
      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT_EXT://localhost:19092
The port inside the container stays 9092; only the published port and the advertised one change, and they must match each other.
A fixed Kafka version
latest is whatever version Docker downloaded first; it doesn't update by itself (docker compose pull does). To test against a particular Kafka version, replace it with a version tag, for example apache/kafka:3.9.1.
Two copies at once
container_name: broker means only one container of that name can exist. For a second copy, change container_name and the host port (as above) in the second file.
Clients in other containers
The sample advertises localhost, which is right for KafkIO and other tools on your machine but not for applications running in other containers. For both, give the broker a second listener advertised with its container name; see Listeners and advertised listeners.

Stopping and cleaning up

In the folder with the file:

CommandWhat happens to your topics and messages
docker compose stop Stops the container and keeps it. docker compose start (or up -d) brings Kafka back with everything as it was.
docker compose down Stops and removes the container. The data lived inside it (the sample has no Docker volume), so the next up -d starts an empty Kafka.

Stopping Kafka doesn't affect KafkIO's saved cluster: while the container is down, connecting to it fails like any unreachable cluster, and works again once it's back. To remove the cluster from KafkIO too, see Deleting a configuration.

If it doesn't connect

  • Test Connection fails, and docker compose ps shows no running container: Kafka isn't up. Check docker compose logs broker, and that Docker itself is running.
  • It worked with the sample, but your own Compose file connects and then times out: compare its KAFKA_LISTENERS and KAFKA_ADVERTISED_LISTENERS with the sample's. The usual cause is advertising the container's name; see Docker and advertised listeners.
  • You changed the port: the bootstrap server in KafkIO, the published port and the advertised port must all be the same number.
  • Still unsure whether the port is reachable: the Network Tool checks localhost and the port from KafkIO's side.