diff --git a/serverlessworkflow/antora.yml b/serverlessworkflow/antora.yml index 58ae25030..fc79037ae 100644 --- a/serverlessworkflow/antora.yml +++ b/serverlessworkflow/antora.yml @@ -93,9 +93,14 @@ asciidoc: kie_tools_releases_page_url: https://github.com/apache/incubator-kie-tools/releases quarkus_guides_base_url: https://quarkus.io/guides quarkus_guides_kafka_url: https://quarkus.io/guides/kafka + quarkus_guides_building_native: https://quarkus.io/guides/building-native-image quarkus_guides_config_reference_url: https://quarkus.io/guides/config-reference + quarkus_guides_container_image_url: https://quarkus.io/guides/container-image + quarkus_guides_dev_services: https://quarkus.io/guides/getting-started-dev-services quarkus_guides_infinispan_client_reference_url: https://quarkus.io/guides/infinispan-client-reference + quarkus_guides_logging_url: https://quarkus.io/guides/logging quarkus_guides_profiles_url: https://quarkus.io/guides/config-reference#profiles + quarkus_guides_swaggerui_url: https://quarkus.io/guides/openapi-swaggerui quarkus_url: https://quarkus.io/ dev_services_url: https://quarkus.io/guides/dev-services test_containers_url: https://www.testcontainers.org/ diff --git a/serverlessworkflow/modules/ROOT/nav.adoc b/serverlessworkflow/modules/ROOT/nav.adoc index 1a210603c..d3e77ff8b 100644 --- a/serverlessworkflow/modules/ROOT/nav.adoc +++ b/serverlessworkflow/modules/ROOT/nav.adoc @@ -96,6 +96,7 @@ ** xref:use-cases/advanced-developer-use-cases/index.adoc[Advanced Development Use Cases of {product_name} applications using Quarkus and Java] *** Getting started **** xref:use-cases/advanced-developer-use-cases/getting-started/create-your-first-workflow-service.adoc[] +**** xref:use-cases/advanced-developer-use-cases/getting-started/create-your-first-workflow-project.adoc[] **** xref:use-cases/advanced-developer-use-cases/getting-started/build-workflow-image-with-quarkus-cli.adoc[] **** xref:use-cases/advanced-developer-use-cases/getting-started/working-with-serverless-workflow-quarkus-examples.adoc[] **** xref:use-cases/advanced-developer-use-cases/getting-started/test-serverless-workflow-quarkus-examples.adoc[] diff --git a/serverlessworkflow/modules/ROOT/pages/use-cases/advanced-developer-use-cases/getting-started/create-your-first-workflow-project.adoc b/serverlessworkflow/modules/ROOT/pages/use-cases/advanced-developer-use-cases/getting-started/create-your-first-workflow-project.adoc new file mode 100644 index 000000000..36a31630d --- /dev/null +++ b/serverlessworkflow/modules/ROOT/pages/use-cases/advanced-developer-use-cases/getting-started/create-your-first-workflow-project.adoc @@ -0,0 +1,187 @@ += Creating a Quarkus Workflow project + +As a developer, you can use {product_name} to create an application and in this guide we want to explore different options and provide an overview of available tools that can help. + +We will also use Quarkus dev mode for iterative development and testing. + +As a common application development, you have different phases like Analysis, Development and Deployment. Let's explore in detail each phase and what {product_name} provides in each case: + +* <> +** <> +** <> +** <> +** <> + +* <> +** <> +** <> +** <> +* <> + + +.Prerequisites +* You have set up your environment according to the xref:getting-started/preparing-environment.adoc#proc-advanced-local-environment-setup[advanced environment setup] guide. + +For more information about the tooling and the required dependencies, see xref:getting-started/getting-familiar-with-our-tooling.adoc[Getting familiar with {product_name} tooling]. + +ifeval::["{kogito_version_redhat}" != ""] +include::../../pages/_common-content/downstream-project-setup-instructions.adoc[] +endif::[] + + +[[proc-analysis-phase]] +== Analysis phase + +Start by analyzing the requirements for your {product_name} application. This will enable you to make decisions about the persistence, eventing, security, topology, and component interaction needs of your application. + +[[proc-adding-persistence]] +=== Adding persistence +Service orchestration is a relevant use case regarding the rise of microservices and event-driven architectures. These architectures focus on communication between services and there is always the need to coordinate that communication without the persistence addition requirement. + +{product_name} applications use an in-memory persistence by default. This makes all the {workflow_instance} information volatile upon runtime restarts. In the case of this guide, when the workflow runtime is restarted. +As a developer, you must decide if you need to ensure that your workflow instances remain consistent in the context. + +If your application requires persistence, you must decide what kind of persistence is needed and configure it properly. +Follow the {product_name} xref:use-cases/advanced-developer-use-cases/persistence/persistence-core-concepts.adoc[persistence guide] for more information. + +You can find more information about how to create an application that writes to and reads from a database following link:https://quarkus.io/guides/getting-started-dev-services[Your second Quarkus application] guide. + +[[proc-adding-eventing]] +=== Adding eventing + +Quarkus unifies reactive and imperative programming you can find more information about this in the link:https://quarkus.io/guides/quarkus-reactive-architecture[Quarkus Reactive Architecture] guide. + +In this phase, we must decide how the Event-Driven Architecture needs to be added to our project. +As an event-driven architecture, it uses events to trigger and communicate between services. It allows decoupled applications to publish and subscribe to events through an event broker asynchronously. The event-driven architecture is a method of developing systems that allows information to flow in real time between applications, microservices, and connected devices. + +This means that applications and devices do not need to know where they are sending information or where the information they are consuming comes from. + +If we choose to add eventing, {product_name} supports different options like: + +* *Kafka Connector* for Reactive Messaging. See xref:use-cases/advanced-developer-use-cases/event-orchestration/consume-producing-events-with-kafka.adoc[] for more details. +* *Knative* eventing. See xref:use-cases/advanced-developer-use-cases/event-orchestration/consume-produce-events-with-knative-eventing.adoc[] for more details. + +You must choose how the different project components will communicate and what kind of communication is needed. More details about link:https://quarkus.io/guides/quarkus-reactive-architecture#quarkus-extensions-enabling-reactive[Quarkus Extensions enabling Reactive] + +[[proc-adding-data-index-service]] +=== Adding Data Index service + +The {data_index_ref} service can index the {workflow_instance} information using GraphQL. This is very useful if you want to consume the workflow data in different applications through a GraphQL endpoint. +For more information about {data_index_ref} service see xref:data-index/data-index-core-concepts.adoc[] for more details. + +If you decide to index the data, you must select how to integrate the {data_index_ref} service in your topology. Here are some options: + +* You can choose to have the data indexation service integrated directly into our application using the different xref:use-cases/advanced-developer-use-cases/data-index/data-index-quarkus-extension.adoc[]. +This allows you to use the same data source as the application persistence uses, without the need for extra service deployment. +** *{data_index_ref} persistence extension*. That persists the indexed data directly at the application data source. +** *{data_index_ref} extension*. That persist directly the indexed data at the application data source and also provide the GraphQL endpoint to interact with the persisted data. +* Another option is to have the Data Index as a standalone service. In this case, you must properly configure the communication between your {product_name} application and the {data_index_ref} service. More details in xref:data-index/data-index-service.adoc[] + + +[[proc-adding-job-service]] +=== Adding Job service + +The Job Service facilitates the scheduled execution of tasks in a cloud environment. If any of your {product_name} workflow needs some kind of temporary schedule, you will need to integrate the Job service. + +If you decide to use Job Service, you need to select how to integrate the service into your topology. Here are some options: + +* You can choose to have the Job service integrated directly into your {product_name} Quarkus application using xref:use-cases/advanced-developer-use-cases/job-service/quarkus-extensions.adoc[] guide. +* Explore how to integrate the Job service and define the interaction with your {product_name} application workflows. You can find more Job service-related details in xref:job-services/core-concepts.adoc[Job Service Core concepts]. + +[[proc-development-phase]] +== Development phase + +Once you decide which components you must integrate into {product_name} project, you can jump into the workflow development phase. + +The goal is to create a workflow and be able to test and improve it. {product_name} provides some tooling to facilitate the developer to try the workflows during this development phase and refine them before going to the deployment phase. +As an overview, you have the following resources to help in this development phase: + +** <> +** <> +** <> + +[[proc-boostrapping-the-project]] +=== Bootstrapping a project, Creating a workflow, Running your workflow application and Testing your workflow application + +To create your workflow service, first you need to bootstrap a project. +Follow the {product_name} xref:use-cases/advanced-developer-use-cases/getting-started/create-your-first-workflow-service.adoc[] guide to setup a minimal working project. + +[[proc-logging-configuration]] +=== How to configure logging + +In order to understand what's happening in the environment. {product_name} is using Quarkus Log Management. Logs can provide a detailed history of what happened leading up to the issue. + +Quarkus uses the JBoss Log Manager logging backend for publishing application and framework logs. +Quarkus supports the JBoss Logging API and multiple other logging APIs, seamlessly integrated with JBoss Log Manager +In order to be able to see the in detail access to link:{quarkus_guides_logging_url}[Quarkus Logging Configuration guide] + +.Example adding Logging configuration properties in `application.properties` file +[source,properties] +---- +quarkus.log.console.enable=true <1> +quarkus.log.level=INFO <2> +quarkus.log.category."org.apache.kafka.clients".level=INFO +quarkus.log.category."org.apache.kafka.common.utils".level=INFO <3> +---- +<1> If console logging should be enabled, even by default is set to true +<2> The log level of the root category, which is used as the default log level for all categories +<3> Logging is configured on a per-category basis, with each category being configured independently. Configuration for a category applies recursively to all subcategories unless there is a more specific subcategory configuration + +[NOTE] +==== +Access to link:{quarkus_guides_logging_url}#loggingConfigurationReference[Logging configuration reference] to see how logs properties can be configured +==== + +[[proc-dev-ui]] +=== Refining your workflow testing with Dev-UI + +Quarkus provides a host of features when dev mode is enabled allowing things like: + +* *Change configuration values*. +* *Running Development services*, including Zero-config setup of data sources. When testing or running in dev mode Quarkus can even provide you with a zero config database out of the box, a feature we refer to as Dev Services. More information can be found in link:{quarkus_guides_logging_url}#dev-services[Quarkus introduction to Dev services]. +* *Access to Swagger-UI* that allows exploring the different {product_name} application endpoints. The quarkus-smallrye-openapi extension will expose the Swagger UI when Quarkus is running in dev mode. Additional information can be found link:{quarkus_guides_swaggerui_url}#dev-mode[Use Swagger UI for development]. +* *Data index Graph UI* that allows to perform GraphQL queries or to explore the data schema +* Allow to *explore the {workflow_instances}* if the {product_name} Runtime tools Quarkus Dev UI is included + +[NOTE] +==== +By default, Swagger UI is only available when Quarkus is started in dev or test mode. + +If you want to make it available in production too, you can include the following configuration in your application.properties: + +``` +quarkus.swagger-ui.always-include=true +``` +This is a build time property, it cannot be changed at runtime after your application is built. +==== + +[[proc-deployment-phase]] +== Deployment phase + +At this stage you have a {product_name} Quarkus application well tested and ready to be deployed. + +There are two basic modes that a Quarkus application can be deployed: + +* As an standard Java application (executable jar with libraries on the classpath) +* As a native executable which can be built using GraalVM link:{quarkus_guides_building_native}#producing-a-native-executable[Quarkus Building a native executable guide] + +If you put either the Java application or the native executable app inside a container, you can deploy the container anywhere that supports running containers. + +Quarkus provides extensions for building (and pushing) container images. +You can find more details about that container images generation in link:{quarkus_guides_container_image_url}[Quarkus Container Image extensions] + +Once this container image is built it can be used as part of the decided topology. You have different options like: + +* xref:use-cases/advanced-developer-use-cases/deployments/deploying-on-minikube.adoc[] +* xref:use-cases/advanced-developer-use-cases/deployments/deploying-on-kubernetes.adoc[] +* xref:use-cases/advanced-developer-use-cases/deployments/deploying-on-openshift.adoc[] + +== Additional resources + +* xref:getting-started/getting-familiar-with-our-tooling.adoc[Getting familiar with {product_name} tooling] +* xref:service-orchestration/orchestration-of-openapi-based-services.adoc[Orchestrating the OpenAPI services] +* xref:use-cases/advanced-developer-use-cases/event-orchestration/newsletter-subscription-example.adoc[] +* xref:use-cases/advanced-developer-use-cases/timeouts/timeout-showcase-example.adoc[] + +include::../../../../pages/_common-content/report-issue.adoc[] + diff --git a/serverlessworkflow/modules/ROOT/pages/use-cases/advanced-developer-use-cases/getting-started/create-your-first-workflow-service.adoc b/serverlessworkflow/modules/ROOT/pages/use-cases/advanced-developer-use-cases/getting-started/create-your-first-workflow-service.adoc index ed51dc422..9d8e27cf5 100644 --- a/serverlessworkflow/modules/ROOT/pages/use-cases/advanced-developer-use-cases/getting-started/create-your-first-workflow-service.adoc +++ b/serverlessworkflow/modules/ROOT/pages/use-cases/advanced-developer-use-cases/getting-started/create-your-first-workflow-service.adoc @@ -1,4 +1,4 @@ -= Creating a Quarkus Workflow Project += Creating a Quarkus Workflow service As a developer, you can use {product_name} and create a `Hello World` application, which includes the following procedures: