RHIDP-7849 Added existing modules to the _Getting started with RHDH on OCP_ title

themr0c · themr0c · commit f3e10193bc2b · 2025-08-06T16:37:25.000+02:00
Fixed existing content to build while reused.

Signed-off-by: Fabrice Flore-Thébault &lt;ffloreth@redhat.com&gt;
diff --git a/assemblies/assembly-configuring-high-availability.adoc b/assemblies/assembly-configuring-high-availability.adoc
@@ -1,4 +1,5 @@
 :_mod-docs-content-type: ASSEMBLY
+:previouscontext: {context}
 :context: HighAvailability
 [id="{context}"]
 = Configuring high availability in {product}
@@ -9,7 +10,7 @@ High availability (HA) is a system design approach that ensures a service remain
 {product} supports HA deployments on the following platforms:
 
 * {ocp-brand-name}
-* {aks-name} 
+* {aks-name}
 * {eks-name}
 
 The HA deployments enable more resilient and reliable service availability across supported environments.
@@ -25,4 +26,7 @@ As an administrator, you can configure high availability by adjusting replica va
 
 include::modules/configuring-high-availability/proc-configuring-high-availability-in-rhdh-operator-deployment.adoc[leveloffset=+1]
 
-include::modules/configuring-high-availability/proc-configuring-high-availability-in-rhdh-helm-chart-deployment.adoc[leveloffset=+1]
+include::modules/configuring-high-availability/proc-configuring-high-availability-in-rhdh-helm-chart-deployment.adoc[leveloffset=+1]
+
+:context: {previouscontext}
+!:previouscontext:
diff --git a/modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc b/modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc
@@ -157,7 +157,6 @@ catalog:
         schedule:
           initialDelay: { seconds: 15}
 ----
---
 
 . To set up the {rhbk} authentication provider in your {product-short} custom configuration, edit your custom {product-short} ConfigMap such as `app-config-rhdh`, and add the following lines to the `{my-app-config-file}` content:
 
diff --git a/modules/configuring/proc-configuring-an-rhdh-instance-with-tls-in-kubernetes.adoc b/modules/configuring/proc-configuring-an-rhdh-instance-with-tls-in-kubernetes.adoc
@@ -1,4 +1,4 @@
-[id="proc-configuring-an-rhdh-instance-with-tls-in-kubernetes_{context}"]
+[id="configuring-an-rhdh-instance-with-tls-in-kubernetes"]
 = Configuring an {product-very-short} instance with a TLS connection in Kubernetes
 
 You can configure a {product-very-short} instance with a Transport Layer Security (TLS) connection in a Kubernetes cluster, such as an Azure Red Hat OpenShift (ARO) cluster, any cluster from a supported cloud provider, or your own cluster with proper configuration. Transport Layer Security (TLS) ensures a secure connection for the {product-very-short} instance with other entities, such as third-party applications, or external databases. However, you must use a public Certificate Authority (CA)-signed certificate to configure your Kubernetes cluster.
diff --git a/modules/configuring/proc-provisioning-your-custom-configuration.adoc b/modules/configuring/proc-provisioning-your-custom-configuration.adoc
@@ -22,40 +22,10 @@ It contains one secret per line in `KEY=value` form.
 This is the main {product-short} configuration file.
 You need a custom `{my-app-config-file}` file to avoid the {product-short} installer to revert user edits during upgrades.
 When your custom `{my-app-config-file}` file is empty, {product-short} is using default values.
-
-** To prepare a deployment with the {product} Operator on {ocp-short}, you can start with an empty file.
-
-** To prepare a deployment with the {product} Helm chart, or on Kubernetes, enter the {product-short} base URL in the relevant fields in your `{my-app-config-file}` file to ensure proper functionality of {product-short}.
-The base URL is what a {product-short} user sees in their browser when accessing {product-short}.
-The relevant fields are `baseUrl` in the `app` and `backend` sections, and `origin` in the `backend.cors` subsection:
 +
-.Configuring the `baseUrl` in `{my-app-config-file}`
-====
-[source,yaml,subs="+attributes,+quotes"]
-----
-app:
-  title: {product}
-  baseUrl: {my-product-url}
-
-backend:
-  auth:
-    externalAccess:
-      - type: legacy
-        options:
-          subject: legacy-default-config
-          secret: "${BACKEND_SECRET}"
-  baseUrl: {my-product-url}
-  cors:
-    origin: {my-product-url}
-----
-====
-
-** Optionally, enter your configuration such as:
-
-*** link:{authentication-book-url}[{authentication-book-title}].
-*** link:{authorization-book-url}[{authorization-book-title}].
-*** link:{customizing-book-url}[Customization].
-*** xref:proc-configuring-an-rhdh-instance-with-tls-in-kubernetes_running-behind-a-proxy[Configure your {ocp-short} integration].
+--
+include::snip-provisioning-your-custom-configuration-optional-substep-in-{context}-context.adoc[]
+--
 
 . Provision your custom configuration files to your {ocp-short} cluster.
 
