RHIDP-7849 Added existing modules to _Setting up and configuring your first instance_

assemblies/assembly-configuring-a-proxy.adoc

@@ -1,4 +1,5 @@
 :_mod-docs-content-type: ASSEMBLY
+:previouscontext: {context}
 :context: running-behind-a-proxy
 
 [id="{context}"]
@@ -22,3 +23,5 @@ include::modules/configuring-a-proxy/proc-configuring-proxy-in-operator-deployme
 
 include::modules/configuring-a-proxy/proc-configuring-proxy-in-helm-deployment.adoc[leveloffset=+1]
 
+:context: {previouscontext}
+!:previouscontext:

assemblies/assembly-configuring-external-postgresql-databases.adoc

@@ -1,4 +1,5 @@
 :_mod-docs-content-type: ASSEMBLY
+:previouscontext: {context}
 :context: configuring-external-postgresql-databases
 
 [id="{context}"]
@@ -22,3 +23,5 @@ include::modules/configuring-external-databases/proc-configuring-postgresql-inst
 
 include::modules/configuring-external-databases/proc-migrating-databases-to-an-external-server.adoc[leveloffset=+1]
 
+:context: {previouscontext}
+!:previouscontext:

assemblies/assembly-configuring-high-availability.adoc

@@ -1,4 +1,5 @@
 :_mod-docs-content-type: ASSEMBLY
+:previouscontext: {context}
 :context: HighAvailability
 
 [id="{context}"]
@@ -28,3 +29,6 @@ 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]
+
+:context: {previouscontext}
+!:previouscontext:

assemblies/assembly-provisioning-a-custom-configuration.adoc

@@ -1,4 +1,5 @@
 :_mod-docs-content-type: ASSEMBLY
+:previouscontext: {context}
 :context: provisioning-and-using-your-custom-configuration
 
 [id="{context}"]
@@ -27,3 +28,5 @@ include::modules/configuring/proc-mounting-additional-files-in-your-custom-confi
 
 include::modules/configuring/proc-using-the-helm-chart-to-run-rhdh-with-your-custom-configuration.adoc[leveloffset=+1]
 
+:context: {previouscontext}
+!:previouscontext:

modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc

@@ -385,7 +385,7 @@ auth:
 `additionalScopes`::
 Optional for additional scopes.
 To add scopes for the application registration, uncomment and enter the list of scopes that you want to add.
-The default and mandatory value lists following scopes: 
+The default and mandatory value lists following scopes:
 * `openid`
 * `offline_access`
 * `profile`
@@ -463,6 +463,7 @@ This resolver looks up the user by matching their Microsoft email to the user en
 Configure the sign-in resolver to bypass the user provisioning requirement in the {product-short} software catalog.
 +
 WARNING: Use `dangerouslyAllowSignInWithoutUserInCatalog` to explore {product-short} features, but do not use it in production.
+endif::[]
 
 .Verification
 . To verify user and group provisioning, check the console logs for `MicrosoftGraphOrgEntityProvider` events.

modules/configuring/con-checklist-to-run-your-first-rhdh-instance-in-production.adoc

@@ -0,0 +1,24 @@
+:_mod-docs-content-type: CONCEPT
+
+[id="checklist-to-run-your-first-rhdh-instance-in-production_{context}"]
+= Checklist to run your first {product} ({product-very-short}) instance in production.
+
+With the default configuration, {product-short} runs with a minimal feature set that does not require secure connection to external services such as an identity provider, a Git provider, and external PostgreSQL and Redis databases.
+
+Using critical features therefore requires following additional configuration:
+
+For resiliency::
+* Use an external PostgreSQL database.
+* Enable high-availability.
+
+For performance::
+* Enable assets caching to an external Redis database.
+
+For security::
+* Use secure connections to your external services.
+* Provision users and enable authentication.
+* Enable role-based access control, and configure the permission policy by using the Web UI.
+
+For adapting to your environment::
+* Enable GitHub repository discovery.
+* Customize {product-short} appearance with your logo.

modules/installation/proc-configuring-an-rhdh-instance-with-tls-in-kubernetes.adoc → modules/configuring/proc-configuring-an-rhdh-instance-with-tls-in-kubernetes.adoc

@@ -1,6 +1,6 @@
 :_mod-docs-content-type: PROCEDURE
 
-[id="proc-configuring-an-rhdh-instance-with-tls-in-kubernetes_{context}"]
+[id="configuring-an-rhdh-instance-with-tls-in-kubernetes_{context}"]
 = 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.

