<a id="share-groups-docker"></a>

# Configure Share Groups for Docker in Confluent Platform

This topic provides a single-node setup for running Confluent Platform with share group support enabled
using Docker. Share groups allow for cooperative message consumption and scaling consumers beyond
the number of topic partitions, which is ideal for high-throughput queuing use cases.

Share partition lag represents the number of offsets in a
partition that are not delivery complete for a share group.
This metric reports processing progress and helps you automate scaling
of share consumer instances.
For configuration details, see the troubleshooting section below.

For client-side details, see
[Share Consumers for Confluent Platform](../../../clients/share-consumers.md#kafka-sharegroup).

## Environment variables for single-broker clusters

Set the following environment variables on a single-broker container
to configure the internal Apache Kafka® topic that stores share group
state, message locks, and delivery attempts:

`KAFKA_SHARE_COORDINATOR_STATE_TOPIC_REPLICATION_FACTOR`
: Defines the number of brokers that replicate each partition of the
  internal topic used to store share group metadata.

`KAFKA_SHARE_COORDINATOR_STATE_TOPIC_MIN_ISR`
: Defines the minimum number of replicas that must be in-sync for a successful write
  operation to the internal state topic.

## Run Kafka with share groups enabled

In a single-broker cluster, you run Kafka with share groups enabled in the same way that
you would normally start it, but you specify the
`KAFKA_SHARE_COORDINATOR_STATE_TOPIC_REPLICATION_FACTOR` and
`KAFKA_SHARE_COORDINATOR_STATE_TOPIC_MIN_ISR` environment variables.

The following `docker-compose.yml` file sets up a single-broker Kafka cluster using KRaft
mode, with highlighted lines for enabling the share coordinator and configuring the
internal state topic.

```yaml
services:

  broker:
    image: confluentinc/cp-server:8.1.0
    hostname: broker
    container_name: broker
    ports:
      - "9092:9092"
      - "9101:9101"
    environment:
      KAFKA_NODE_ID: 1
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: 'CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT,PLAINTEXT_HOST:PLAINTEXT'
      KAFKA_ADVERTISED_LISTENERS: 'PLAINTEXT://broker:29092,PLAINTEXT_HOST://localhost:9092'
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
      KAFKA_GROUP_INITIAL_REBALANCE_DELAY_MS: 0
      KAFKA_CONFLUENT_LICENSE_TOPIC_REPLICATION_FACTOR: 1
      KAFKA_CONFLUENT_BALANCER_TOPIC_REPLICATION_FACTOR: 1
      KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: 1
      KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: 1
      KAFKA_JMX_PORT: 9101
      KAFKA_JMX_HOSTNAME: localhost
      KAFKA_PROCESS_ROLES: 'broker,controller'
      KAFKA_CONTROLLER_QUORUM_VOTERS: '1@broker:29093'
      KAFKA_LISTENERS: 'PLAINTEXT://:29092,CONTROLLER://:29093,PLAINTEXT_HOST://0.0.0.0:9092'
      KAFKA_INTER_BROKER_LISTENER_NAME: 'PLAINTEXT'
      KAFKA_CONTROLLER_LISTENER_NAMES: 'CONTROLLER'
      KAFKA_LOG_DIRS: '/tmp/kraft-combined-logs'
      CONFLUENT_METRICS_ENABLE: 'false'
      CONFLUENT_SUPPORT_CUSTOMER_ID: 'anonymous'      
      CLUSTER_ID: 'MkU3OEVBNTcwNTJENDM2Qk'
      
      # --- Share Group Configuration (Enabled) ---
      KAFKA_SHARE_COORDINATOR_STATE_TOPIC_REPLICATION_FACTOR: 1
      KAFKA_SHARE_COORDINATOR_STATE_TOPIC_MIN_ISR: 1
```

Considerations:
: - If you are using Docker Compose V1, use a dash in the `docker compose` commands. For
    more information, see [Migrate to Compose V2](https://docs.docker.com/compose/releases/migrate/).
  - Set the share group feature version on the cluster after the broker has started.
  - Run the following commands from the host machine.
  - Confluent drops the `.sh` extension for CLI tools.

To run a single-broker Kafka cluster with share groups enabled:

1. Copy the example compose file and save to a file named: `docker-compose.yml`
2. In a terminal window, navigate to where you saved the compose file, and start the single-broker Kafka cluster
   with the `-d` option to run in detached mode:
   ```bash
   docker compose up -d
   ```

   Your output should resemble the following:
   ```bash
   ✔ Network qfk-quick-start.       Created       0.0s
   ✔ Container broker               Started       0.3s
   ```
3. Verify that the broker is up and running:
   ```bash
   docker compose ps
   ```
4. Enable the share group feature:
   ```bash
   docker compose exec broker kafka-features
           --bootstrap-server localhost:9092 \
           upgrade \
           --feature share.version=1
   ```

   Your output should resemble the following:
   ```bash
   share.version was upgraded to 1.
   ```
5. Create a topic named `share-test` with a single partition:
   ```bash
   docker compose exec broker kafka-topics \
           --create \
           --topic share-test \
           --bootstrap-server localhost:9092 \
           --partitions 1 \
           --replication-factor 1 \
           --if-not-exists
   ```

   Your output should resemble the following:
   ```bash
   Created topic share-test.
   ```
6. In a second terminal window, start the first share consumer:
   ```bash
   docker compose exec broker kafka-console-share-consumer \
           --topic share-test \
           --bootstrap-server localhost:9092 \
           --group share-group-v3
   ```
7. In a third terminal window, start the second share consumer, using the same group as the
   first share consumer:
   ```bash
   docker compose exec broker kafka-console-share-consumer \
           --topic share-test \
           --bootstrap-server localhost:9092 \
           --group share-group-v3
   ```
8. Open a fourth terminal window and run the producer:
   ```bash
   docker compose exec broker kafka-console-producer \
           --topic share-test \
           --bootstrap-server localhost:9092
   ```
9. In the producer terminal window, type 10 or more unique messages and press Enter after each one.
   For example:
   - message 1
   - message 2
   - message 3
     …
10. Verify success. Records appear in both share consumers, distributed in batches or chunks, demonstrating
    successful message splitting across the single partition.

    If you’re done working with Confluent Platform, you can stop and remove the Docker
    containers and images. To stop the consumer and producer, use the key combination
    `Control` + `C`.
11. Run the following command to stop the Docker containers:
    ```bash
    docker compose stop
    ```
12. After stopping the Docker containers, run the following commands to
    prune the Docker system. Running these commands deletes containers,
    networks, volumes, and images, freeing up disk space:
    ```bash
    docker system prune -a --volumes --filter "label=io.confluent.docker"
    ```

## Troubleshoot

| Issue or error message                                      | Cause                                                                                                                                                                                                                                 | Fix                                                                                                                                                                                                                                   |
|-------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Share consumers can join the group but receive no messages. | Incorrect `KAFKA_LISTENERS` prevents the controller from assigning<br/>consumption tasks to the broker.                                                                                                                               | Ensure internal listeners use the wildcard interface. For example,<br/>see [Partitions not being assigned](#share-groups-listeners).                                                                                                  |
| Consumers don’t read old messages.                          | The share consumer tool often defaults to latest offset, and the<br/>`--from-beginning` flag isn’t supported. To read from the earliest offset,<br/>set `share.auto.offset.reset` to `EARLIEST` using the share group configurations. | Use a new, unique group ID for each consumption test to force the broker to<br/>start reading from the beginning.                                                                                                                     |
| UNKNOWN_TOPIC_OR_PARTITION                                  | Producer starts before the broker fully loads KRaft metadata on start up.                                                                                                                                                             | Wait 15-30 seconds after docker compose up before running any commands.                                                                                                                                                               |
| exec: “kafka-features.sh”: … not found                      | Incorrect path or use of the `.sh` extension in Confluent Platform Docker images.                                                                                                                                                     | Drop the `.sh` extension: use `kafka-features`.                                                                                                                                                                                       |
| Share lag metric shows no data or is empty.                 | The share lag calculator is not configured.                                                                                                                                                                                           | Ensure `confluent.share.lag.calculator.enabled` is set to `true` in the broker configuration.<br/>Additionally, ensure `org.apache.kafka.common.metrics.JmxReporter` is added as part of the `metric.reporters` broker configuration. |

<a id="share-groups-listeners"></a>

### Partitions not being assigned

If you are able to form a share group but partitions are not being assigned, change the hostname in your `KAFKA_LISTENERS` environment variable from a
specific service name, such as `broker`, to the wildcard interface (`:`) as shown in the following example.

If your `KAFKA_LISTENERS` specifies a particular service name, such as `broker`, and
partitions are not being assigned:

- `KAFKA_LISTENERS: 'PLAINTEXT://broker:29092,CONTROLLER://broker:29093,PLAINTEXT_HOST://0.0.0.0:9092'`

Change your `KAFKA_LISTENERS` to the wildcard interface (:) like in the following example:

- `KAFKA_LISTENERS: 'PLAINTEXT://:29092,CONTROLLER://:29093,PLAINTEXT_HOST://0.0.0.0:9092'`

Use the wildcard interface (:) for `KAFKA_LISTENERS` with share groups.

## Related content

- [Share Consumers for Confluent Platform](../../../clients/share-consumers.md#kafka-sharegroup)
- [Share Groups for Confluent Platform](../../../config-manage/kafka-queues.md#share-groups-broker)
- [Monitor Kafka with JMX in Confluent Platform](../../../kafka/monitoring.md#kafka-monitoring)
- [Monitor and Track Metrics in Docker with JMX in Confluent Platform](monitoring.md#use-jmx-monitor-docker-deployments)