luminanova/lumina repository overview

⁠LuminaKafka Docker Image

LuminaKafka is a read-only Kafka inspection UI for browsing:

• brokers
• topics
• partitions
• messages
• consumer groups

It runs as a single container with:

• Go backend
• Next.js frontend

After starting the container, open:

http://localhost:3000

⁠Quick Start

docker run -p 3000:3000 \
  -e KAFKA_BROKERS=<your-bootstrap-brokers> \
  luminanova/lumina

Example:

docker run -p 3000:3000 \
  -e KAFKA_BROKERS=broker1:9092,broker2:9092,broker3:9092 \
  luminanova/lumina

⁠Required Environment Variable

KAFKA_BROKERS

Comma-separated Kafka bootstrap brokers.

Example:

-e KAFKA_BROKERS=broker1:9092,broker2:9092

⁠Important Kafka Networking Note

KAFKA_BROKERS must be reachable from inside the Lumina container.

Kafka clients use the bootstrap broker list only to discover the cluster. After that, Kafka returns advertised broker addresses. Those advertised addresses must also be reachable from the Lumina container.

Because of that, the correct broker value depends on where Kafka is running.

⁠Common Run Scenarios

⁠1. Kafka Running On Your Host Machine

On macOS or Windows, use:

docker run -p 3000:3000 \
  -e KAFKA_BROKERS=host.docker.internal:9092 \
  luminanova/lumina

Do not use localhost:9092 here. Inside the container, localhost refers to the container itself, not your host machine.

⁠2. Kafka Running In Docker On The Same Docker Network

If Kafka is running in another container and its hostname is kafka:

docker run --network my-kafka-net -p 3000:3000 \
  -e KAFKA_BROKERS=kafka:19092 \
  luminanova/lumina

Use the Kafka container or service hostname, not localhost.

⁠3. Kafka Running Remotely

docker run -p 3000:3000 \
  -e KAFKA_BROKERS=broker1.company.net:9092,broker2.company.net:9092 \
  luminanova/lumina

⁠Port Mapping

Lumina serves the UI on port 3000.

Expose it like this:

-p 3000:3000

Then open:

http://localhost:3000

⁠Troubleshooting

⁠Error: Backend did not become ready at http://127.0.0.1:9099

This usually means Lumina started, but it could not connect to Kafka.

Most common causes:

• KAFKA_BROKERS points to localhost:9092
• Kafka is not reachable from the container
• Kafka advertised listeners are not reachable from the container

⁠Wrong

-e KAFKA_BROKERS=localhost:9092

⁠Better for host Kafka

-e KAFKA_BROKERS=host.docker.internal:9092

⁠Better for Docker Kafka

-e KAFKA_BROKERS=kafka:19092

⁠Example With Docker Network

docker network create kafka-net

docker run --network kafka-net -d --name lumina \
  -p 3000:3000 \
  -e KAFKA_BROKERS=kafka:19092 \
  luminanova/lumina

⁠Current Scope

This image currently supports:

• broker browsing
• topic browsing
• bounded message browsing
• consumer group inspection

It does not currently include:

• live tailing
• topic mutations
• consumer group mutations
• authentication
• multi-cluster switching