@@ -92,12 +62,5 @@ link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-
 `_<my_product_secrets>_` is your preferred {product-short} secret name, specifying the identifier for your secret configuration within {product-short}.
 ====
 
-.Next steps
-Consider provisioning additional config maps and secrets:
-
-* To use an external PostgreSQL database, xref:configuring-external-postgresql-databases[provision your PostgreSQL database secrets].
-
-
-* To enable dynamic plugins, link:{installing-and-viewing-plugins-book-url}[provision your dynamic plugins config map].
 
-* To configure authorization by using external files, link:{authorization-book-url}#managing-authorizations-by-using-external-files[provision your RBAC policies config map].
+include::snip-provisioning-your-custom-configuration-next-steps-in-{context}-context.adoc[]
diff --git a/modules/configuring/proc-using-the-operator-to-run-rhdh-with-your-custom-configuration-in-getting-started-context.adoc b/modules/configuring/proc-using-the-operator-to-run-rhdh-with-your-custom-configuration-in-getting-started-context.adoc
@@ -0,0 +1,72 @@
+[id="using-the-operator-to-run-rhdh-with-your-custom-configuration"]
+= Using the {product} Operator to run {product-short} with your custom configuration
+
+To use the {product-short} Operator to run {product} with your custom configuration, create your {product-custom-resource-type} custom resource (CR) that:
+
+* Mounts files provisioned in your custom config maps.
+* Injects environment variables provisioned in your custom secrets.
+
+.Prerequisites
+* By using the link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html-single/cli_tools/index#cli-about-cli_cli-developer-commands[{openshift-cli}], you have access, with developer permissions, to the {ocp-short} cluster aimed at containing your {product-short} instance.
+* xref:proc-install-operator_getting-started-with-rhdh-on-ocp-for-the-platform-engineer[]
+* xref:provisioning-your-custom-configuration[]
+
+.Procedure
+
+. Author your {product-custom-resource-type} CR in a `{my-product-cr-name}.yaml` file to use your custom config maps and secrets.
++
+.`{my-product-cr-name}.yaml` custom resource example with dynamic plugins and RBAC policies config maps, and external PostgreSQL database secrets.
+[source,yaml,subs="+attributes,+quotes"]
+----
+apiVersion: rhdh.redhat.com/v1alpha3
+kind: Backstage
+metadata:
+  name: _<{my-product-cr-name}>_
+spec:
+  application:
+    appConfig:
+      mountPath: /opt/app-root/src
+      configMaps:
+         - name: {my-app-config-config-map}
+         - name: rbac-policies
+    dynamicPluginsConfigMapName: dynamic-plugins-rhdh
+    extraEnvs:
+      envs:
+        - name: HTTP_PROXY
+          value: 'http://10.10.10.105:3128'
+        - name: HTTPS_PROXY
+          value: 'http://10.10.10.106:3128'
+        - name: NO_PROXY
+          value: 'localhost,example.org'
+      secrets:
+         - name: `_<my_product_secrets>_`
+         - name: {my-product-database-secrets}
+    extraFiles:
+      mountPath: /opt/app-root/src
+      secrets:
+        - name: {my-product-database-certificates-secrets}
+          key: postgres-crt.pem, postgres-ca.pem, postgres-key.key
+    replicas: 2
+  database:
+    enableLocalDb: false
+----
+
+`application`::
+`appConfig`::: Register your `{my-app-config-config-map}` and `rbac-policies` config maps.
+`dynamicPluginsConfigMapName`::: Register your `dynamic-plugins-rhdh` config map.
+`extraEnvs`:::
+`env`:::: Enter your proxy environment variables.
+`secrets`:::: Register your `<my_product_secrets>` and `{my-product-database-secrets}` secrets.
+`extraFiles`:::
+`secrets`::::
+Register the `postgres-crt.pem`, `postgres-ca.pem`, and `postgres-key.key` files contained in the `{my-product-database-certificates-secrets}` secret.
+`replicas`::: Enable high availability (HA) by increasing the replicas count to a value higher or equal to 2.
+`database`::
+`enableLocalDb`::: Use your external PostgreSQL database rather than the internal PostgreSQL database.
+
+. Apply your {product-custom-resource-type} CR to start or update your {product-short} instance.
++
+[source,terminal,subs="+attributes,+quotes"]
+----
+$ oc apply --filename={my-product-cr-name}.yaml --namespace={my-product-namespace}
+----
diff --git a/modules/configuring/snip-provisioning-your-custom-configuration-next-steps-in-configuring-and-operating-context.adoc b/modules/configuring/snip-provisioning-your-custom-configuration-next-steps-in-configuring-and-operating-context.adoc
@@ -0,0 +1,9 @@
+.Next steps
+Consider provisioning additional config maps and secrets:
+
+* To use an external PostgreSQL database, xref:configuring-external-postgresql-databases[provision your PostgreSQL database secrets].
+
+
+* To enable dynamic plugins, link:{installing-and-viewing-plugins-book-url}[provision your dynamic plugins config map].
+
+* To configure authorization by using external files, link:{authorization-book-url}#managing-authorizations-by-using-external-files[provision your RBAC policies config map].
diff --git a/modules/configuring/snip-provisioning-your-custom-configuration-next-steps-in-getting-started-with-rhdh-on-ocp-for-the-platform-engineer-context.adoc b/modules/configuring/snip-provisioning-your-custom-configuration-next-steps-in-getting-started-with-rhdh-on-ocp-for-the-platform-engineer-context.adoc
@@ -0,0 +1,10 @@
+.Next steps
+Consider provisioning additional config maps and secrets:
+
+* xref:proc-configuring-postgresql-instance-using-operator_getting-started-with-rhdh-on-ocp-for-the-platform-engineer[Provision your external PostgreSQL database secrets.]
+
+* xref:enabling-github-repository-discovery[Provision your GitHub repository discovery secrets.]
+
+* xref:proc-config-dynamic-plugins-rhdh-operator_getting-started-with-rhdh-on-ocp-for-the-platform-engineer[To enable dynamic plugins, provision your dynamic plugins config map].
+
+* To configure authorization by using external files, link:{authorization-book-url}#managing-authorizations-by-using-external-files[provision your RBAC policies config map].
diff --git a/modules/configuring/snip-provisioning-your-custom-configuration-optional-substep-in-getting-started-with-rhdh-on-ocp-for-the-platform-engineer-context.adoc b/modules/configuring/snip-provisioning-your-custom-configuration-optional-substep-in-getting-started-with-rhdh-on-ocp-for-the-platform-engineer-context.adoc
@@ -0,0 +1,55 @@
+.. For a production environment consider starting with:
++
+.`{my-app-config-file}`
+[source,yaml,subs="+attributes,+quotes"]
+----
+app:
+  title: My custom Red Hat Developer Hub title
+  branding:
+    fullLogo: ${BASE64_EMBEDDED_FULL_LOGO}
+    fullLogoWidth: 110px
+    iconLogo: ${BASE64_EMBEDDED_ICON_LOGO}
+backend:
+  cache:
+    store: redis
+    connection: redis://user:pass@cache.example.com:6379
+catalog:
+  providers:
+    github:
+      providerId:
+        organization: "${GITHUB_INTEGRATION_ORGANIZATION}"
+        schedule:
+          frequency:
+            minutes: 30
+          initialDelay:
+            seconds: 15
+          timeout:
+            minutes: 15
+integrations:
+  github:
+    - host: ${GITHUB_INTEGRATION_HOST_DOMAIN}
+      apps:
+        - appId: ${GITHUB_INTEGRATION_APP_ID}
+          clientId: ${GITHUB_INTEGRATION_CLIENT_ID}
+          clientSecret: ${GITHUB_INTEGRATION_CLIENT_SECRET}
+          privateKey: |
+            ${GITHUB_INTEGRATION_PRIVATE_KEY_FILE}
+techdocs:
+  cache:
+    ttl: 3600000
+----
+`app`::
+`title`::: Enter your Developer Hub instance display name, such as _<My custom {product} title>_.
+`branding`::: Set your custom logo. See xref:proc-customize-rhdh-branding-logo_getting-started-with-rhdh-on-ocp-for-the-platform-engineer[].
+`backend`::
+`cache`::: Enable the plugins assets cache. See xref:enabling-the-rhdh-plugin-assets-cache_getting-started-with-rhdh-on-ocp-for-the-platform-engineer[].
+`catalog`::
+`provider`:::
+`github`:::: xref:enabling-github-repository-discovery[]
+`integrations`::
+`github`::: xref:enabling-github-repository-discovery[]
+`techdocs`::
+`cache`::: Enable the Techdocs cache. See xref:enabling-the-rhdh-plugin-assets-cache_getting-started-with-rhdh-on-ocp-for-the-platform-engineer[].
+
+.. Additionaly, link:{authentication-book-url}[provision users and enabling authentication with your external identity provider].
+.. link:{authorization-book-url}[Configuring authorization by using Role based access control (RBAC)].
diff --git a/modules/configuring/snip-provisioning-your-custom-configuration-optional-substep-in-operating-and-configuring-context.adoc b/modules/configuring/snip-provisioning-your-custom-configuration-optional-substep-in-operating-and-configuring-context.adoc
@@ -0,0 +1,35 @@
+
+** To prepare a deployment with the {product} Operator on {ocp-short}, you can start with an empty file.
+
+** To prepare a deployment with the {product} Helm chart, or on Kubernetes, enter the {product-short} base URL in the relevant fields in your `{my-app-config-file}` file to ensure proper functionality of {product-short}.
+The base URL is what a {product-short} user sees in their browser when accessing {product-short}.
+The relevant fields are `baseUrl` in the `app` and `backend` sections, and `origin` in the `backend.cors` subsection:
++
+.Configuring the `baseUrl` in `{my-app-config-file}`
+====
+[source,yaml,subs="+attributes,+quotes"]
+----
+app:
+  title: {product}
+  baseUrl: {my-product-url}
+
+backend:
+  auth:
+    externalAccess:
+      - type: legacy
+        options:
+          subject: legacy-default-config
+          secret: "${BACKEND_SECRET}"
+  baseUrl: {my-product-url}
+  cors:
+    origin: {my-product-url}
+----
+====
+
+** Optionally, enter your configuration such as:
+
+*** link:{authentication-book-url}[{authentication-book-title}].
+*** link:{authorization-book-url}[{authorization-book-title}].
+*** link:{customizing-book-url}[Customization].
+*** xref:proc-configuring-an-rhdh-instance-with-tls-in-kubernetes_running-behind-a-proxy[Configure your {ocp-short} integration].
+
diff --git a/modules/installation/proc-install-operator.adoc b/modules/installation/proc-install-operator.adoc
@@ -78,8 +78,3 @@ If you selected an *Automatic* approval strategy, the upgrade status should reso
  *** From the list of installed Operators, locate the {product} Operator name and details.
  *** Click *{product} Operator* to open the *Operator details* page for the {product} Operator.
 
