Docusuarus upgrade and doc updates

docs-source/site/docs/intro.md

@@ -1,7 +1,39 @@
 ---
 sidebar_position: 1
 ---
-
 # Oracle Backend for Microservices and AI
 
-Oracle Backend for Microservices and AI allows developers to build microservices in Helidon and/or Spring Boot and provisions a “backend as a service” with Oracle Database and other infrastructure components that operate on multiple clouds. Oracle Backend for Microservices and AI vastly simplifies the task of building, testing, and operating microservices platforms for reliable, secure, and scalable enterprise applications.
+## Accelerate Your Journey to Cloud-Native Applications
+
+Oracle Backend for Microservices and AI (OBaaS) is a comprehensive platform that transforms how developers build, deploy, and scale modern applications. By combining the power of Oracle Database with a complete microservices infrastructure, OBaaS eliminates the complexity of cloud-native development and empowers teams to focus on innovation rather than infrastructure.
+
+## Build Faster, Scale Smarter
+
+Whether you're building with Helidon, Spring Boot, or integrating AI capabilities, OBaaS provides a production-ready "backend as a service" that handles the heavy lifting. Deploy across multiple clouds with confidence, knowing that your platform is built on proven Oracle technology designed for enterprise-grade reliability, security, and performance.
+
+## Why Choose Oracle Backend for Microservices and AI?
+
+### Developer Experience First
+
+Write code in your preferred framework—Helidon or Spring Boot—while OBaaS handles service discovery, configuration management, API gateways, and data persistence. Spend less time configuring infrastructure and more time building features that matter to your business.
+
+### Enterprise-Grade Infrastructure
+
+Built on Oracle Database and designed for mission-critical workloads, OBaaS provides:
+
+- **Reliability**: High availability and disaster recovery built in
+- **Security**: Enterprise-grade security controls and compliance
+- **Scalability**: Elastic scaling to meet demand automatically
+- **Performance**: Optimized for low latency and high throughput
+
+### AI-Ready Platform
+
+Leverage the power of Oracle Database 23ai to integrate artificial intelligence and machine learning directly into your applications. Build intelligent services that learn and adapt without the complexity of managing separate AI infrastructure.
+
+### Multi-Cloud Flexibility
+
+Deploy on Oracle Cloud Infrastructure, other cloud providers, or hybrid environments. OBaaS provides consistent operations and portability across clouds, giving you freedom from vendor lock-in.
+
+### Simplified Operations
+
+OBaaS vastly simplifies the task of building, testing, and operating microservices platforms. From development through production, automated workflows and integrated tooling streamline every phase of the application lifecycle.

docs-source/site/docs/setup/database.md

@@ -1,36 +1,67 @@
 ---
-title: Prepare and Install the OBaaS Database Helm chart
+title: Prepare and Install the OBaaS Database Helm Chart
 sidebar_position: 9
 ---
-## Prepare and Install the OBaaS Database Helm chart
+## Prepare and Install the OBaaS Database Helm Chart
 
-For this step, you will need the **obaas-db** directory in which you will see the following files:
+## Overview
+
+This guide provides instructions for preparing and installing the OBaaS Database Helm chart in your Kubernetes cluster.
+
+## Prerequisites
+
+Navigate to the `obaas-db` directory containing the Helm chart files:
 
 ```bash
 cd obaas-db/
 ls
-Chart.yaml scripts templates values.yaml
 ```
 
-You must edit the **values.yaml** file as follows:
+Expected output:
+
+```text
+Chart.yaml  scripts  templates  values.yaml
+```
+
+## Configuration
+
+### Editing values.yaml
+
+Before installation, edit the `values.yaml` file according to your environment requirements.
+
+#### Private Repository Configuration
 
-- If you are using a private repository, you must update each **image** entry to point to your private repository instead of the public repositories.
+If you are using a private repository, update each `image` entry to point to your private repository instead of the public repositories.
 
-- (Optional) If you want to install any components in this chart into their own separate namespace, you can override the global namespace by setting a value in the **namespace** property inside the section for that component.
+#### Namespace Configuration (Optional)
 
-**Important note**: Please pause to double check all of the values are correct. If there are any errors here, the database provisioning will fail.
+To install components into separate namespaces, override the global namespace by setting a value in the `namespace` property inside the component's section.
 
-Install the Helm chart using the following command (The `--debug` flag is optional and enables verbose output from Helm).
+:::warning Important
+Double-check all values before proceeding. Incorrect values will cause the database provisioning to fail.
+:::
 
