kie-kogito-docs-574 - Add prepare environment guide for sonataflow (#575

)

* 574 - Initial skeleton and learning environment guide

* 574 - Add preparing-environment.adoc and link it to getting started

* 574 - Add production environment.adoc, improve original ones

* 574 - improve the getting-started guide based on new additions

* 574 - add cluster startup into prepare-enevironment.adoc

* 574 - fix typos and links

* 574 - add nav.adoc and minor improvements

* 574 - fix link to production guide

* 574 - improve memory for minikube, add prereq to learning

* 574 - use prepare environment guides in quarkus getting started

* 574 - fix references to non quarkus getting-started-req

* 574 - fix getting-started-with-kn-cli guide

* 574 - Fix wrong tabs

* Update serverlessworkflow/modules/ROOT/pages/getting-started/learning-environment.adoc

Co-authored-by: Walter Medvedeo <[email protected]>

---------

Co-authored-by: Walter Medvedeo <[email protected]>

serverlessworkflow/antora.yml

@@ -58,6 +58,9 @@ asciidoc:
     kubernetes_version: 1.26
     openshift_version_min: 4.10
     openshift_version_max: 4.15
+    knative_version: 1.13
+    knative_serving_version: 1.13
+    knative_eventing_version: 1.13
     # only used in downstream
     operator_version: main
     # after TP1, change to Serverless Logic
@@ -131,3 +134,4 @@ asciidoc:
     data_index_ref: Data Index
     workflow_instance: workflow instance
     workflow_instances: workflow instances
+    sonataflow_devmode_devui_url: /q/dev/org.kie.kogito.kogito-quarkus-serverless-workflow-devui/

serverlessworkflow/modules/ROOT/nav.adoc

@@ -16,6 +16,10 @@
 // under the License.
 
 * xref:release_notes.adoc[Release notes]
+* Setup
+** xref:getting-started/learning-environment.adoc[]
+** xref:getting-started/preparing-environment.adoc[]
+** xref:getting-started/production-environment.adoc[]
 * Getting Started
 ** xref:getting-started/getting-familiar-with-our-tooling.adoc[]
 ** xref:getting-started/create-your-first-workflow-service-with-kn-cli-and-vscode.adoc[]

serverlessworkflow/modules/ROOT/pages/_common-content/getting-started-requirement-quarkus.adoc

@@ -0,0 +1,3 @@
+* A quarkus workflow project is created.
++
+For more information about creating a workflow project, see xref:use-cases/advanced-developer-use-cases/getting-started/create-your-first-workflow-service.adoc[Creating your first Serverless Workflow Java service].

serverlessworkflow/modules/ROOT/pages/_common-content/getting-started-requirement.adoc

@@ -1,3 +1,3 @@
 * A workflow project is created.
 +
-For more information about creating a workflow project, see xref:use-cases/advanced-developer-use-cases/getting-started/create-your-first-workflow-service.adoc[Creating your first Serverless Workflow Java service].
+For more information about creating a workflow project, see xref:getting-started/create-your-first-workflow-service-with-kn-cli-and-vscode.adoc[Creating your first workflow project].

serverlessworkflow/modules/ROOT/pages/getting-started/create-your-first-workflow-service-with-kn-cli-and-vscode.adoc

@@ -3,21 +3,8 @@
 This guide showcases using the Knative Workflow CLI plugin and Visual Studio code to create & run {product_name} projects.
 
 .Prerequisites
-* 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.vscode-extension-serverless-workflow-editor[Red Hat Serverless Workflow Editor] is installed to edit your workflows.
-
-.Preparing your environment for local development with locally deployed cluster instance
-* Install https://docs.docker.com/engine/install/[Docker] or https://podman.io/docs/installation[Podman].
-* Install https://minikube.sigs.k8s.io/docs/start/[minikube]
-* Install https://kubernetes.io/docs/tasks/tools/[kubectl].
-* Start minikube. Depending on your environment, set `--driver` flag to `podman` or `docker`
-[source,bash]
-----
-minikube start --cpus 4 --memory 8096 --addons registry --addons metrics-server --insecure-registry "10.0.0.0/24" --insecure-registry "localhost:5000"  --driver=docker
-----
-* (optional) Install https://k9scli.io/[k9scli.io] 
-* xref:cloud/operator/install-serverless-operator.adoc[]
-* Install https://github.com/kiegroup/kie-tools/releases/tag/{kn_cli_version}[SonataFlow plug-in for Knative CLI]. Follow xref:testing-and-troubleshooting/kn-plugin-workflow-overview.adoc[] guide.
+* You have setup your environment according xref:getting-started/preparing-environment.adoc#proc-minimal-local-environment-setup[minimal environment setup] guide.
+* Install https://k9scli.io/[k9scli.io] for easier inspection of your application resources in cluster. This is optional, you can use any tool you are fimiliar with in this regard. 
 
 [[proc-creating-app-with-kn-cli]]
 == Creating a workflow project with Visual Studio Code and KN CLI
