-
Notifications
You must be signed in to change notification settings - Fork 59
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
KOGITO-9458: Create the detailed guide about running a quarkus workfl…
…ow project
- Loading branch information
Showing
4 changed files
with
191 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
184 changes: 184 additions & 0 deletions
184
...ced-developer-use-cases/getting-started/create-your-first-workflow-project.adoc
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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: | ||
|
|
||
| * <<proc-analysis-phase,Analysis and taking decisions phase>> | ||
| ** <<proc-adding-persistence,Adding persistence?>> | ||
| ** <<proc-adding-eventing,Adding eventing?>> | ||
| ** <<proc-adding-data-index-service,Adding Data Index service?>> | ||
| ** <<proc-adding-job-service,Adding Job service?>> | ||
| * <<proc-development-phase,Development phase>> | ||
| ** <<proc-boostrapping-the-project,Bootstrapping a project, Creating a workflow, Running your workflow application and Testing your workflow application >> | ||
| ** <<proc-logging-configuration,How to configure logging>> | ||
| ** <<proc-dev-ui, Refine your workflow testing with Dev-UI>> | ||
| * <<proc-deployment-phase,Deployment phase>> | ||
| .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 >> | ||
| ** <<proc-logging-configuration,How to configure logging>> | ||
| ** <<proc-dev-ui,Refine your workflow testing with Dev-UI>> | ||
|
|
||
| [[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[] | ||
|
|
2 changes: 1 addition & 1 deletion
2
...ced-developer-use-cases/getting-started/create-your-first-workflow-service.adoc
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters