KOGITO-5508 Data Index Dev Service

docs/src/main/asciidoc/dev-services.adoc

@@ -68,6 +68,12 @@ link:security-openid-connect-dev-services[OIDC Dev Services Guide].
 :no-duration-note: true
 include::{generated-dir}/config/quarkus-keycloak-devservices-keycloak-keycloak-build-time-config.adoc[opts=optional, leveloffset=+1]
 
+== Kogito
+
+The Kogito Dev Service will be enabled when either `kogito-quarkus` or `kogito-quarkus-processes` extension is present in your application. More information can be found at the link:kogito-dev-services[Kogito Dev Services Guide].
+
+include::kogito-dev-services-build-time-config.adoc[opts=optional, leveloffset=+1]
+
 == MongoDB
 
 The MongoDB Dev Service will be enabled when the `quarkus-mongodb-client` extension is present in your application, and

docs/src/main/asciidoc/kogito-dev-services-build-time-config.adoc

@@ -0,0 +1,54 @@
+[.configuration-legend]
+icon:lock[title=Fixed at build time] Configuration property fixed at build time - All other configuration properties are overridable at runtime
+[.configuration-reference, cols="80,.^10,.^10"]
+|===
+
+h|[[quarkus-kogito-dev-services-build-time-config_configuration]]link:#quarkus-kogito-dev-services-build-time-config_configuration[Configuration property]
+
+h|Type
+h|Default
+
+a|icon:lock[title=Fixed at build time] [[quarkus-kogito-dev-services-build-time-config_quarkus.kogito.devservices.enabled]]`link:#quarkus-kogito-dev-services-build-time-config_quarkus.kogito.devservices.enabled[quarkus.kogito.devservices.enabled]`
+
+[.description]
+--
+If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present. When DevServices is enabled Quarkus will attempt to automatically configure and start a Data Index when running in Dev mode.
+--|boolean
+|true
+
+
+a|icon:lock[title=Fixed at build time] [[quarkus-kogito-dev-services-build-time-config_quarkus.kogito.devservices.image-name]]`link:#quarkus-kogito-dev-services-build-time-config_quarkus.kogito.devservices.image-name[quarkus.kogito.devservices.image-name]`
+
+[.description]
+--
+The container image name to use.
+--|string
+|quay.io/kiegroup/kogito-data-index-ephemeral
+
+
+a|icon:lock[title=Fixed at build time] [[quarkus-kogito-dev-services-build-time-config_quarkus.kogito.devservices.port]]`link:#quarkus-kogito-dev-services-build-time-config_quarkus.kogito.devservices.port[quarkus.kogito.devservices.port]`
+
+[.description]
+--
+Optional fixed port the dev service will listen to.
+If not defined, the port will be chosen randomly.
+--|int
+|8180
+
+a|icon:lock[title=Fixed at build time] [[quarkus-kogito-dev-services-build-time-config_quarkus.kogito.devservices.shared]]`link:#quarkus-kogito-dev-services-build-time-config_quarkus.kogito.devservices.shared[quarkus.kogito.devservices.shared]`
+
+[.description]
+--
+Indicates if the Data Index instance managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for Kogito starts a new container. The discovery uses the `kogito-dev-service-data-index` label. The value is configured using the service-name property. Container sharing is only used in dev mode.
+--|boolean
+|true
+
+a|icon:lock[title=Fixed at build time] [[quarkus-kogito-dev-services-build-time-config_quarkus.kogito.devservices.service-name]]`link:#quarkus-kogito-dev-services-build-time-config_quarkus.kogito.devservices.service-name[quarkus.kogito.devservices.service-name]`
+
+[.description]
+--
+The value of the `kogito-dev-service-data-index` label attached to the started container. This property is used when shared is set to true. In this case, before starting a container, Dev Services for Kogito looks for a container with the `kogito-dev-service-data-index` label set to the configured value. If found, it will use this container instead of starting a new one. Otherwise it starts a new container with the `kogito-dev-service-data-index` label set to the specified value. This property is used when you need multiple shared Data Index instances.
+--|string
+|kogito-data-index
+
+|===