-- global.obaasName="obaas-dev" - Sets the OBaaS instance name.
-- global.targetNamespace="obaas-dev" - Specifies the target namespace (*OPTIONAL*, only needed if you want to override the default namespace).
+## Installation
 
-**Note**: If you are installing multiple OBaaS instances in your cluster, each one MUST have a different release name, `obaasName` and `targetNamespace`.
+### Single Instance Installation
+
+Install the Helm chart using the following command:
 
 ```bash
-helm --debug install obaas-db --set global.obaasName="obaas-dev" --set global.targetNamespace="obaas-dev" ./
+helm --debug install obaas-db \
+  --set global.obaasName="obaas-dev" \
+  --set global.targetNamespace="obaas-dev" \
+  ./
 ```
 
+**Parameters:**
+
+- `global.obaasName`: Sets the OBaaS instance name
+- `global.targetNamespace`: Specifies the target namespace (optional, only needed to override the default namespace)
+- `--debug`: Optional flag that enables verbose output from Helm
+
+**Expected output:**
+
 ```text
 NAME: obaas-db
 LAST DEPLOYED: Sun Aug 17 13:09:20 2025
@@ -40,29 +71,57 @@ REVISION: 1
 TEST SUITE: None
 ```
 
-When the installation has completed, you can use `helm ls` command to view the installed charts:
+### Multiple Instance Installation
 
-```text
-NAME               	NAMESPACE	REVISION	UPDATED                             	STATUS  	CHART                    	APP VERSION
-obaas-db           	default  	1       	2025-09-12 13:51:23.751199 -0500 CDT	deployed	OBaaS-db-0.1.0           	2.0.0-M4   
-obaas-observability	default  	1       	2025-09-12 13:45:43.113298 -0500 CDT	deployed	OBaaS-observability-0.1.0	2.0.0-M4   
-obaas-prereqs      	default  	1       	2025-09-12 13:37:16.026781 -0500 CDT	deployed	OBaaS-Prerequisites-0.0.1	2.0.0-M4  
+When installing multiple OBaaS instances in your cluster, each instance must have unique values for:
+
+- Release name
+- `obaasName`
+- `targetNamespace`
+
+**Example for development instance:**
+
+```bash
+helm --debug install obaas-db \
+  --set global.obaasName="obaas-dev" \
+  --set global.targetNamespace="obaas-dev" \
+  ./
 ```
 
-If you overrode the namespace for this component, you will see a new namespace called **oracle-database-operator-system** (for example) and the following pods. Otherwise the pods will be in the **obaas-dev** namespace (or whatever name you chose). 
+**Example for production instance:**
 
-![DB Operator pods](media/image6.png)
+```bash
+helm --debug install obaas-prod-db \
+  --set global.obaasName="obaas-prod" \
+  --set global.targetNamespace="obaas-prod" \
+  ./
+```
+
+## Verification
 
-**Note**: If you are installing multiple OBaaS instances in your cluster, each one MUST have a different release name, `obaasName` and `targetNamespace`.  For example (The `--debug` flag is optional and enables verbose output from Helm):
+### View Installed Charts
 
-For obaas-dev:
+After installation completes, view the installed Helm charts:
 
 ```bash
-helm --debug install obaas-db --set global.obaasName="obaas-dev" --set global.targetNamespace="obaas-dev" ./
+helm ls
 ```
 
-For obaas-prod:
+**Expected output:**
+
+```text
+NAME               	NAMESPACE	REVISION	UPDATED                             	STATUS  	CHART                    	APP VERSION
+obaas-db           	default  	1       	2025-09-12 13:51:23.751199 -0500 CDT	deployed	OBaaS-db-0.1.0           	2.0.0-M4   
+obaas-observability	default  	1       	2025-09-12 13:45:43.113298 -0500 CDT	deployed	OBaaS-observability-0.1.0	2.0.0-M4   
+obaas-prereqs      	default  	1       	2025-09-12 13:37:16.026781 -0500 CDT	deployed	OBaaS-Prerequisites-0.0.1	2.0.0-M4  
+```
+
+### Verify Pods and Namespaces
+
+If you overrode the namespace for this component, you will see a new namespace (e.g., `oracle-database-operator-system`) with the following pods. Otherwise, the pods will be in your target namespace (e.g., `obaas-dev`).
 
 ```bash