@@ -60,25 +47,50 @@ To deploy the finished project to a local cluster, proceed to the next section.
 
 Use the `deploy` command with kn workflow to deploy the {product_name} project into your local cluster.
 
-* Deploy to minikube
+* Deploy to cluster
 [source,bash]
 ----
-kn workflow deploy
+kn workflow deploy --namespace my-sf-application
 ----
-* (Optional) Using k9scli you can examine your deployment.
-* In a different bash instance, create a port mapping:
-[source,bash]
+* Using k9s cli you can examine your deployment.
+* In a separate bash instance create a port mapping:
++
+[tabs]
+====
+Minikube::
++
+--
+[source,shell]
 ----
-minikube service hello --namespace default --url
+minikube service hello --namespace my-sf-application --url
 ----
 * Use this URL to access your workflow instances using the Developer UI
-** <RETURNED_URL>/q/dev/org.kie.kogito.kogito-quarkus-serverless-workflow-devui/workflowInstances
-* To update the image run the `deploy` again, note that this may take some time.
+** <RETURNED_URL>{sonataflow_devmode_devui_url}/workflowInstances
+--
+Kind::
++
+--
+[source,shell]
+----
+# Execute
+kubectl get services -n my-sf-application
 
+# You should see output like this, note the ports
+NAME         TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)            AGE
+hello        ClusterIP   10.96.0.1    <none>        <RANDOM_PORT>/80   39s
+
+# Execute
+kubectl port-forward service/hello <RANDOM_PORT>:80 -n my-sf-application
+
+----
+--
+====
+
+* To update the image run the `deploy` again, note that this may take some time.
 * To stop the deployment, use the `undeploy` command:
 [source,bash]
 ----
-kn worklow undeploy
+kn worklow undeploy --namespace my-sf-application
 ----
 * You can validate your pod is terminating using k9s cli.
 

serverlessworkflow/modules/ROOT/pages/getting-started/learning-environment.adoc

@@ -0,0 +1,20 @@
+= Learning environment
+
+.Prerequisites
+* Basic knowledge of cloud environments, containers, docker and Kubernetes
+* You are familiar with https://github.com/serverlessworkflow/specification/blob/0.8.x/specification.md[CNCF Serverless Workflow Specification 0.8]
+
+If you are new to {product_name} we recommend a few starting points to get up to speed with the technology and what it has to offer. 
+
+* Read the xref:core/cncf-serverless-workflow-specification-support.adoc[serverless workflow specification and what is supported]. 
+* Try our link:{serverless_logic_web_tools_url}/sample-catalog?category=serverless-workflow[{serverless_logic_web_tools_name} samples]. 
+
+Once familiar with the specification and samples, navigate to xref:getting-started/preparing-environment.adoc[] guide to complete the necesarry setup of your environment. After that, you should be ready to create your first {product_name} application.
+
+== Additional resources
+
+* xref:getting-started/preparing-environment.adoc[]
+* xref:getting-started/production-environment.adoc[]
+
+
+include::../../pages/_common-content/report-issue.adoc[]

serverlessworkflow/modules/ROOT/pages/getting-started/preparing-environment.adoc

