docs(orchestrator): improve readme #227
Conversation
Missing ChangesetsThe following package(s) are changed by this PR but do not have a changeset:
See CONTRIBUTING.md for more information about how to add changesets. Changed Packages
|
| export AUTH_GITHUB_CLIENT_ID=...fill | ||
| export AUTH_GITHUB_CLIENT_SECRET=...fill |
There was a problem hiding this comment.
link to explain how to get those secrets?
There was a problem hiding this comment.
good point, I added instructions how to do this
There was a problem hiding this comment.
does it look good now?
workspaces/orchestrator/plugins/orchestrator/docs/quickstart.md
Outdated
Show resolved
Hide resolved
|
|
||
| The orchestrator works harmoniously with other Backstage components such as the Software Catalog, permissions, and plugins as well as others. By leveraging its capabilities, organizations can orchestrate and coordinate developer self-service flows effectively. | ||
|
|
||
| ## Context |
There was a problem hiding this comment.
why removing the Context section? I see that you're keeping some of the info here and there but I don't get why the removed info is unnecessary. Need clarifications here :)
There was a problem hiding this comment.
I found it crowds the README and is related to Sonata itself and not to the plugin
But I can return it
| - Runtime monitoring of instances | ||
| - Dashboards | ||
| - Potential custom integrations (user interaction, notifications, etc.) | ||
| In addition to the main plugins, the architecture includes several isolated plugins that are imported by the above plugins: |
There was a problem hiding this comment.
I meant that the following plugins are imported by backstage-plugin-orchestrator or backstage-plugin-orchestrator-backend
| - Orchestration visualization / graphical editor | ||
| - Integration with service catalog/actions | ||
| - GitHub integration | ||
| - Form generation | ||
| - Runtime monitoring of instances | ||
| - Dashboards | ||
| - Potential custom integrations (user interaction, notifications, etc.) | ||
| In addition to the main plugins, the architecture includes several isolated plugins that are imported by the above plugins: |
There was a problem hiding this comment.
It does, I thought better make it shorter
batzionb
force-pushed
the
improvereadme
branch
from
b8bdbe0 to
ce118d2
Compare
|
@masayag @mareklibra |
| @@ -0,0 +1,70 @@ | |||
| ## How to use the Git Hub identity provider | |||
|
|
||
| Follow these steps to login to backstage using your github account: | ||
|
|
||
| ### Create a Github OAuth App |
| The orchestrator relies on [SonataFlow](https://sonataflow.org/), a powerful tool for building cloud-native workflow applications. | ||
|
|
||
| The main idea is to keep the same user experience for users, leveraging the UI components, input forms, and flow that Scaffolder provides, this way it should be straightforward for users and transparent no matter whether using Templates or Workflows, both can live together being compatible with integration points. | ||
| The orchestrator works harmoniously with other Backstage components such as the Software Catalog, permissions, and plugins as well as others. By leveraging its capabilities, organizations can orchestrate and coordinate developer self-service flows effectively. |
There was a problem hiding this comment.
What's the meaning of working harmoniously with the Software Catalog in this context? If the intention is to invoke software template as part of the workflow, or invoking other backend plugins - it should be stated clearly. This will highlight the fact that custom actions can be invoked by the orchestrator via a software template or as backend plugin if it has that API exposed.
There was a problem hiding this comment.
you're right, this section isn't clear, and the integration with the software catalog isn't done
I can remove this
|
|
||
| **Client-side tooling** | ||
| 2. **`backstage-plugin-orchestrator-backend`** | ||
| - Serves as a backend proxy between to SonataFlow. |
There was a problem hiding this comment.
should it be "between Backstand and SonataFlow" ?
|
|
||
| ## Capabilities | ||
| The architecture adheres to standard Backstage plugin guidelines and requires the following plugins to be installed for proper functionality: |
There was a problem hiding this comment.
Would you like to add a link to https://www.rhdhorchestrator.io/main/docs/architecture/ ?
|
|
||
| Please follow this link for instructions: https://github.com/janus-idp/backstage-showcase/blob/main/docs/dynamic-plugins/installing-plugins.md#installing-external-dynamic-plugins. | ||
| ## Install as a static plugin |
There was a problem hiding this comment.
this is for users installing on vanilla backstage
There was a problem hiding this comment.
all RHDH plugins include this in the docs
|
|
||
| More detailed info about permissions can be found in [docs/Permissions.md](docs/Permissions.md). | ||
| - Docker up and running |
There was a problem hiding this comment.
Isn't podman supported as well? if not, should we provide here the command for running the container using podman from CLI instead of auto-start by the plugin?
There was a problem hiding this comment.
the command is invoked in our code, currently it runs docker
we will need to change the code to support also podman
There was a problem hiding this comment.
I think better change the code to support both than to have the README explain what to do for podman, which is updating the autoStart to false and running the command
|
|
||
| This command updates the [generated files](https://github.com/redhat-developer/rhdh-plugins/blob/main/workspaces/orchestrator/plugins/orchestrator-common/src/generated) including API, client and docs. | ||
| For more information about audit logs in RHDH, please refer to [the official documentation](https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.2/html/getting_started_with_red_hat_developer_hub/assembly-audit-log#con-audit-log-config_assembly-audit-log). |
There was a problem hiding this comment.
This can be updated to RHDH 1.4 doc:
https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.4/html/audit_log/assembly-audit-log
|
|
||
| ### Create a Github OAuth App | ||
|
|
||
| Go to your Github account -> Setting -> Developer settings -> OAuth Apps -> New OAuth App. |
|
|
||
| ### Update backstage user entity | ||
|
|
||
| Update [users.yaml](../users.yaml) to match you Github account. Put your github username in the metadata.name field, and you github email in spec.profile.email field. |
There was a problem hiding this comment.
Perhaps a snippet will be a simpler option of a User entity (just a thought)
There was a problem hiding this comment.
you have it in ../users.yaml
| yarn dev | ||
| ``` | ||
|
|
||
| ## API Development instruction |
There was a problem hiding this comment.
Shouldn't this section go under orchestrator-common/README.md and be pointed from here or the other way around?
|
|
||
| - **Organizing Forms into Wizard-Style Steps:** If the schema is an object containing nested objects (i.e., the root is an object, and its properties are also objects), the plugin organizes the form into multiple steps. Each nested object becomes a separate step in a wizard-style interface. For example, the schema provided above results in two steps: _Personal Details_ and _Contact Details_. | ||
|
|
||
| The [`orchestrator-form-react`](https://github.com/janus-idp/backstage-plugins/tree/main/plugins/orchestrator-form-react) plugin is designed to operate independently of the main orchestrator plugin. This modularity allows developers to test and validate form behavior in a standalone Backstage development environment before integrating it with the full orchestrator setup. |
There was a problem hiding this comment.
organized and updated the README
made the introduction part much shorter to keep the README focused
Link to branch to review properly:
https://github.com/batzionb/rhdh-plugins/tree/improvereadme/workspaces/orchestrator#readme