EPIC Goal

What are we trying to solve here?

Background/Feature Origin

Why is this important?

User Scenarios

Dependencies (internal and external)

Acceptance Criteria

Release Enablement/Demo - Provide necessary release enablement details and documents
DEV - Upstream code and tests merged: <link to meaningful PR or GitHub Issue>
DEV - Upstream documentation merged: <link to meaningful PR or GitHub Issue>
DEV - Downstream build attached to advisory: <link to errata>
QE - Test plans in Playwright: <link or reference to playwright>
QE - Automated tests merged: <link or reference to automated tests>
DOC - Downstream documentation merged: <link to meaningful PR>

Documentation Tasks:

• Follow logical order: these are prerequisites for proc-enabling-orchestrator-plugins-components.adoc in the Helm chart case. They should appear before proc-enabling-orchestrator-plugins-components.adoc: "Installing Orchestrator dependencies when using the {product} Helm Chart", with heads up on the fact that this step is not necessary when using the Operator.

Consider also this reorganisation:

Outline

Installing the Orchestrator

Orchestrator architecture

In this section, cover the architecture components that the customer need to understand to be successful in installing RHDH with the Orchestrator.
Omit components that can be left in the kitchen sink of the plugin developer, only necessary to understand how to develop the plugin itself.
Group the components logically: the groups are then reused in procedure, because they are used in different steps (RHDH plugins, Sonataflow and dependencies).

Highlight the main installer differences:

• The Operator installs all the dependencies transparently.
• Installing with the Helm chart requires additional steps.
• As usual, installing in network restricted environments requires additional steps, such as mirroring the required components into the restricted network.

There is a logical progression in presenting the procedures: start the simplest (Operator), increase complexity: (Helm), (Operator + airgap), finish with the most complex (Helm + airgap).

Installing the Orchestrator by using the {product} Operator

1. Unique step: install the Orchestrator and Notification plugins. (The RHDH Operator installs all the required Sonataflow and Serverless dependencies)

Installing the Orchestrator by using the {product} Helm Chart

1. Install the OpenShift Serverless dependencies
2. Install the Orchestrator and Notification plugins.

Installing the Orchestrator by using the {product} Operator in a network restricted environment

1. Mirror the images (and other preliminary tasks?)
2. Install the Orchestrator and Notification plugins.

Installing the Orchestrator by using the {product} Helm Chart in a network restricted environment

1. Mirror the images (and other preliminary tasks?)
2. Install the OpenShift Serverless dependencies
3. Install the Orchestrator and Notification plugins.

Example detailled outline

(Thanks ffloreth@redhat.com for the help with this task so far.)

Enabling the RHDH Orchestrator for an RHDH Operator-based instance

Prerequisites

• You run Red Hat Developer Hub (RHDH)  by using the RHDH Operator.
• (Optional) For managing the Orchestrator project, you have installed Argo CD or Red Hat OpenShift GitOps in the cluster. It is disabled by default.
• (Optional) To use Tekton tasks and the build pipeline, you have installed Tekton or Red Hat OpenShift Pipelines in the cluster. These features are disabled by default.   

Procedure

1. Enable the Orchestrator plugins. (+ code with all plugins) (+ Describe each plugin purpose)

Verification

• The RHDH Web UI displays the Operator feature (describe where).
• The RHDH Operator has installed all the Sonataflow and Serverless dependencies, including: OpenShift Serverless Logic Operator, OpenShift Serverless Operator, Knative Serving, Knative Eventing, SonataFlowPlatform instance and network policies, Postgresql database, secret, and service.

Enabling the RHDH Orchestrator for an RHDH Helm-based instance

Prerequisites

• You run Red Hat Developer Hub (RHDH) by using the RHDH Helm Chart
• (Optional) For managing the Orchestrator project, you have installed Argo CD or Red Hat OpenShift GitOps in the cluster. It is disabled by default.
• (Optional) To use Tekton tasks and the build pipeline, you have installed Tekton or Red Hat OpenShift Pipelines in the cluster. These features are disabled by default.   

Procedure

1. Run the helm install command for the orchestrator-infra chart. This command initiates the installation of all the Sonataflow and Serverless dependencies, including: OpenShift Serverless Logic Operator, OpenShift Serverless Operator, Knative Serving, Knative Eventing, SonataFlowPlatform instance and network policies, Postgresql database, secret, and service.
2. Manually approve the install plans for the Operators. You must run the oc patch installplan commands provided in the output to approve their installation. 
3. Enable the Orchestrator plugins in the RHDH app-config.yaml. (+ code with all plugins) (+ Describe each plugin purpose).

Install the RHDH Orchestrator manually on a Helm-based installation

Omit this procedure unless we really intend to support it.

Prerequisites

• You run Red Hat Developer Hub (RHDH) by using the RHDH Helm Chart
• (Optional) For managing the Orchestrator project, you have installed Argo CD or Red Hat OpenShift GitOps in the cluster. It is disabled by default.
• (Optional) To use Tekton tasks and the build pipeline, you have installed Tekton or Red Hat OpenShift Pipelines in the cluster. These features are disabled by default.   

Procedure

1. Install the OpenShift Serverless components manually by following the instructions in the Red Hat OpenShift Serverless documentation.
2. Configure workflow persistence to prevent workflow context from being lost when the Pod restarts. You can do this configuration at the namespace level using the SonataFlowPlatform or SonataFlow custom resources (CR). For detailed instructions on configuring persistence using the SonataFlowPlatform or SonataFlow custom resources, see Managing workflow persistence.
3. (Optional) If required, deploy a custom PostgreSQL database.    
4. Enable the Orchestrator plugins in the RHDH app-config.yaml. (+ code with all plugins) (+ Describe each plugin purpose).
    

Who is your target persona?

<Role>

What stage of the user journey are you targeting?

<User journey>

Why is this content important?

<Justification>

What is the main user goal aka job to be done?

As a <role>, I want to <goal>

What high level steps does the user need to take to accomplish the goal?

1. <User steps to accomplish goal>

What pain points are the user likely to encounter when accomplishing this goal?

<Pain points>

Links to existing content

• <Add link to content>

People:

• SME: <SME>
• QE: <QE>

Release Note: Yes/No

Documentation Outline

• <Documentation outline>

Who is your target persona?

<Role>

What stage of the user journey are you targeting?

<User journey>

Why is this content important?

<Justification>

What is the main user goal aka job to be done?

As a <role>, I want to <goal>

What high level steps does the user need to take to accomplish the goal?

1. <User steps to accomplish goal>

What pain points are the user likely to encounter when accomplishing this goal?

<Pain points>

Links to existing content

• <Add link to content>

People:

• SME: <SME>
• QE: <QE>

Release Note: Yes/No

Documentation Outline

• <Documentation outline>