modules/configuring/proc-preparing-your-external-services.adoc

@@ -0,0 +1,118 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="preparing-your-external-services"]
+= Preparing your external services
+
+{product} relies on external services.
+Prepare the following required external services:
+
+PostgreSQL database::
+{product-short} stores data in a PostgreSQL database.
+Use an external database for resiliency and include it in your disaster recovery plan.
+
+Redis cache::
+For efficiency, {product-short} caches plugin and Techdocs assets when your provide a Redis cache server.
+
+GitHub API access::
+Provide credentials to a GitHub app to enable access to the GitHub API for repository discovery.
+
+Connection to your identity provider::
+Provide credentials to your identity provider to enable user provisioning and authentication.
+
+.Procedure
+* Get your external PostgreSQL database connection strings and certificates.
+postgres-host::: Your PostgreSQL instance Domain Name System (DNS) or IP address.
+postgres-port::: Your PostgreSQL instance port number, such as 5432.
+postres-username::: The user name to connect to your PostgreSQL instance.
+postgres-password::: The password to connect to your PostgreSQL instance.
+postgres-ca.pem:::
+postgres-key.key:::
+postgres-crt.pem:::
+For security, use TLS certificates to secure the connection to the database.
+
+. Get your Redis cache server connection string, such as `rediss://user:[email protected]:6379`.
+For security, consider using a `rediss` secure server connection.
+
+. Create a GitHub App to allow {product-short} to access the GitHub API for repository.
+Opt for a GitHub App instead of an OAuth app to use fine-grained permissions, gain more control over which repositories the application can access, and use short-lived tokens.
+
+.. link:https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app[Register a GitHub App] with the following configuration:
+
+GitHub App name::
+Enter a unique name identifying your GitHub App, such as `integrating-with-rhdh-__<GUID>__`.
+
+Homepage URL::
+Enter your {product-short} URL: `pass:c,a,q[{my-product-url}]`.
+
+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.
+
+App permissions::
+Select permissions to define the level of access for the app.
+Adapt permissions to your needs:
+
+Reading software components:::
+
+Contents::::
+`Read-only`
+
+Commit statuses::::
+`Read-only`
+
+Reading organization data:::
+
+Members::::
+`Read-only`
+
+Publishing software templates:::
+Set permissions if you intend to use the same GitHub App for software templates.
+
+Administration::::
+`Read & write` (for creating repositories)
+
+Contents::::
+`Read & write`
+
+Metadata::::
+`Read-only`
+
+Pull requests::::
+`Read & write`
+
+Issues::::
+`Read & write`
+
+Workflows::::
+`Read & write` (if templates include GitHub workflows)
+
+Variables::::
+`Read & write` (if templates include GitHub Action Repository Variables)
+
+Secrets::::
+`Read & write` (if templates include GitHub Action Repository Secrets)
+
+Environments::::
+`Read & write` (if templates include GitHub Environments)
+
+Organization permissions::
+Members:::
+`Read-only`
+
+Where can this GitHub App be installed?::
+Select `Only on this account`.
+
+.. In the *General* -> *Clients secrets* section, click *Generate a new client secret*.
+
+.. In the *General* -> *Private keys* section, click *Generate a private key*.
+
+.. In the *Install App* tab, choose an account to install your GitHub App on.
+
+.. Save the following values for the next step:
+
+* **App ID**
+* **Client ID**
+* **Client secret**
+* **Private key**

modules/configuring/proc-provisioning-your-custom-configuration.adoc

@@ -14,50 +14,48 @@ Your changes on this configuration might get reverted on {product-short} restart
 .Prerequisites
 * By using the {platform-cli-link}, you have access, with developer permissions, to the {platform-generic} cluster aimed at containing your {product-short} instance.
 
+ifeval::["{context}" == "setting-up-and-configuring-your-first-rhdh-instance"]
+include::snip-provisioning-your-custom-configuration-prerequisites-in-setting-up-and-configuring-your-first-rhdh-instance-context.adoc[]
+endif::[]
+
 .Procedure
-. Author your custom `_<my_product_secrets>_.txt` file to provision your secrets as environment variables values in {a-platform-generic} secret,
-rather than in clear text in your configuration files.
-It contains one secret per line in `KEY=value` form.
+. For security, store your secrets as environment variables values in an {ocp-short} secret, rather than in clear text in your configuration files.
+Collect all your secrets in the `secrets.txt` file, with one secret per line in `KEY=value` form.
 +
