redhat-developer · jmagak · Nov 25, 2025 · Nov 25, 2025 · Nov 25, 2025 · Nov 25, 2025
diff --git a/assemblies/assembly-building-and-deploying-serverless-workflows.adoc b/assemblies/assembly-building-and-deploying-serverless-workflows.adoc
@@ -42,4 +42,7 @@ include::modules/orchestrator/proc-building-the-01-basic-workflow.adoc[leveloffs
 include::modules/orchestrator/con-generated-workflow-manifests.adoc[leveloffset=+1]
 
 // deploy workflows on a cluster
-include::modules/orchestrator/proc-deploying-workflows-on-a-cluster.adoc[leveloffset=+1]
+include::modules/orchestrator/proc-deploying-workflows-on-a-cluster.adoc[leveloffset=+1]
+
+// best practices when creating workflows
+include::modules/orchestrator/ref-best-practices-for-creating-workflows.adoc[leveloffset=+1]
diff --git a/assemblies/assembly-install-rhdh-orchestrator-helm.adoc b/assemblies/assembly-install-rhdh-orchestrator-helm.adoc
@@ -0,0 +1,21 @@
+:_mod-docs-content-type: ASSEMBLY
+
+ifndef::context[]
+[id="install-rhdh-orchestrator-helm.adoc"]
+endif::[]
+ifdef::context[]
+[id="assembly-install-rhdh-orchestrator-helm"]
+endif::[]
+:context: install-rhdh-orchestrator
+= Installing {product} with Orchestrator by using the {product} Helm chart
+
+You can install {product} with Orchestrator by using the {product} Helm chart.
+
+include::modules/orchestrator/proc-install-rhdh-with-orchestrator-helm-cli.adoc[leveloffset=+1]
+
+include::modules/orchestrator/proc-install-rhdh-with-orchestrator-helm-webui.adoc[leveloffset=+1]
+
+include::modules/orchestrator/ref-orchestrator-resource-limits.adoc[leveloffset=+1]
+
+// manual installation
+include::modules/orchestrator/proc-manual-install-components-orchestrator-plugin.adoc[leveloffset=+1]
diff --git a/assemblies/assembly-install-rhdh-orchestrator-operator.adoc b/assemblies/assembly-install-rhdh-orchestrator-operator.adoc
@@ -0,0 +1,16 @@
+:_mod-docs-content-type: ASSEMBLY
+
+ifndef::context[]
+[id="install-rhdh-orchestrator-operator"]
+endif::[]
+ifdef::context[]
+[id="assembly-install-rhdh-orchestrator-operator"]
+endif::[]
+:context: install-rhdh-orchestrator
+= Installing {product} with Orchestrator by using the {product} Operator
+
+You can install {product} with Orchestrator by using the {product} Operator.
+
+include::modules/orchestrator/proc-enable-orchestrator-plugin.adoc[leveloffset=+1]
+
+include::modules/orchestrator/proc-upgrading-the-orchestrator-plugin.adoc[leveloffset=+1]
diff --git a/assemblies/assembly-install-rhdh-orchestrator.adoc b/assemblies/assembly-install-rhdh-orchestrator.adoc
diff --git a/assemblies/assembly-orchestrator-plugins-components.adoc b/assemblies/assembly-orchestrator-plugins-components.adoc
@@ -0,0 +1,8 @@
+:_mod-docs-content-type: ASSEMBLY
+
+[id="assembly-orchestrator-plugins-components_{context}"]
+
+= Enabling Orchestrator plugins components
+
+// enabling orchestrator plugins components
+include::modules/orchestrator/proc-enabling-orchestrator-plugins-components.adoc[leveloffset=+1]
diff --git a/assemblies/assembly-orchestrator-plugins-technical-appendixes.adoc b/assemblies/assembly-orchestrator-plugins-technical-appendixes.adoc
@@ -0,0 +1,10 @@
+:_mod-docs-content-type: ASSEMBLY
+
+[id="assembly-orchestrator-plugins-technical-appendixes_{context}"]
+
+= Technical appendix
+
+The following appendix provides technical information, and details on non-production tools, such as the {product-very-short} helper script, which might be helpful for understanding setup options or quick testing.
+
+// {product-very-short} helper script
+include::modules/orchestrator/proc-helper-script-overview.adoc[leveloffset=+1]
diff --git a/assemblies/assembly-orchestrator-rhdh.adoc → ...ies/assembly-rhdh-about-orchestrator.adoc b/assemblies/assembly-orchestrator-rhdh.adoc → ...ies/assembly-rhdh-about-orchestrator.adoc
@@ -20,31 +20,14 @@ You can streamline and automate your work by using the Orchestrator in {product}
 Orchestrator currently supports only {ocp-brand-name} ({ocp-short}); it is not available on {aks-brand-name} ({aks-short}), {eks-brand-name} ({eks-short}), or {gke-brand-name} ({gke-short}).
 ====
 
-To start using Orchestrator in {product-very-short}, you must:
-
-* Install the required infrastructure components, such as Red Hat OpenShift Serverless Operator, Knative Serving, Knative Eventing, and OpenShift Serverless Logic Operator
-* Configure your {product-custom-resource-type} custom resource (CR) or Helm values file for Orchestrator
+// compatibility guide for {product} Orchestrator
+include::modules/orchestrator/ref-compatibility-guide-for-orchestrator.adoc[leveloffset=+1]
 
 // orchestrator architecture
 include::modules/orchestrator/con-architecture-overview.adoc[leveloffset=+1]
 
-// compatibility guide for {product} Orchestrator
-include::modules/orchestrator/ref-compatibility-guide-for-orchestrator.adoc[leveloffset=+1]
+// getting started
+include::modules/orchestrator/con-getting-started.adoc[leveloffset=+1]
 
 // provisioning plugin dependencies
-include::modules/orchestrator/con-orchestrator-plugin-dependencies-operator.adoc[leveloffset=+1]
-
-// enabling orchestrator plugins components
-include::modules/orchestrator/proc-enabling-orchestrator-plugins-components.adoc[leveloffset=+1]
-
-// Orchestrator Infrastructure for {product} Helm chart
-include::modules/orchestrator/proc-helm-install-components-orchestrator-plugin.adoc[leveloffset=+2]
-
-// manual installation
-include::modules/orchestrator/proc-manual-install-components-orchestrator-plugin.adoc[leveloffset=+2]
-
-// {product-very-short} helper script
-include::modules/orchestrator/proc-helper-script-overview.adoc[leveloffset=+2]
-
-// best practices when creating workflows
-include::modules/orchestrator/ref-best-practices-for-creating-workflows.adoc[leveloffset=+1]
+include::modules/orchestrator/con-orchestrator-plugin-dependencies-operator.adoc[leveloffset=+1]
diff --git a/modules/orchestrator/con-architecture-overview.adoc b/modules/orchestrator/con-architecture-overview.adoc
@@ -1,6 +1,6 @@
 :_mod-docs-content-type: CONCEPT
 
-[id="con-architecture-overview.adoc_{context}"]
+[id="con-architecture-overview_{context}"]
 = Understand Orchestrator architecture
 
 The Orchestrator architecture is composed of several components, each contributing to the running and management of workflows.
@@ -13,16 +13,12 @@ Orchestrator backend plugins::: Get workflow data into {product-short}.
 
 Notifications plugins::: Inform users about workflow events.
 
-Sonataflow::
-
-The Sonataflow orchestrator and its subcomponents handle the workflows.
-The {product} Orchestrator and the {product} Helm chart manage the following subcomponents lifecycle:
-
-OpenShift Serverless Logic Operator::: Manages the Sonataflow custom resource (CR), where each CR represents a deployed workflow.
+Openshift Serverless Logic Operator:: Serves as the workflow engine, and its subcomponents handle running, executing and providing persistence for the workflows. The {product} Operator and the {product} Helm chart manage the following lifecycle of these subcomponents:
 
 Sonataflow Runtime/Workflow Application::: Functions as a deployed workflow. Operates as an HTTP server, handling requests for running workflow instances. It is managed as a Kubernetes (K8s) deployment by the Openshift Serverless Logic Operator.
 
 Data Index Service::: Serves as a repository for workflow definitions, instances, and associated jobs. It exposes a GraphQL API used by the Orchestrator backend plugin to retrieve workflow definitions and instances.
+
 Job Service::: Orchestrates scheduled tasks for workflows.
 
 OpenShift Serverless::: Provides serverless capabilities essential for workflow communication. It employs Knative eventing to interface with the Data Index service and uses Knative functions to introduce more complex logic to workflows.

diff --git a/modules/orchestrator/con-benefits-of-workflow-images.adoc b/modules/orchestrator/con-benefits-of-workflow-images.adoc
@@ -1,6 +1,6 @@
 :_mod-docs-content-type: CONCEPT
 
-[id="con-benefits-of-workflow-images.adoc_{context}"]
+[id="con-benefits-of-workflow-images_{context}"]
 = Benefits of workflow images
 
 While the OpenShift Serverless Logic Operator supports the building of workflows dynamically, this approach is primarily for experimentation.

diff --git a/modules/orchestrator/con-build-sh-script-and-its-uses.adoc b/modules/orchestrator/con-build-sh-script-and-its-uses.adoc
@@ -1,6 +1,6 @@
 :_mod-docs-content-type: CONCEPT
 
-[id="con-build-sh-script-and-its-uses.adoc_{context}"]
+[id="con-build-sh-script-and-its-uses_{context}"]
 = The `build-sh` script functionality and important flags
 
 The `build-sh` script does the following tasks in order:

diff --git a/modules/orchestrator/con-environment-variables-supported-by-the-build-script.adoc b/modules/orchestrator/con-environment-variables-supported-by-the-build-script.adoc
@@ -1,6 +1,6 @@
 :_mod-docs-content-type: CONCEPT
 
-[id="con-environment-variables-supported-by-the-build-script.adoc_{context}"]
+[id="con-environment-variables-supported-by-the-build-script_{context}"]
 = Environment variables supported by the build script
 
 The `build-sh` script supports the following environment variables to customize the workflow build process without modifying the script itself:

diff --git a/modules/orchestrator/con-generated-workflow-manifests.adoc b/modules/orchestrator/con-generated-workflow-manifests.adoc
@@ -1,6 +1,6 @@
 :_mod-docs-content-type: CONCEPT
 
-[id="con-generated-workflow-manifests.adoc_{context}"]
+[id="con-generated-workflow-manifests_{context}"]
 = Generated workflow manifests
 
 The following example is an illustration of what is generated under the `01_basic/manifests`:

diff --git a/modules/orchestrator/con-getting-started.adoc b/modules/orchestrator/con-getting-started.adoc
@@ -0,0 +1,17 @@
+:_mod-docs-content-type: CONCEPT
+
+[id="con-getting-started_{context}"]
+= Getting started with Orchestrator
+
+To start using Orchestrator in {product-very-short}, you must:
+
+* Install the required infrastructure components, such as Red Hat OpenShift Serverless Operator, Knative Serving, Knative Eventing, and OpenShift Serverless Logic Operator
+
+* Configure your {product-custom-resource-type} custom resource (CR) or Helm values file for Orchestrator
+
+[NOTE]
+====
+When using the {product-very-short} Operator, the required infrastructure components are provisioned automatically once the Orchestrator plugins are enabled in the {product-custom-resource-type} CR.
+
+When using the {product-very-short} Helm chart, the required infrastructure components are installed automatically using the dedicated `redhat-developer-hub-orchestrator-infra` Helm chart prior to enabling the Orchestrator plugins in the main {product-very-short} chart.
+====
diff --git a/modules/orchestrator/con-orchestrator-plugin-dependencies-operator.adoc b/modules/orchestrator/con-orchestrator-plugin-dependencies-operator.adoc
@@ -1,6 +1,6 @@
 :_mod-docs-content-type: CONCEPT
 
-[id="con-orchestrator-plugin-dependencies-operator.adoc_{context}"]
+[id="con-orchestrator-plugin-dependencies-operator_{context}"]
 = Orchestrator plugin dependencies for Operator installation
 
 When you enable the Orchestrator plugin in your {product-custom-resource-type} custom resource (CR), the Operator automatically provisions the following required dependencies:

diff --git a/modules/orchestrator/con-project-structure-overview.adoc b/modules/orchestrator/con-project-structure-overview.adoc
@@ -1,6 +1,6 @@
 :_mod-docs-content-type: CONCEPT
 
-[id="con-project-structure-overview.adoc_{context}"]
+[id="con-project-structure-overview_{context}"]
 = Project structure overview
 
 The project utilizes *Quarkus project layout* (Maven project structure). This structure is illustrated by the following `01_basic` workflow example:

diff --git a/modules/orchestrator/con-required-tools.adoc b/modules/orchestrator/con-required-tools.adoc
@@ -1,6 +1,6 @@
 :_mod-docs-content-type: CONCEPT
 
-[id="con-required-tools.adoc_{context}"]
+[id="con-required-tools_{context}"]
 = Required tools
 
 To run the `build-sh` script locally and manage the workflow lifecycle, you must install the following command-line tools:

diff --git a/modules/orchestrator/proc-building-locally.adoc b/modules/orchestrator/proc-building-locally.adoc
@@ -1,6 +1,6 @@
 :_mod-docs-content-type: PROCEDURE
 
-[id="proc-building-locally.adoc_{context}"]
+[id="proc-building-locally_{context}"]
 = Building workflow images locally
 
 You can use the build script (`build.sh`) to build workflow images. You can run it either locally or inside a container. This section highlights how build workflow images locally.

diff --git a/modules/orchestrator/proc-building-the-01-basic-workflow.adoc b/modules/orchestrator/proc-building-the-01-basic-workflow.adoc
@@ -1,6 +1,6 @@
 :_mod-docs-content-type: PROCEDURE
 
-[id="proc-building-the-01-basic-workflow.adoc_{context}"]
+[id="proc-building-the-01-basic-workflow_{context}"]
 = Building the `01_basic` workflow
 
 To run the script from the root directory of the repository, you must use the `-w` flag to point to the workflow directory. Additionally, specify the output directory with the `-m` flag.

diff --git a/modules/orchestrator/proc-creating-and-running-workflows.adoc b/modules/orchestrator/proc-creating-and-running-workflows.adoc
@@ -1,6 +1,6 @@
 :_mod-docs-content-type: PROCEDURE
 
-[id="proc-creating-and-running-workflows.adoc_{context}"]
+[id="proc-creating-and-running-workflows_{context}"]
 = Creating and running your serverless workflow project locally
 
 The `kn-workflow` CLI is an essential tool that generates workflow manifests and project structures. To ensure successful development and immediate testing, begin developing a new serverless workflow locally by completing the following steps:

diff --git a/modules/orchestrator/proc-deploying-workflows-on-a-cluster.adoc b/modules/orchestrator/proc-deploying-workflows-on-a-cluster.adoc
@@ -1,6 +1,6 @@
 :_mod-docs-content-type: PROCEDURE
 
-[id="proc-deploying-workflows-on-a-cluster.adoc_{context}"]
+[id="proc-deploying-workflows-on-a-cluster_{context}"]
 = Deploying workflows on a cluster
 
 You can deploy the workflow on a cluster, since the image is pushed to the image registry and the deployment manifests are available.

diff --git a/modules/orchestrator/proc-enabling-orchestrator-plugins-components.adoc b/modules/orchestrator/proc-enabling-orchestrator-plugins-components.adoc
@@ -1,49 +1,29 @@
 :_mod-docs-content-type: PROCEDURE
 
-[id="proc-enabling-orchestrator-plugins-components.adoc_{context}"]
+[id="proc-enabling-orchestrator-plugins-components_{context}"]
 = Enabling Orchestrator plugins components
 
-To use the Orchestrator, enable the Orchestrator plugins for {product}, that are disabled by default:
+To use the Orchestrator, enable the following Orchestrator plugins for {product}, that are disabled by default:
 
-Orchestrator frontend plugins::
+Orchestrator-frontend plugin::
 
 `backstage-plugin-orchestrator`:::
 Provides the interface for users to run and monitor workflows within {product-very-short}. You can run and track the execution status of processes.
 
-`backstage-plugin-orchestrator-form-widgets`:::
-Provides custom widgets for the workflow execution form, allowing you to customize input fields and streamline the process of launching workflows.
-
-`backstage-plugin-orchestrator-form`:::
-Provides the workflow execution form where you can define and submit the necessary input data required to start a new workflow instance.
-
-`backstage-plugin-orchestrator-form-api`:::
-Defines the API for extending the workflow execution form.
-
-Orchestrator backend plugins::
+Orchestrator-backend plugin::
 
 `backstage-plugin-orchestrator-backend`:::
-Gets workflow data into {product-short} making sure {product-very-short} ingests critical workflow metadata and runtime status fulfilling your need for visibility.
-
-`backstage-plugin-orchestrator-common`:::
-Contains the backend OpenAPI specification along with autogenerated API documentation and client libraries.
-
-`scaffolder-backend-module-orchestrator`:::
-Provides callable actions from scaffolder templates, such as `orchestrator:workflow:run` or `orchestrator:workflow:get_params`.
-
-Notification plugins::
+Gets workflow data into {product-short} making sure {product-very-short} processes critical workflow metadata and runtime status fulfilling your need for visibility.
 
-`backstage-plugin-notifications`:::
-Provides notification frontend components that allow you to display immediate, visible alerts about key workflow state changes, allowing real-time status tracking.
+Orchestrator-form-widget::
 
+`backstage-plugin-orchestrator-form-widgets`:::
+Provides custom widgets for the workflow execution form, allowing you to customize input fields and streamline the process of launching workflows.
 
-`backstage-plugin-signals`:::
-Provides notification frontend components user experience enhancements so you can process the real-time lifecycle events.
-
-`backstage-plugin-notifications-backend-dynamic`:::
-Provides notification backend components allowing you to manage and store the stream of workflow events, making sure that critical notifications are ready to be served to the front-end user interface.
+Orchestrator-scaffolder-backend-module::
 
-`backstage-plugin-signals-backend-dynamic`:::
-Provides the backend components for notification user experience enhancements allowing you to establish the necessary communication channels for the event-driven orchestration that is core to Serverless Workflows.
+`scaffolder-backend-module-orchestrator`:::
+Provides callable actions from Scaffolder templates, such as `orchestrator:workflow:run` or `orchestrator:workflow:get_params`.
 
 .Prerequisites
 
@@ -61,19 +41,13 @@ Provides the backend components for notification user experience enhancements al
 [source,yaml,subs="+attributes,+quotes"]
 ----
 plugins:
-  - package: "@redhat/backstage-plugin-orchestrator@{product-chart-version}"
+  - package: "@redhat/backstage-plugin-orchestrator@{orchestrator-plugin-version}"
     disabled: false
-  - package: "@redhat/backstage-plugin-orchestrator-backend-dynamic@{product-chart-version}"
+  - package: "@redhat/backstage-plugin-orchestrator-backend-dynamic@{orchestrator-plugin-version}"
     disabled: false
-  - package: "@redhat/backstage-plugin-scaffolder-backend-module-orchestrator-dynamic@{product-chart-version}"
+  - package: "@redhat/backstage-plugin-scaffolder-backend-module-orchestrator-dynamic@{orchestrator-plugin-version}"
     disabled: false
-  - package: "@redhat/backstage-plugin-orchestrator-form-widgets@{product-chart-version}"
-    disabled: false
-  - package: "@redhat/backstage-plugin-orchestrator-common@{product-chart-version}"
-    disabled: false
-  - package: "@redhat/backstage-plugin-orchestrator-form@{product-chart-version}"
-    disabled: false
-  - package: "@redhat/backstage-plugin-orchestrator-form-api@{product-chart-version}"
+  - package: "@redhat/backstage-plugin-orchestrator-form-widgets@{orchestrator-plugin-version}"
     disabled: false
   - package: "./dynamic-plugins/dist/backstage-plugin-notifications"
     disabled: false
@@ -83,4 +57,4 @@ plugins:
     disabled: false
   - package: "./dynamic-plugins/dist/backstage-plugin-signals-backend-dynamic"
     disabled: false
-----
+----
diff --git a/modules/orchestrator/proc-helm-install-components-orchestrator-plugin.adoc b/modules/orchestrator/proc-helm-install-components-orchestrator-plugin.adoc
@@ -7,7 +7,7 @@ You can use Orchestrator Infrastructure for {product} to install components for
 
 .Procedure
 
-. Run the `helm install` command for the `orchestrator-infra` chart. This command initiates the installation of the Red Hat Serverless Operator and Red Hat Serverless Logic Operator components.
+. Run the `helm install` command for the `redhat-developer-hub-orchestrator-infra` Helm chart. This command initiates the installation of the Red Hat Serverless Operator and Red Hat Serverless Logic Operator components.
 +
 [source,terminal,subs="attributes+"]
 ----

diff --git a/modules/orchestrator/proc-helper-script-overview.adoc b/modules/orchestrator/proc-helper-script-overview.adoc
@@ -1,6 +1,6 @@
 :_mod-docs-content-type: PROCEDURE
 
-[id="proc-helper-script-overview.adoc_{context}"]
+[id="proc-helper-script-overview_{context}"]
 = Installing components using the `{product-very-short}` helper script
 
 You can use the {product-very-short} helper script `plugin-infra.sh` to quickly install the OpenShift Serverless infrastructure and Openshift Serverless Logic infrastructure required by the Orchestrator plugin.