RHIDP-5733: Info about custom config in the Installation guides

modules/installation/proc-install-operator.adoc

@@ -19,9 +19,14 @@ Containers are available for the following CPU architectures:
 
 .Procedure
 
-. In the *Administrator* perspective of the {ocp-short} web console, click *Operators > OperatorHub*.
+. In the navigation menu of the {ocp-short} console, click *Operators > OperatorHub*.
 . In the *Filter by keyword* box, enter {product-short} and click the *{product} Operator* card.
 . On the *{product} Operator* page, read the information about the Operator and click *Install* to open the *Install Operator* page.
+.  After the Operator is successfully installed, provision your custom configuration:
++
+Before you create a {product-short} instance, you must create the required config map and Secret resources in your project. These include the `baseUrl` and service-to-service authentication secrets.
++
+For detailed steps, see xref:{configuring-book-url}#provisioning-and-using-your-custom-configuration[Provisioning your custom {product} configuration].
 . From the *Update channel* drop-down menu, select the update channel that you want to use, for example, *fast* or *fast-{product-version}*.
 +
 [IMPORTANT]

modules/installation/proc-install-rhdh-ocp-operator.adoc

@@ -7,21 +7,72 @@
 As a developer, you can deploy a {product} instance on {ocp-short} by using the *Developer Catalog* in the {ocp-brand-name} web console. This deployment method uses the {product} Operator.
 
 .Prerequisites
-
+* You have set the `baseUrl` in your `{my-app-config-file}` to match the external URL of your {product-short} instance. Without it, frontend and backend services cannot communicate, and features might not work as expected.
 * xref:proc-install-operator_{context}[An {ocp-short} administrator has installed the {product} Operator].
 * xref:{configuring-book-url}#provisioning-your-custom-configuration[You have provisioned your custom config maps and secrets in your `_<{my-product-namespace}>_` project].
 * xref:{configuring-book-url}#using-the-operator-to-run-rhdh-with-your-custom-configuration[You have authored your {product-custom-resource-type} custom resource].
 
 .Procedure
 
-. In the {ocp-short} web console, select your `_<{my-product-namespace}>_` project.
-
-. From the *Developer* perspective on the {ocp-short} web console, click *+Add*.
+. In the {ocp-short} web console, select your `_<{my-product-namespace}>_` project, then click *Add*.
 . From the *Developer Catalog* panel, click *Operator Backed*.
 . In the *Filter by keyword* box, enter _{product-short}_ and click the *{product}* card.
+. Provision your custom configuration using the following template:
++
+[source,yaml,subs="attributes+"]
+----
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: app-config-rhdh
+data:
+  "app-config-rhdh.yaml": |
+    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}
+----
++
+Use a config map named `app-config-rhdh` to provide your `app-config.yaml` file, and a Secret for service-to-service authentication (such as `BACKEND_SECRET`).
++
+To create and apply these configuration resources, follow the steps in xref:{configuring-book-url}#provisioning-and-using-your-custom-configuration[Provisioning your custom {product} configuration] for the full procedure.
++
+[NOTE]
+====
+The `app-config-rhdh` config map must include your customized `app-config.yaml` file. This config map is mounted into the {product-short} container at runtime.
+====
+
+. Create a secret named `{my-product-secrets}` and add a key named `BACKEND_SECRET` with a `Base64-encoded` string as value, as shown in the following example:
++
+--
+[source,yaml,subs="+attributes,+quotes"]
+----
+apiVersion: v1
+kind: Secret
+metadata:
+  name: {my-product-secrets}
+stringData:
+  # TODO: Add the necessary auth secrets for service-to-service auth setup
+  BACKEND_SECRET: "xxx" # Replace with your `Base64-encoded` secret
+----
+--
++
+[NOTE]
+====
+Ensure that your secret includes `BACKEND_SECRET`, used for service-to-service authentication. For structure and provisioning steps, see xref:{configuring-book-url}#provisioning-and-using-your-custom-configuration[Provisioning your custom {product} configuration].
+====
 . Click *Create*.
 . xref:{configuring-book-url}#using-the-operator-to-run-rhdh-with-your-custom-configuration[Add your {product-custom-resource-type} custom resource content].
-. On the *Create Backstage* page, click *Create*
+. On the *Create Backstage* page, click *Create*.
 
 .Verification
 

modules/installation/proc-install-rhdh-osd-gcp-helm.adoc