@@ -0,0 +1,90 @@
+= Environment setup
+
+This guide lists the different ways to set up your environment for {product_name} development. 
+If you are new, start with the minimal one.
+
+[[proc-minimal-local-environment-setup]]
+== Minimal local environment setup
+
+Recommended steps to setup your local development environment. By completing these steps you are able to
+start the development on your local machine using our guides.
+
+.Procedure
+. Install https://docs.docker.com/engine/install/[Docker] or https://podman.io/docs/installation[Podman].
+. Install https://minikube.sigs.k8s.io/docs/start/[minikube] or https://kind.sigs.k8s.io/docs/user/quick-start/#installation[kind].
+. Install https://kubernetes.io/docs/tasks/tools/[Kubernetes CLI].
+. Install https://knative.dev/docs/install/quickstart-install/[Knative using quickstart]. This will also setup Knative Serving and Eventing for you and the cluster should be running.
+. xref:cloud/operator/install-serverless-operator.adoc[]
+. Install xref:testing-and-troubleshooting/kn-plugin-workflow-overview.adoc[Knative Workflow CLI].
+. Install https://code.visualstudio.com/[Visual Studio Code] with https://marketplace.visualstudio.com/items?itemName=kie-group.swf-vscode-extension[our extension] that simplifies development of workflows by provifing visual aids and auto-complete features.
+
+[[proc-starting-cluster-fo-local-development]]
+== Starting the cluster for local development
+
+If you have used https://knative.dev/docs/install/quickstart-install/[Knative using quickstart] guide, your selected cluster should be running and properly configured to work with our guides.
+
+Please note, that if the knative quickstart procedure is not used, you need to install Knative Serving and Eventing manually. See <<proc-additional-options-for-local-environment>>.
+
+
+.To startup the selected cluster without quickstart, use the following command:
+[tabs]
+====
+Minikube::
++
+--
+.Configure and startup minikube
+[source,shell]
+----
+# Set a driver and container runtime
+minikube config set driver docker/podman
+minikube config set container-runtime docker/podman
+
+# Set cpu and memory
+# 4096 is minimal baseline, increase to 6144 or 8192 if possible
+minikube config set cpus 4
+minikube config set memory 4096
+
+# Start the cluster
+minikube start --cpus 4 --memory 4096 --addons registry --addons metrics-server --insecure-registry "10.0.0.0/24" --insecure-registry "localhost:5000"
+
+# Set the active profile
+minikube profile minikube
+----
+--
+Kind::
++
+--
+.Start a kind cluster
+[source,shell]
+----
+kind create cluster
+----
+--
+====
+
+[[proc-advanced-local-environment-setup]]
+== Advanced local environment setup
+
+If you are interested in our Java and Quarkus development path, consider completing this procedure in addition to the
+<<proc-minimal-local-environment-setup>>. By completing these steps you are able to start the development of applications on your local machine using our xref:use-cases/advanced-developer-use-cases/index.adoc[advanced developer guides].
+
+.Procedure
+. Install https://openjdk.org/[OpenJDK] {java_min_version} and cofigure `JAVA_HOME` appropriately by adding it to the `PATH`.
+. Install https://maven.apache.org/index.html[Apache Maven] {maven_min_version}.
+. Install https://quarkus.io/guides/cli-tooling[Quarkus CLI] corresponding to currently supported version by {product_name}. Currently it is {quarkus_version}.
+
+[[proc-additional-options-for-local-environment]]
+== Additional options for local environment setup
+
+Points listed in this section provide extra posibilties when working with our guides and are considered optional.
+
+* Install https://www.graalvm.org/[GraalVM] {graalvm_min_version}. This will allow you to create https://www.graalvm.org/22.0/reference-manual/native-image/[native image] of your {product_name} application.
+* Install https://knative.dev/docs/install/yaml-install/serving/install-serving-with-yaml/[Knative Serving using YAML files] for advanced customizations or in cases where the quickstart procedure fails.
+* Install https://knative.dev/docs/install/yaml-install/eventing/install-eventing-with-yaml/[Knative Eventing using YAML files] for advanced customizations or in cases where the quickstart procedure fails.
+
+== Additional resources
+
+* xref:getting-started/production-environment.adoc[]
+* xref:getting-started/create-your-first-workflow-service-with-kn-cli-and-vscode.adoc[]
+
+include::../../pages/_common-content/report-issue.adoc[]

serverlessworkflow/modules/ROOT/pages/getting-started/production-environment.adoc

@@ -0,0 +1,13 @@
+= Production environment
+
+In thise guide, you can find {product_name} recommendations and best-practices for production environment.
+
+`NOTE: Guide is not complete and under construction. For now, please explore the cloud chapters linked in the additional resources section.`
+
+Are you using {product_name} in production? Let us know how so that we can expand our test suites!
+
+== Additional resources
+
+* xref:cloud/index.adoc[]
+
+include::../../pages/_common-content/report-issue.adoc[]

serverlessworkflow/modules/ROOT/pages/index.adoc

@@ -8,6 +8,33 @@
 
 You can learn how to create, manage, and deploy your workflow applications with the following guides.
 
+[.card-section]
+== Setup
+
+[.card]
+--
+[.card-title]
+xref:getting-started/learning-environment.adoc[]
+[.card-description]
+Learn about the recommended environment to start your journey with {product_name} applications
+--
+
+[.card]
+--
+[.card-title]
+xref:getting-started/preparing-environment.adoc[]
+[.card-description]
+An all-in-one guide to prepare you environment for you to be uncover the full potential of {product_name} guides on your local environment.
+--
+
+[.card]
+--
+[.card-title]
+xref:getting-started/production-environment.adoc[]
+[.card-description]
+Learn about the best practices and recommendations for production environments.
+--
+
 [.card-section]
 == Getting started
 

serverlessworkflow/modules/ROOT/pages/use-cases/advanced-developer-use-cases/getting-started/build-workflow-image-with-quarkus-cli.adoc

@@ -9,27 +9,18 @@
 :google_jib_url: https://github.com/GoogleContainerTools/jib
 :kogito_sw_examples_git_repo_url: https://github.com/apache/incubator-kie-kogito-examples.git
 
-This document describes how to build a Serverless Application Container image using the link:{quarkus_cli_url}[Quarkus CLI].
+This document describes how to build a {product_name} container image using the link:{quarkus_cli_url}[Quarkus CLI].
 
 .Prerequisites
-include::./../../../../pages/_common-content/getting-started-requirement.adoc[]
-* Latest version of Docker is installed. Alternatively, you can use link:{google_jib_url}[Jib] to build container images. However, Docker is required to build GraalVM native image using the Quarkus native builder image.
-* Optionally, GraalVM {graalvm_min_version} is installed.
+include::./../../../../pages/_common-content/getting-started-requirement-quarkus.adoc[]
+* You have setup your environment according to xref:getting-started/preparing-environment.adoc#proc-advanced-local-environment-setup[advanced environment setup] guide and you cluster is ready.
+* Optionally, GraalVM {graalvm_min_version} is installed. See xref:getting-started/preparing-environment.adoc#proc-additional-options-for-local-environment[]
 
 Quarkus provides a few extensions to build container images, such as `Jib`, `docker`, `s2i`, and `buildpacks`. For more information about the Quarkus extensions, see the link:{quarkus_container_images_url}[Quarkus documentation].
 
-The examples in this document assume that you have the Quarkus tooling installed. For more information about the tooling, see xref:getting-started/getting-familiar-with-our-tooling.adoc[Getting familiar with {product_name} tooling].
-
 [[proc-building-serverless-workflow-application]]
 == Building the workflow application
 
-After installing the required tooling, you can start building your workflow application.
-
-.Prerequisites
-* You have created a Quarkus project.
-* Quarkus CLI is installed. 
-For more information about installing the Quarkus CLI, see link:{quarkus_cli_url}#installing-the-cli[Installing the Quarkus CLI].
-
 .Procedure
 . In a command terminal, navigate to your Quarkus project.
 . To build your workflow application on Quarkus, set the `quarkus.container-image.build` property value to `true` and run the following command:
@@ -70,7 +61,7 @@ The added Jib extension caches the `target/lib` directory. Based on the size of
 [source,shell]
 ----
 quarkus build -Dquarkus.container-image.build=true \
-    -Dquarkus.container-image.group=kogito \
+    -Dquarkus.container-image.group=sonataflow \
     -Dquarkus.container-image.name=serverless-workflow-greeting-quarkus \
     -Dquarkus.container-image.tag=1.0 \
     -Dquarkus.container-image.registry=quay.io \
@@ -79,7 +70,7 @@ quarkus build -Dquarkus.container-image.build=true \
 +
 The previous command results in the following container image pushed to `quay.io`:
 +
-`quay.io/kogito/serverless-workflow-greeting-quarkus:1.0`
+`quay.io/sonataflow/serverless-workflow-greeting-quarkus:1.0`
 
 . Alternatively, you can create an Apache Maven profile to build the container image, which can be triggered by setting the target profile.
 +
@@ -114,11 +105,6 @@ You can activate the created Apache Maven profile using Quarkus CLI:
 
 When it comes to workflows, a small startup footprint is expected, which can be better when using the native builds to build a workflow application.
 
-.Prerequisites
-* You have created a Quarkus project.
-* Quarkus CLI is installed. 
-For more information about installing the Quarkus CLI, see link:{quarkus_cli_url}[Installing the Quarkus CLI].
-
 .Procedure
 . In a command terminal, navigate to your Quarkus project.
 . To build a native image, pass the `--native` flag using Quarkus CLI:

serverlessworkflow/modules/ROOT/pages/use-cases/advanced-developer-use-cases/getting-started/create-your-first-workflow-service.adoc

@@ -18,11 +18,7 @@ This document describes how to create a workflow application that serves a `hell
 image::getting-started/hello-world-workflow.png[]
 
 .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.
+* You have setup your environment according to xref:getting-started/preparing-environment.adoc#proc-advanced-local-environment-setup[advanced environment setup] guide and you cluster is ready.
 
 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].