docker compose generation

[vsevel]

the compose feature is great, but it can be cumbersome to create the compose file, and even harder to keep it up to date.

in our extensions we have developed a mechanism that generates a docker compose based on extensions used in the application.

for instance if the application uses the jms, kafka and apicurio extensions, at build time we will generate target/compose/compose-devservices.yml, with content:

name: bank-quarkus
services:
  apicurio:
    image: apicurio/apicurio-registry-mem:2.4.2.Final
    ports:
    - '8080'
  artemis:
    image: quay.io/arkmq-org/activemq-artemis-broker:artemis.2.40.0
    ports:
    - '61616'
    environment:
      AMQ_USER: admin
      AMQ_PASSWORD: admin
      AMQ_EXTRA_ARGS: --no-autotune --mapped --no-fsync
  kafka:
    image: apache/kafka-native:3.9.0
    restart: 'no'
    ports:
    - '9092'
    labels:
      io.quarkus.devservices.compose.exposed_ports: /etc/kafka/docker/ports
    environment:
      KAFKA_NODE_ID: 1
      KAFKA_PROCESS_ROLES: broker,controller
      KAFKA_LISTENERS: PLAINTEXT://:9092,CONTROLLER://:9093
      KAFKA_CONTROLLER_LISTENER_NAMES: CONTROLLER
      KAFKA_CONTROLLER_QUORUM_VOTERS: 1@localhost: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
    command: /kafka.sh
    volumes:
    - ./kafka.sh:/kafka.sh

plus an additional kafka.sh (with content as seen in documentation).

the dev team can decide to copy those resources to ./ under source control so they get used in dev mode.
if we see there is a file in ./:

• if we are running on the local developer host, , then we will override it with the one we generate (with a config param to disable that behavior if needed)
• if we are running on the CI, we will compare it with the one we generate. if different, we will fail the build (with a config param to ignore diffs if needed).
  it works like the formatter and impsort plugins: update file under source control in dev, check in CI.

the last piece that we have is the ability to complement and/or override some values in the generated file.
for instance we may create ./override-compose-devservices.yml with content:

services:
  apicurio:
    image: apicurio/apicurio-registry-mem:2.4.14.Final
    ports:
      - '8443'
  artemis:
    environment:
      FOO: bar

then at build time, we will now generate the following file:

name: bank-quarkus
services:
  apicurio:
    image: apicurio/apicurio-registry-mem:2.4.14.Final    <============= append/override
    ports:
    - '8080'
    - '8443'      <============= append/override
  artemis:
    image: quay.io/arkmq-org/activemq-artemis-broker:artemis.2.40.0
    ports:
    - '61616'
    environment:
      AMQ_USER: admin
      AMQ_PASSWORD: admin
      AMQ_EXTRA_ARGS: --no-autotune --mapped --no-fsync
      FOO: bar               <============= append/override

in terms of implementation, we created:

public final class ComposeBuildItem extends MultiBuildItem {

    String yaml;

    Map<String, String> additionalResources = new HashMap<>();

    public ComposeBuildItem(String yaml) {
        this.yaml = yaml;
    }

    public Map<String, String> getAdditionalResources() {
        return additionalResources;
    }

    public String getYaml() {
        return yaml;
    }
}

some of our extensions will create ComposeBuildItem objects. For instance for kafka:

public class KafkaComposeProcessor {

    private static final Logger logger = LoggerFactory.getLogger(KafkaComposeProcessor.class);

    private static final String sh = """
            #!/bin/bash

            # Wait for the ports file to be created
            while [ ! -f /etc/kafka/docker/ports ]; do
              sleep 0.1;
            done;

            # Source the file to load PORT_* variables
            source /etc/kafka/docker/ports;

            # Use the port mappings
            export KAFKA_ADVERTISED_LISTENERS=PLAINTEXT://localhost:$PORT_9092;
            # Run the Kafka broker executable
            /etc/kafka/docker/run
            """;

    @BuildStep
    ComposeBuildItem compose() throws IOException {
        try (InputStream input = Thread.currentThread().getContextClassLoader().getResourceAsStream("kafka.template.yaml")) {
            String yaml = new String(Objects.requireNonNull(input).readAllBytes(), StandardCharsets.UTF_8);
            ComposeBuildItem item = new ComposeBuildItem(yaml);
            item.getAdditionalResources().put("kafka.sh", sh);
            return item;
        }
    }
}

we have also a src/main/resources/kafka.template.yaml, which is basically a copy of https://quarkus.io/guides/kafka#Compose

the final touch is a processor, which will process all ComposeBuildItem objects, generate target/compose/compose-devservices.yml, apply overrides if needed, and either copy file into ./ (local mode) or check for differences (CI).

this feature allows to use compose with some of the transparency used in dev services.
I am wondering if this could be a good fit for quarkus.
cc @cescoffier @ozangunalp

[cescoffier]

@ozangunalp WDYT?