-[role="_additional-resources"]
-.Additional resources
-
-* xref:proc-install-rhdh-ocp-operator_{context}[Deploying {product} on {ocp-short} with the Operator]
-* link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html-single/operators/index#olm-installing-from-operatorhub-using-web-console_olm-adding-operators-to-a-cluster[Installing from OperatorHub by using the web console]
diff --git a/modules/integrating-with-github/proc-enabling-github-repository-discovery.adoc b/modules/integrating-with-github/proc-enabling-github-repository-discovery.adoc
@@ -25,7 +25,7 @@ Authorization callback URL::
 Enter your {product-short} authentication backend URL: `pass:c,a,q[{my-product-url}/api/auth/github/handler/frame]`.
 
 Webhook::
-Clear "Active", as this is not needed for authentication and catalog providers. 
+Clear "Active", as this is not needed for authentication and catalog providers.
 
 App permissions::
 Select permissions to define the level of access for the app.
@@ -117,7 +117,7 @@ It provides an automated alternative to manually registering components via `cat
 When a repository contains a `catalog-info.yaml` file, the entity is ingested into the catalog as a component.
 +
 .`dynamic-plugins.yaml` file fragment
-[code,yaml]
+[source,yaml]
 ----
 plugins:
   - package: './dynamic-plugins/dist/backstage-plugin-catalog-backend-module-github'
diff --git a/titles/configuring/master.adoc b/titles/configuring/master.adoc
@@ -27,7 +27,7 @@ include::assemblies/assembly-configuring-high-availability.adoc[leveloffset=+1]
 include::assemblies/assembly-configuring-a-proxy.adoc[leveloffset=+1]
 
 
-include::modules/installation/proc-configuring-an-rhdh-instance-with-tls-in-kubernetes.adoc[leveloffset=+1]
+include::modules/configuring/proc-configuring-an-rhdh-instance-with-tls-in-kubernetes.adoc[leveloffset=+1]
 
 
 include::assemblies/dynamic-plugins/assembly-using-the-dynamic-plugins-cache.adoc[ leveloffset=+1]
@@ -36,4 +36,4 @@ include::assemblies/dynamic-plugins/assembly-using-the-dynamic-plugins-cache.ado
 include::assemblies/assembly-configuring-default-secret-pvc-mounts.adoc[leveloffset=+1]
 
 
-include::modules/configuring/proc-enabling-the-rhdh-plugin-assets-cache.adoc[leveloffset=+1]
+include::modules/configuring/proc-enabling-the-rhdh-plugin-assets-cache.adoc[leveloffset=+1]
diff --git a/titles/getting-started-with-rhdh-on-ocp-for-the-platform-engineer/master.adoc b/titles/getting-started-with-rhdh-on-ocp-for-the-platform-engineer/master.adoc
@@ -2,9 +2,65 @@ include::artifacts/attributes.adoc[]
 :title: Getting started with {product} on {ocp-brand-name} for the platform engineer
 :subtitle: As a platform engineer, prepare your IT infrastructure including {ocp-brand-name} and required external components, and run your first {product} ({product-very-short}) instance in production.
 :abstract: As a platform engineer, prepare your IT infrastructure including {ocp-brand-name} and required external components, and run your first {product} ({product-very-short}) instance in production.
-:context: customizing-display
+:context: getting-started-with-rhdh-on-ocp-for-the-platform-engineer
 [id="{context}"]
 = {title}
 
 {abstract}
 
+// Install the operator
+include::modules/installation/proc-install-operator.adoc[leveloffset=+1]
+
+
+// Provision your custom configuration
+include::modules/configuring/proc-provisioning-your-custom-configuration.adoc[leveloffset=+1]
+
+// Understand plugins
+include::modules/con-rhdh-plugins.adoc[leveloffset=+1]
+
+
+// Select and enable your plugins
+include::modules/dynamic-plugins/proc-config-dynamic-plugins-rhdh-operator.adoc[leveloffset=+1]
+
+// TODO: Understand the software catalog
+
+// Enable plugin caching
+include::modules/configuring/proc-enabling-the-rhdh-plugin-assets-cache.adoc[leveloffset=+1]
+
+// Configure high availability (replicas)
+// Module replaced by a shorter version inline
+//include::assemblies/assembly-configuring-high-availability.adoc[leveloffset=+1]
+
+// Configure an external database
+include::modules/configuring-external-databases/proc-configuring-postgresql-instance-using-the-operator.adoc[leveloffset=+1]
+
+
+// Optional: If your environment requires it: run behind a proxy
+// Module replaced by a shorter version inline
+// include::modules/configuring-a-proxy/proc-configuring-proxy-in-operator-deployment.adoc[leveloffset=+1]
+
+// Authentication: simplified
+// FIXME: see https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/pull/1266
+
+// Git provider
+include::modules/integrating-with-github/proc-enabling-github-repository-discovery.adoc[leveloffset=+1]
+
+// Importing manually a Git repository
+//Missing?
+
+// Run a CI pipeline: GitHub; CF + Tekton
+
+// Configure Software Templates
+
+// Changing the title, logo, and color scheme
+== Customizing the appearance of your {product-very-short} instance
+
+include::modules/customizing/proc-customizing-your-product-title.adoc[leveloffset=+2]
+
+
+include::modules/customizing-the-appearance/proc-customize-rhdh-branding-logo.adoc[leveloffset=+2]
+
+
+include::modules/customizing-the-appearance/proc-customize-rhdh-theme-mode.adoc[leveloffset=+2]
+
+include::modules/configuring/proc-using-the-operator-to-run-rhdh-with-your-custom-configuration-in-getting-started-context.adoc[leveloffset=+1]

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-[id="proc-configuring-an-rhdh-instance-with-tls-in-kubernetes_{context}"]`
	`1`	`+[id="configuring-an-rhdh-instance-with-tls-in-kubernetes"]`
`2`	`2`	`= Configuring an {product-very-short} instance with a TLS connection in Kubernetes`
`3`	`3`
`4`	`4`	You can configure a {product-very-short} instance with a Transport Layer Security (TLS) connection in a Kubernetes cluster, such as an Azure Red Hat OpenShift (ARO) cluster, any cluster from a supported cloud provider, or your own cluster with proper configuration. Transport Layer Security (TLS) ensures a secure connection for the {product-very-short} instance with other entities, such as third-party applications, or external databases. However, you must use a public Certificate Authority (CA)-signed certificate to configure your Kubernetes cluster.