docs/src/main/asciidoc/kogito-dev-services.adoc

@@ -0,0 +1,65 @@
+////
+This guide is maintained in the main Quarkus repository
+and pull requests should be submitted there:
+https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
+////
+= Dev Services for Kogito
+
+include::./attributes.adoc[]
+
+If any Kogito process-related extension is present (e.g. `kogito-quarkus` or `kogito-quarkus-processes`), Dev Services for Kogito automatically starts a Data Index in dev mode.
+So, you don't have to start it manually or have any other service set-up manually.
+The application is configured automatically, meaning that will replicate any
+Kogito messaging events related to Process Instances and User Tasks into the provisioned Data Index instance.
+
+Additionally, link:dev-ui[Dev UI] available at http://localhost:8080/q/dev[/q/dev] complements this feature with a Dev UI page which helps to Query Data Index via its GraphiQL UI.
+
+image::dev-ui-kogito-data-index-card.png[alt=Dev UI Kogito,role="center"]
+
+image::dev-ui-kogito-data-index.png[alt=Dev UI Kogito Data Index GraphiQL,role="center"]
+
+For more details about how to query data about processes and user tasks, please visit https://docs.kogito.kie.org/latest/html_single/#ref-data-index-service-queries_kogito-configuring[Kogito Data Index documentation].
+
+== Enabling / Disabling Dev Services for Kogito
+
+Dev Services for Kogito is automatically enabled unless:
+
+- `quarkus.kogito.devservices.enabled` is set to `false`
+
+Dev Services for Kogito relies on Docker to start the broker.
+If your environment does not support Docker, you will need to start the broker manually, or connect to an already running Data Index.
+
+== Shared Data Index
+
+In case you would like to share the Data Index instance between applications.
+Dev Services for Kogito implements a _service discovery_ mechanism for your multiple Quarkus applications running in _dev_ mode to share a single instance.
+
+NOTE: Dev Services for Kogito starts the container with the `kogito-dev-service-data-index` label which is used to identify the container.
+
+If you need multiple (shared) Data Index instances, you can configure the `quarkus.kogito.devservices.service-name` attribute and indicate the instance name.
+It looks for a container with the same value, or starts a new one if none can be found.
+The default service name is `kogito-data-index`.
+
+Sharing is enabled by default in dev mode.
+You can disable the sharing with `quarkus.kogito.devservices.shared=false`.
+
+== Setting the port
+
+By default, Dev Services for Kogito starts a Data Index using port 8180.
+You can set the port by configuring the `quarkus.kogito.devservices.port` property.
+
+== Configuring the image
+
+Dev Services for Kogito uses: `kiegroup/kogito-data-index-ephemeral` images.
+You can select any version from https://quay.io/repository/kiegroup/kogito-data-index-ephemeral?tab=tags.
+
+[source, properties]
+----
+quarkus.kogito.devservices.image-name=quay.io/kiegroup/kogito-data-index-ephemeral
+----
+
+== References
+
+* link:dev-ui[Dev UI]
+* https://docs.kogito.kie.org/latest/html_single/[Kogito Documentation]
+* link:kogito.adoc[Quarkus - Kogito]

docs/src/main/asciidoc/kogito.adoc

@@ -44,7 +44,7 @@ You can reference to https://kiegroup.github.io/kogito-online/#/download[Busines
 * Eclipse
 
 To be able to make use of visual modelling of your processes, download Eclipse IDE and
-install from Market place Eclipse BPMN2 Modeller plugin (with jBPM Runtime Extension)
+install from Marketplace Eclipse BPMN2 Modeller plugin (with jBPM Runtime Extension)
 
 == Architecture
 
@@ -478,3 +478,4 @@ Once the dependency is added to the project, decision tables in `xls` or `xlsx`
 
 * https://kogito.kie.org[Kogito Website]
 * https://docs.jboss.org/kogito/release/latest/html_single[Kogito Documentation]
+* link:kogito-dev-services.adoc[Kogito Dev Services]