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,18 @@
+:_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]
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,58 @@
+:_mod-docs-content-type: ASSEMBLY
+
+[id="assembly-orchestrator-plugins-components_{context}"]
+=  Orchestrator plugins components
+
+To use the Orchestrator, enable the Orchestrator plugins for {product}, that are disabled by default:
+
+Orchestrator front end plugins::
+
+`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::
+
+`backstage-plugin-orchestrator-backend`:::
+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-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::
+
+`backstage-plugin-notifications`:::
+Provides notification front end components that allow you to display immediate, visible alerts about key workflow state changes, allowing real-time status tracking.
+
+
+`backstage-plugin-signals`:::
+Provides notification front end 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.
+
+`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.
+
+// 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]
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.

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,10 @@
+:_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
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,50 +1,8 @@
 :_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:
-
-Orchestrator frontend plugins::
-
-`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::
-
-`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::
-
-`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.
-
-
-`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.
-
-`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.
-
 .Prerequisites
 
 * You have installed the following operators:
@@ -83,4 +41,4 @@ plugins:
     disabled: false
   - package: "./dynamic-plugins/dist/backstage-plugin-signals-backend-dynamic"
     disabled: false
-----
+----
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.

diff --git a/modules/orchestrator/ref-best-practices-for-creating-workflows.adoc b/modules/orchestrator/ref-best-practices-for-creating-workflows.adoc
@@ -1,6 +1,6 @@
 :_mod-docs-content-type: CONCEPT
 
-[id="ref-best-practices-for-creating-workflows.adoc_{context}"]
+[id="ref-best-practices-for-creating-workflows_{context}"]
 = Best practices when creating serverless workflows
 
 Create effective serverless workflows using thoughtful approaches to design, handle data, and manage error by following these best practices based on the Serverless Workflow Domain Specific Language (DSL) principles. These principles help you to build robust workflows.

diff --git a/modules/orchestrator/ref-compatibility-guide-for-orchestrator.adoc b/modules/orchestrator/ref-compatibility-guide-for-orchestrator.adoc
@@ -1,6 +1,6 @@
 :_mod-docs-content-type: REFERENCE
 
-[id="con-compatibility-guide-for-orchestrator.adoc_{context}"]
+[id="con-compatibility-guide-for-orchestrator_{context}"]
 = Compatibility guide for Orchestrator
 
 The following table lists the {product-very-short} Orchestrator plugin versions and their compatible corresponding infrastructure versions.

diff --git a/titles/orchestrator/master.adoc b/titles/orchestrator/master.adoc
@@ -6,12 +6,16 @@ include::artifacts/attributes.adoc[]
 :abstract: As an administrator, you can use Orchestrator to enable serverless workflows in {product} to support cloud migration, developer onboarding, and custom workflows.
 = {title}
 
-include::assemblies/assembly-orchestrator-rhdh.adoc[leveloffset=+1]
+include::assemblies/assembly-rhdh-about-orchestrator.adoc[leveloffset=+1]
 
-include::assemblies/assembly-building-and-deploying-serverless-workflows.adoc[leveloffset=+1]
+include::assemblies/assembly-orchestrator-plugins-components.adoc[leveloffset=+1]
 
-include::assemblies/assembly-install-rhdh-orchestrator.adoc[leveloffset=+1]
+include::assemblies/assembly-install-rhdh-orchestrator-operator.adoc[leveloffset=+1]
+
+include::assemblies/assembly-install-rhdh-orchestrator-helm.adoc[leveloffset=+1]
+
+include::assemblies/assembly-install-rhdh-orchestrator-plugin-in-an-air-gapped-environment-operator.adoc[leveloffset=+1]
 
 include::assemblies/assembly-install-rhdh-orchestrator-plugin-in-an-air-gapped-environment-helm.adoc[leveloffset=+1]
 
-include::assemblies/assembly-install-rhdh-orchestrator-plugin-in-an-air-gapped-environment-operator.adoc[leveloffset=+1]
+include::assemblies/assembly-building-and-deploying-serverless-workflows.adoc[leveloffset=+1]