-helm --debug install obaas-prod-db --set global.obaasName="obaas-prod" --set global.targetNamespace="obaas-prod" ./
+kubectl get pods -n oracle-database-operator-system
 ```
+
+![DB Operator pods](media/image6.png)

docs-source/site/docs/setup/namespace.md

@@ -2,20 +2,148 @@
 title: Create Namespace(s) for OBaaS
 sidebar_position: 6
 ---
-## Create the namespace(s) for the OBaaS installation(s)
+## Create Namespace(s) for OBaaS
 
-EACH instance of OBaaS must be installed in its own dedicated/unique namespace.
+## Overview
 
-**Note**: You will only install the **obaas-prereqs** chart once per cluster, all other charts are installed once per OBaaS instance. The **obaas-prereqs** chart contains items that are cluster-wide and shared by all OBaaS instances in a cluster. If you are going to install multiple OBaaS instances (which is not supported in 2.0.0-M4) we recommend that you put the **obaas-prereqs** chart in its own namespace, separate from all OBaaS instances.
+Each OBaaS instance requires its own dedicated namespace for isolation and organization within your Kubernetes cluster.
 
-To create the namespace(s), use the following command(s). For example, to create two installations called `obaas-dev` and `obaas-prod`:
+## Namespace Requirements
+
+### Instance Isolation
+
+Each OBaaS instance must be installed in its own unique namespace. This ensures:
+
+- Resource isolation between instances
+- Independent lifecycle management
+- Clear separation of concerns
+- Simplified troubleshooting and maintenance
+
+### Prerequisites Chart Namespace
+
+The `obaas-prereqs` chart has special considerations:
+
+- Installed **once per cluster** (not per instance)
+- Contains cluster-wide components shared by all OBaaS instances
+- Should be installed in its own dedicated namespace, separate from OBaaS instances
+
+:::info Multiple Instance Support
+Multiple OBaaS instances are not supported in version 2.0.0-M4. This capability is planned for future releases.
+:::
+
+## Creating Namespaces
+
+### Single Instance
+
+For a single OBaaS installation, create one namespace:
+
+```bash
+kubectl create ns obaas-dev
+```
+
+Verify the namespace was created:
+
+```bash
+kubectl get ns obaas-dev
+```
+
+Expected output:
+
+```text
+NAME        STATUS   AGE
+obaas-dev   Active   5s
+```
+
+### Multiple Instances (Future Support)
+
+When multiple instances are supported, create a namespace for each instance. For example, to create development and production installations:
+
+**Development namespace:**
 
 ```bash
 kubectl create ns obaas-dev
 ```
 
+**Production namespace:**
+
 ```bash
 kubectl create ns obaas-prod
 ```
 
-Change the value to the desired name(s).
+**Verify all namespaces:**
+
+```bash
+kubectl get ns | grep obaas
+```
+
+Expected output:
+
+```text
+obaas-dev    Active   10s
+obaas-prod   Active   5s
+```
+
+## Namespace Naming Conventions
+
+When naming your namespaces, consider the following best practices:
+
+- Use lowercase letters, numbers, and hyphens only
+- Keep names descriptive and meaningful (e.g., `obaas-dev`, `obaas-prod`, `obaas-staging`)
+- Include environment indicators for clarity
+- Avoid special characters or spaces
+- Keep names concise but descriptive
+
+**Examples of good namespace names:**
+
+```bash
+obaas-dev
+obaas-production
+obaas-test
+obaas-staging
+obaas-demo
+```
+
+## Verification
+
+After creating namespaces, verify they exist and are active:
+
+```bash
+kubectl get namespaces
+```
+
+You should see your newly created OBaaS namespaces in the output with `Active` status.
+
+## Troubleshooting
+
+### Namespace Already Exists
+
+If you receive an error that the namespace already exists:
+
+```bash
+kubectl get ns obaas-dev
+```
+
+If the namespace exists but you want to start fresh, delete it first:
+
+```bash
+kubectl delete ns obaas-dev
+```
+
+:::warning Data Loss
+Deleting a namespace will remove all resources within it. Ensure you have backups if needed before deleting a namespace.
+:::
+
+### Namespace Stuck in Terminating State
+
+If a namespace is stuck in "Terminating" state:
+
+```bash
+kubectl get ns obaas-dev
+```
+
+Check for resources preventing deletion:
+
+```bash
+kubectl api-resources --verbs=list --namespaced -o name | \
+  xargs -n 1 kubectl get --show-kind --ignore-not-found -n obaas-dev
+```