-* {authentication-book-link}[Enter your authentication secrets].
+--
+ifeval::["{context}" == "setting-up-and-configuring-your-first-rhdh-instance"]
+include::snip-provisioning-your-custom-configuration-secrets-steps-in-setting-up-and-configuring-your-first-rhdh-instance-context.adoc[]
+endif::[]
+ifeval::["{context}" != "setting-up-and-configuring-your-first-rhdh-instance"]
+include::snip-provisioning-your-custom-configuration-secrets-steps-in-default-context.adoc[]
+endif::[]
+--
 
 . Author your custom `{my-app-config-file}` file.
 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.
++
+--
+include::snip-provisioning-your-custom-configuration-appconfig-step-with-optional-steps-{optional-steps}d.adoc[]
+--
 
-** To prepare a deployment with the {product} Operator on {platform}, 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:
+. Author your custom `dynamic-plugins.yaml` file to enable plugins.
+By default, {product-short} enables a minimal plugin set, and disables plugins that require configuration or secrets, such as the GitHub repository discovery plugin and the Role-based access control (RBAC) plugin.
 +
-.Configuring the `baseUrl` in `{my-app-config-file}`
-====
-[source,yaml,subs="+attributes,+quotes"]
+Enable the GitHub repository discovery and the RBAC features:
++
+.`dynamic.plugins.yaml`
+[source,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}
+includes:
+  - dynamic-plugins.default.yaml
+plugins:
+  - package: ./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-github
+    disabled: false
+  - package: ./dynamic-plugins/dist/backstage-community-plugin-rbac
+    disabled: false
 ----
-====
-
-** Optionally, enter your configuration such as:
-
-*** {authentication-book-link}[{authentication-book-title}].
-*** {authorization-book-link}[{authorization-book-title}].
-*** {customizing-book-link}[Customization].
 
 . Provision your custom configuration files to your {platform} cluster.
 
@@ -68,21 +66,30 @@ backend:
 $ oc create namespace {my-product-namespace}
 ----
 
-.. Provision your `{my-app-config-file}` file to the `{my-app-config-config-map}` config map in the _<{my-product-namespace}>_ project.
+.. Provision your `{my-app-config-file}` and `dynamic-plugins.yaml` files respectively to the `{my-app-config-config-map}`, and `dynamic-plugins-rhdh` config maps in the _<{my-product-namespace}>_ project.
 +
 [source,terminal,subs="+attributes,+quotes"]
 ----
 $ oc create configmap {my-app-config-config-map} --from-file={my-app-config-file} --namespace={my-product-namespace}
+$ oc create configmap dynamic-plugins-rhdh --from-file=dynamic-plugins.yaml --namespace={my-product-namespace}
 ----
++
+Alternatively,
+link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html-single/nodes/index#nnodes-pods-configmap-create-from-console_configmaps[create the config maps by using the web console].
 
-.. Provision your `_<my_product_secrets>_.txt` file to the `_<my_product_secrets>_` secret in the _<{my-product-namespace}>_ project.
+.. Provision your `secrets.txt` file to the `{my-product-secrets}` secret in the _<{my-product-namespace}>_ project.
 +
 [source,terminal,subs="+attributes,+quotes"]
 ----
-$ oc create secret generic `_<my_product_secrets>_` --from-file=`_<my_product_secrets>_.txt` --namespace={my-product-namespace}
+$ oc create secret generic {my-product-secrets} --from-file=secrets.txt --namespace={my-product-namespace}
 ----
-
-.Next steps
-* To use an external PostgreSQL database, {configuring-book-link}configuring-external-postgresql-databases[provision your PostgreSQL database secrets].
-* To enable dynamic plugins, {installing-and-viewing-plugins-book-link}[provision your dynamic plugins config map].
-* To configure authorization by using external files, {authorization-book-link}#managing-authorizations-by-using-external-files[provision your RBAC policies config map].
++
+Alternatively,
+link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html-single/nodes/index#nodes-pods-secrets-creating-web-console-secrets_nodes-pods-secrets[create the secret by using the web console].
+
+ifeval::["{context}" == "setting-up-and-configuring-your-first-rhdh-instance"]
+include::snip-provisioning-your-custom-configuration-next-steps-in-setting-up-and-configuring-your-first-rhdh-instance-context.adoc[]
+endif::[]
+ifeval::["{context}" != "setting-up-and-configuring-your-first-rhdh-instance"]
+include::snip-provisioning-your-custom-configuration-next-steps-in-default-context.adoc[]
+endif::[]