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..eebd82a44 --- /dev/null +++ b/serverlessworkflow/modules/ROOT/pages/use-cases/advanced-developer-use-cases/getting-started/create-your-first-workflow-project.adoc @@ -0,0 +1,184 @@ += 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 in that purpose. + +We will also use Quarkus dev mode for iterative development and testing. + +As a common application development, we have different phases: Analysis, Development and Deployment. Let's explore in detail each phase and what {product_name} provides in each case: + +* <> +** <> +** <> +** <> +** <> + +* <> +** <> +** <> +** <> +* <> + + +.Prerequisites +* Java {java_min_version} is installed with `JAVA_HOME` configured appropriately. +* Apache Maven {maven_min_version} is installed. +* {quarkus_cli_url}[Quarkus CLI] or xref:testing-and-troubleshooting/kn-plugin-workflow-overview.adoc[Knative Workflow CLI] {kn_cli_version} is installed. +* Visual Studio Code with https://marketplace.visualstudio.com/items?itemName=redhat.java[Red Hat Java Extension] +and https://marketplace.visualstudio.com/items?itemName=redhat.vscode-extension-serverless-workflow-editor[Red Hat Serverless Workflow Editor] is installed to edit your workflows. + +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 and taking decisions phase + +In this phase the goal is to make some decisions about persistence, eventing, security,.. What needs to be the topology of our application and how the different components need to interact. + +[[proc-adding-persistence]] +=== Adding persistence? + +We need to decide if we need to ensure that your workflow instances remain consistent in the context. +When the persistence is not configured, an in-memory persistence is used, making all the {workflow_instance} information volatile upon runtime restarts. In this case if the workflow runtime is restarted. + +At this stage we need to decide what kind of persistence is needed and configure it properly. +You can find deeper explained it in {product_name} persistence xref:use-cases/advanced-developer-use-cases/persistence/persistence-core-concepts.adoc[] + +You can find more information about how to create an application which writes to and reads from a database at Quarkus guide link:https://quarkus.io/guides/getting-started-dev-services[Your second Quarkus application] +[[proc-adding-eventing]] +=== Adding eventing? + +Quarkus unifies reactive and imperative programming you can find it more explained in the Quarkus guide link:https://quarkus.io/guides/quarkus-reactive-architecture[Quarkus Reactive Architecture] + +In this phase we need to decide how the Event-Driven Architecture needs to be added to our project. We have different options here: + +* *Kafka Connector* for Reactive Messaging. xref:use-cases/advanced-developer-use-cases/event-orchestration/consume-producing-events-with-kafka.adoc[] +* *Knative* eventing. xref:use-cases/advanced-developer-use-cases/event-orchestration/consume-produce-events-with-knative-eventing.adoc[] + +When we choose how the different project components will communicate. 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 decision is if we need the {data_index_ref} service enabled to be able to index the {workflow_instance} information in order to be consumed from {product_name} tooling or just through a GraphQl endpoint. + +The {data_index_ref} service is available for this purpose. See xref:data-index/data-index-core-concepts.adoc[] for more details. + +Once we decide we want to index the data, we need to select how to integrate the service in our topology. Having different options like: + +* We can choose to have the data indexation service integrated directly in our application using the different xref:use-cases/advanced-developer-use-cases/data-index/data-index-quarkus-extension.adoc[]. +This allows just using the same Datasource as the application persistence without any extra service deployment. +** *{data_index_ref} persistence extension*. That persists the indexed data directly at the application Data source. +** *{data_index_ref} extension*. Allow to 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, we need to properly configure the communication between our new application and the 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 our {product_name} workflow needs some kind of temporary schedule, we will need to integrate the Job service. + +Once we decide we want a Job Service, we need to select how to integrate the service in our topology. Having different options like: + +* We can choose to have the Job service integrated directly in our {product_name} Quarkus application using xref:use-cases/advanced-developer-use-cases/job-service/quarkus-extensions.adoc[]. +* Explore how to integrate the Job service and define the interaction with our {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 + +After taking some decisions about the components we need to integrate in our project, we 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 in order to facilitate the developer to try the workflows during this development phase and refine them before going to deployment phase. +As an overview, we 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. +You can explore it in a detailed way following the {product_name} xref:use-cases/advanced-developer-use-cases/getting-started/create-your-first-workflow-service.adoc[] guide. + +[[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]] +=== Refine 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 we 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. We 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 899e3a217..124c047a4 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: