kie-kogito-docs-574 - Add prepare environment guide for sonataflow

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/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,25 @@ 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-sonataflow-application
 ----
-* (Optional) Using k9scli you can examine your deployment.
+* Using k9s cli you can examine your deployment.
 * In a different bash instance, create a port mapping:
 [source,bash]
 ----
-minikube service hello --namespace default --url
+minikube service hello --namespace my-sonataflow-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
+** <RETURNED_URL>{sonataflow_devmode_devui_url}{workflow_instances}
 * 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-sonataflow-application
 ----
 * You can validate your pod is terminating using k9s cli.
 

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

@@ -0,0 +1,16 @@
+= Learning environment
+
+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 link: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,88 @@
+= 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
+
+Recomennded 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
+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
+
+* 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