@@ -17,7 +17,28 @@ You can install {product-short} on {osd-short} on {gcp-short} using the {product
 . In the *Filter by keyword* box, enter {product-short} and click the *{product}* card.
 . From the {product} page, click *Create*.
 . From your cluster, copy the {ocp-short} router host (for example: `apps.<clusterName>.com`).
-. Select the radio button to configure the {product-short} instance with either the form view or YAML view. The *Form view* is selected by default.
+. Select the radio button to configure the {product-short} instance with either the form view or YAML view.
++
+[IMPORTANT]
+====
+Before deploying {product-short} using the Helm chart, you must define custom configuration settings such as the public `baseUrl` for your instance. Without setting `baseUrl`, the application cannot function correctly. You can define this configuration either through the *Form view* or the *YAML view* in the Helm install wizard.
+
+To configure the `baseUrl`, set the following values in your Helm configuration:
+[source,yaml]
+----
+global:
+  app:
+    baseUrl: https://<your-developer-hub-url>
+  backend:
+    baseUrl: https://<your-developer-hub-url>
+    cors:
+      origin: https://<your-developer-hub-url>
+----
+You can also define additional secrets, plugins, and advanced configuration in your `values.yaml` file. For full instructions, see:
+xref:{configuring-book-url}#provisioning-and-using-your-custom-configuration[Provisioning your custom {product} configuration].
+====
++
+The *Form view* is selected by default.
 +
 --
 .. Using *Form view*

modules/installation/proc-install-rhdh-osd-gcp-operator.adoc

@@ -13,12 +13,83 @@ You can install {product-short} on {osd-short} on {gcp-short} using the {product
 
 .Procedure
 
-. In the *Administrator* perspective of the {ocp-short} web console, click *Operators > OperatorHub*.
-. In the *Filter by keyword* box, enter {product-short} and click the *{product} Operator* card.
+. In the {ocp-short} web console menu, go to *Operators > OperatorHub*.
+. In the *Filter by keyword* field, enter {product-short} and click the *{product} Operator* card.
 . On the *{product} Operator* page, click *Install*.
-. In the {ocp-short} console, navigate to *Installed Operators* and select *{product} Operator*.
-. From the {product-short} Operator page, click *Create New Instance* and specify the name and namespace where you want to deploy {product-short}.
-. Configure the required settings such as Git integration, secret management, and user permissions.
+. After the installation completes, navigate to *Installed Operators* and select *Red Hat {product-short} Operator*.
+. Provision your custom configuration:
++
+--
+[source,yaml,subs="attributes+"]
+----
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: app-config-rhdh
+data:
+  "app-config-rhdh.yaml": |
+    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}
+----
+--
++
+You must create a config map named `app-config-rhdh` and a Kubernetes Secret containing the `BACKEND_SECRET`. These resources are used by the {product-short} instance for authentication and application settings.
++
+For further steps, see xref:{configuring-book-url}#provisioning-and-using-your-custom-configuration[Provisioning your custom {product} configuration].
+. Create a config map named `app-config-rhdh` that includes your `{my-app-config-file}` as shown:
++
+--
+[source,yaml,subs="attributes+"]
+----
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: app-config-rhdh
+data:
+  "app-config-rhdh.yaml": |
+    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}
+----
+--
+. Create a secret named `{my-product-secrets}` and add a key named `BACKEND_SECRET` with a `Base64-encoded` string as value:
++
+--
+[source,yaml,subs="+attributes,+quotes"]
+----
+apiVersion: v1
+kind: Secret
+metadata:
+  name: {my-product-secrets}
+stringData:
+  # TODO: Add the necessary auth secrets for service-to-service auth setup
+  BACKEND_SECRET: "xxx" # Replace with your `Base64-encoded` secret
+----
+--
+. Return to the *{product-short} Operator* page and click *Create New Instance*.
+. Specify the name and target namespace for the {product-short} deployment.
+. Configure required options such as Git integration, secrets, and user permissions.
 . Review the configuration, select deployment options, and click *Create*.
 
 .Verification

titles/install-rhdh-ocp/master.adoc

@@ -27,6 +27,12 @@ The {product} Helm chart::
 * Requires manual installation and management
 --
 
+[IMPORTANT]
+====
+You must set the `baseUrl` in `{my-app-config-file}` to match the external URL of your {product-short} instance (for example, `https://rhdh.example.com`).
+This value is required for the {product} to function correctly. If it is not set, frontend and backend services cannot communicate properly, and features may not work as expected.
+====
+
 Use the installation method that best meets your needs and preferences.
 
 .Additional resources

titles/install-rhdh-osd-gcp/master.adoc

@@ -12,6 +12,11 @@ You can install {product-short} on {osd-short} on {gcp-brand-name} ({gcp-short})
 * The {product} Operator
 * The {product} Helm chart
 
+[IMPORTANT]
+====
+You must set the `baseUrl` in `{my-app-config-file}` to match the external URL of your {product-short} instance. This value is required for the {product} to function correctly. If it is not set, frontend and backend services cannot communicate properly, and features may not work as expected.
+====
+
 // Operator procedure
 include::modules/installation/proc-install-rhdh-osd-gcp-operator.adoc[leveloffset=+1]