docs: additional documentation (#82)

Author: vburckhardt

README.md

@@ -27,9 +27,11 @@ To deploy this architecture, follow these steps.
 Before deploying the deployable architecture, ensure you have:
 
 * Created an API key in the target account with sufficient permissions. The target account is the account that will be hosting the resources deployed by this deployable architecture. See [instructions](https://cloud.ibm.com/docs/account?topic=account-userapikey&interface=ui) Note the API key, as it will be used later. On evaluation environments, you may simply grant `Administrator` role on `IAM Identity Service`, `All Identity and Access enabled services` and `All Account Management` services. If you need to narrow down further access, for a production environment for instance, the minimum level of permissions is indicated in the [Permission tab](https://cloud.ibm.com/catalog/7df1e4ca-d54c-4fd0-82ce-3d13247308cd/architecture/Retrieval_Augmented_Generation_Pattern-5fdd0045-30fc-4013-a8bc-6db9d5447a52?kind=terraform&format=stack&version=32db3936-66fe-4b04-bbc8-61d5676a89f1#permissions) of the deployable architecture.
-* (Recommended) Created or access to a signing key, which is the base64 key obtained from `gpg --gen-key` (if not generated before or expired) and then exported via `gpg --export-secret-key <Email Address> | base64` command. See the [devsecops image signing page](https://cloud.ibm.com/docs/devsecops?topic=devsecops-devsecops-image-signing#cd-devsecops-gpg-export) for details. Key note of the key for later. The signing key is not required to deploy all of the Cloud resources created by this deployable architecture, but is necessary to get the automation to build and deploy the sample application.
+* (Recommended to ensure successful sample app deployment) Created or have access to a signing key, which is the base64 key obtained from `gpg --gen-key` (if not generated before or expired) and then exported via `gpg --export-secret-key <Email Address> | base64` command. See the [devsecops image signing page](https://cloud.ibm.com/docs/devsecops?topic=devsecops-devsecops-image-signing#cd-devsecops-gpg-export) for details. Keep note of the key for later. The signing key is not required to deploy all of the Cloud resources created by this deployable architecture, but is necessary to get the automation to build and deploy the sample application.
 * (Optional) Installed the IBM Cloud CLI's Project add-on using the `ibmcloud plugin install project` command. More information is available [here](https://cloud.ibm.com/docs/cli?topic=cli-projects-cli).
 
+Ensure that you are familiar with the "Important Deployment Considerations" located at the bottom of this document.
+
 ## 2. Deploy the Stack in a New Project from Catalog
 
 * Locate the [tile](https://cloud.ibm.com/catalog/7a4d68b4-cf8b-40cd-a3d1-f49aff526eb3/architecture/Retrieval_Augmented_Generation_Pattern-5fdd0045-30fc-4013-a8bc-6db9d5447a52-global) for the Deployable Architecture in the IBM Cloud Catalog.
@@ -71,8 +73,8 @@ You should be directed to a screen looking like:
 ![validate](./images/min/5-validate.png)
 
 Two approaches to deploy the architecture:
-1. Through the UI - note that using the UI requires a large number of clicks each elements on the architecture stack.
-2. Automated - se the  script `./deploy-many.sh` is provided.
+1. Through the UI
+2. Automated - `./deploy-many.sh` is provided.
 
 ### Approach 1: Deployment through the UI
 
@@ -90,7 +92,7 @@ Two approaches to deploy the architecture:
 
 4. Wait for deployment
 
-5. Repeat step 1 for the next configuration in the architecture.
+5. Repeat step 1 for the next configuration in the architecture. Note that as you progress in deploying the initial base configuration, you will be given the option to validate and deploy multiple configuration in parallel.
 
 ### Approach 2: Run ./deploy-many.sh
 
@@ -107,6 +109,39 @@ Tips: If deployment fail for one of the configuration, you may re-run the script
 
 ## 5. Post deployment steps
 
-At this point, all of the infrastructure is deployed in the target account. The initial build for the sample app has also started in the DevOps service, and the app is deployed to IBM Cloud Code Engine.
+At this point, the infrastructure has been successfully deployed in the target account, and the initial build of the sample application has started in the newly-provisioned DevOps service.
+
+### Monitoring the Build and Deployment
+
+To monitor the build and deployment of the application, follow these steps:
+1. **Access the DevOps Toolchains View**: Navigate to the [DevOps / Toolchains view](https://cloud.ibm.com/devops/toolchains) in the target account.
+2. **Select the Resource Group and Region**: Choose the resource group and region where the infrastructure was deployed. The resource group name is based on the prefix and resource_group_name inputs of the deployable architecture.
+3. **Select the Toolchain**: Select "RAG Sample App-CI-Toolchain"
+    ![toolchain](./images/min/8-toolchain.png)
+4. **Access the Delivery Pipeline**: In the toolchain view, select ci-pipeline under Delivery pipeline
+    ![toolchain](./images/min/9-pipeline.png)
+5. **View the CI Pipeline Status**: The current status of the CI pipeline execution can be found under the "rag-webhook-trigger" section.
+
+### Verifying the Application Deployment
+
+Once the initial run of the CI pipeline complete, you should be able to view the application running in the created [Code Engine project](https://cloud.ibm.com/codeengine/projects).
+
+
+### Enabling Watson Assistant
+
+After the application has been built and is running in Code Engine, there are additional steps specific to the sample app that need to be completed to fully enable Watson Assistant in the app. To complete the installation, follow the steps outlined in the [application README.md file](https://github.com/IBM/gen-ai-rag-watsonx-sample-application/blob/main/artifacts/artifacts-README.md).
+
+
+# 6. Important Deployment Considerations
+
+## API Key Requirements
+
+The deployable architecture can only be deployed with an API Key associated with a user. It is not compatible with API Keys associated with a serviceId. Additionally, it cannot be deployed using the Project trusted profile support.
+
+## Known UI Issue: "Unable to validate your configuration"
+
+After approving the configuration, you may encounter an error message stating "Unable to validate your configuration". This is a known UI issue that can be resolved by simply **refreshing your browser window**. This will allow you to continue with the deployment process.
+
+## Using the ./deploy-many.sh Script
 
-There are some remaining steps, specific to the sample app, that can be completed to fully enable Watson assistant in the app. To complete the installation - follow the steps at https://github.com/IBM/gen-ai-rag-watsonx-sample-application/blob/main/artifacts/artifacts-README.md
+The provided ./deploy-many.sh script is designed to deploy the stack of configurations as provided out of the box. If you make any changes to the stack definition in your project, besides specifying inputs, you should deploy your version through the Project UI instead of using the script.

deploy-many.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-set -x
+# set -x
 
 function parse_params() {
   PROJECT_NAME=$1