Documentation update (#1109)

* Documentation update

Author: andytael

docs-source/site/docs/deploy/dbaccess.md

@@ -16,19 +16,23 @@ Create a secret with database access information. This secret is used by the app
 
 For example if you have the following information:
 
-- name: `Your database name`. For example `helmdb`
-- username: `Your database user name`. For example `phonebook`
-- password: `Your database user password`. For example `Welcome-12345`
-- service: `Your servicename`. For example `helmdb_tp`
+- `db.name:` Your database name. For example `helmdb`
+- `db.username:` Your database user name. For example `phonebook`
+- `db.password:` Your database user password. For example `Welcome-12345`
+- `db.service:` Your servicename. For example `helmdb_tp`
+- `db.lb_username` Your Liquibase username.
+- `db.lb_password` Your Liquibase user password.
 
 Create a Kubernetes secret (in this example, `phonebook-db-secrets` in the `obaas-dev` namespace):
 
 ```bash
 kubectl -n obaas-dev create secret generic phonebook-db-secrets \
-  --from-literal=name=helmdb \
-  --from-literal=username=phonebook \
-  --from-literal=password=Welcome-12345 \
-  --from-literal=service=helmdb_tp
+  --from-literal=db.name=helmdb \
+  --from-literal=db.username=phonebook \
+  --from-literal=db.password=Welcome-12345 \
+  --from-literal=db.service=helmdb_tp \
+  --from-literal=db.lb_username=phonebook \
+  --from-literal=db.lb_password=Welcome-12345
 ```
 
 You can verify the values by running the following command (this is for the `username` value):
@@ -70,7 +74,7 @@ args:
   sql $(DB_USER)/$(DB_PASSWORD)@$(TNS_ALIAS) @/tmp/run.sql
 ```
 
-Update the `env:` section to reference the correct secret and keys (here using `obaas-db-secrets`):
+Update the `env:` section to reference the correct secret and keys (here using `obaas-db-secrets`, this is not the same secret as been created above.):
 
 ```yaml
 env:

docs-source/site/docs/observability/acces.md

@@ -4,14 +4,14 @@ sidebar_position: 2
 ---
 ## How to access SigNoz
 
-1. Get the _admin_ email and password for SigNoz
+1. Get the _admin_ email and password for SigNoz. Replace the example namespace `observability` with the namespace where SigNoz is deployed.
 
    ```shell
    kubectl -n observability get secret signoz-authn -o jsonpath='{.data.email}' | base64 -d
    kubectl -n observability get secret signoz-authn -o jsonpath='{.data.password}' | base64 -d
    ```
 
-1. Expose the SigNoz user interface (UI) using this command:
+1. Expose the SigNoz user interface (UI) using this command. Replace the example namespace `observability` with the namespace where SigNoz is deployed:
 
    ```shell
    kubectl -n observability port-forward svc/obaas-signoz-frontend 3301:3301

docs-source/site/docs/platform/adminserver.md

@@ -0,0 +1,25 @@
+---
+title: Spring Boot Admin
+sidebar_position: 9
+---
+## Spring Boot Admin
+
+Spring Boot Admin works by registering Spring Boot applications that expose Actuator endpoints. Each application's health and metrics data is polled by Spring Boot Admin Server, which aggregates and displays this information in a web dashboard. The registered applications can either self-register or be discovered using service discovery tools like Eureka or Consul. Through the dashboard, users can monitor the health, memory usage, logs, and more for each application, and even interact with them via management endpoints for tasks like restarting or updating configurations.
+
+[Spring Boot Admin Documentation](https://docs.spring-boot-admin.com/3.5.5/docs/installation-and-setup/)
+
+### Installing Spring Boot Admin
+
+Spring Boot Admin will be installed if the `admin-server.enabled` is set to `true` in the `values.yaml` file. The default namespace for Spring Boot Admin is `admin-server`.
+
+### Access Spring Boot Admin Web Interface
+
+To access the Spring Boot Admin Web Interface, use kubectl port-forward to create a secure channel to `service/admin-server`. Run the following command to establish the secure tunnel (replace the example namespace `obaas-dev` with the namespace where the Spring Boot Admin Server is deployed):
+
+```shell
+kubectl port-forward -n obaas-dev svc/admin-server 8989
+```
+
+Open the [Spring Boot Admin dashboard](http://localhost:8989)
+
+![Spring Boot Admin Server](images/admin-server.png)

docs-source/site/docs/platform/apisix.md

@@ -0,0 +1,35 @@
+---
+title: Apache APISIX
+sidebar_position: 1
+---
+## Apache APISIX
+
+[Apache APISIX](https://apisix.apache.org) is an open source cloud native API platform that supports the full lifecycle of API management including publishing, traffic management, deployment strategies, and circuit breakers.
+
+### Installing APISIX
+
+Apache APISIX will be installed if the `apisix.enabled` is set to `true` in the `values.yaml` file. The default namespace for Apache APISIX is `apisix`.
+
+### Accessing Apache APISIX
+
+Oracle Backend for Microservices and AI deploys the Apache APISIX Gateway and Dashboard in the `apisix` namespace by default. The gateway is exposed via an external load balancer and an ingress controller.
+
+To access the Apache APISIX APIs, use kubectl port-forward to create a secure channel to `service/apisix-admin`. Run the following command to establish the secure tunnel (replace the example namespace `obaas-dev` with the namespace where APISIX is deployed):
+
+```shell
+kubectl port-forward -n obaas-dev svc/apisix-admin 9180
+```
+
+### Retrieving admin key
+
+To access the APISIX APIs, you need the admin key. Retrieve it with the following command (replace the example namespace `obaas-dev` with the namespace where APISIX is deployed):
+
+```shell
+export admin_key=$(kubectl -n obaas-dev get configmap apisix -o yaml | yq '.data."config.yaml"' | yq '.deployment.admin.admin_key[] | select(.name == "admin") | .key')
+```
+
+Test the admin key by running a simple curl command; it should return the list of configured routes.
+
+```shell
+curl http://127.0.0.1:9180/apisix/admin/routes -H "X-API-key: $admin_key" -X GET
+```

docs-source/site/docs/platform/conductor.md

@@ -0,0 +1,93 @@
+---
+title: Conductor Workflow Orchestration
+sidebar_position: 2
+---
+## Conductor
+
+:::important
+Conductor will be replaced with Oracle Transaction Manager for Microservices, which will include the Conductor Server as a component of the product
+:::
+
+Conductor is a workflow orchestration platform, originally developed at Netflix, designed to coordinate long-running, distributed workflows across microservices by defining tasks, dependencies, and retries, while providing scalability, fault tolerance, and operational visibility through a centralized engine.
+
+[Conductor OSS Documentation](https://docs.conductor-oss.org)
+
+### Installing Conductor
+
+Conductor will be installed if the `conductor-server.enabled` is set to `true` in the `values.yaml` file. The default namespace for Conductor is `conductor-server`.
+
+### API Specification
+
+[API Specification](https://docs.conductor-oss.org/documentation/api/index.html)
+
+### Accessing Conductor APIs
+
+To access the Conductor APIs, use kubectl port-forward to create a secure channel to `service/conductor-server`. Run the following command to establish the secure tunnel (replace the example namespace `obaas-dev` with the namespace where the Conductor Server is deployed):
+
+```shell
+kubectl port-forward -n obaas-dev svc/conductor-server 8080
+```
+
+### Testing the Conductor service
+
+You can test the Conductor service by running the sample workflow provided. Save the content into a file called `first_simple_workflow.json` and then execute the following command:
+
+```shell
+curl -X POST 'http://localhost:8080/api/metadata/workflow' \
+-H 'Content-Type: application/json' \
+-d @first_sample_workflow.json
+```
+
+```json
+ 
+    {
+        "name": "first_sample_workflow",
+        "description": "First Sample Workflow",
+        "version": 1,
+        "tasks": [
+            {
+                "name": "get_population_data",
+                "taskReferenceName": "get_population_data",
+                "inputParameters": {
+                    "http_request": {
+                        "uri": "https://restcountries.com/v3.1/name/united%20states?fields=name,population",
+                        "method": "GET"
+                    }
+                },
+                "type": "HTTP"
+            }
+        ],
+        "inputParameters": [],
+        "outputParameters": {
+            "data": "${get_population_data.output.response.body.data}",
+            "source": "${get_population_data.output.response.body.source}"
+        },
+        "schemaVersion": 2,
+        "restartable": true,
+        "workflowStatusListenerEnabled": false,
+        "ownerEmail": "[email protected]",
+        "timeoutPolicy": "ALERT_ONLY",
+        "timeoutSeconds": 0
+    }
+
+```
+
+Execute the workflow by using this command and capture the Workflow ID:
+
+```shell
+WORKFLOW_ID=$(curl -s -X POST 'http://localhost:8080/api/workflow/first_sample_workflow' \
+-H 'Content-Type: application/json' \
+-d '{}' | tr -d '"')
+```
+
+Check the Workflow IS, should return a string similar to this `46cbbaef-7133-451b-9334-2ccfc4e270c5`
+
+```shell
+echo "Workflow ID: $WORKFLOW_ID"
+```
+
+Check status of the Workflow, will return the data from https://restcountries.com/v3.1/name/united%20states?fields=name,population.
+
+```shell
+curl -s -X GET "http://localhost:8080/api/workflow/$WORKFLOW_ID" | jq
+```

docs-source/site/docs/platform/dbexporter.md

@@ -0,0 +1,21 @@
+---
+title: Oracle Database Metrics Exporter
+sidebar_position: 3
+---
+## Oracle Database Metrics Exporter
+
+This project provides observability for Oracle Database, helping users understand performance and diagnose issues across applications and the database. Over time, it will expand beyond metrics to include logging, tracing, and integrations with popular frameworks such as Spring Boot. It targets both cloud and on-premises deployments, including databases running in Kubernetes and containers
+
+[Full documentation](https://github.com/oracle/oracle-db-appdev-monitoring).
+
+### Installing Oracle Database Metrics Exporter
+
+Oracle Database Metrics Exporter will be installed if the `oracle-database-exporter.enabled` is set to `true` in the `values.yaml` file. The default namespace for Conductor is `oracle-database-exporter`.
+
+### Oracle Database Grafana Dashboard
+
+![Oracle Database Dashboard](images/exporter-running-against-basedb.png)
+
+### Transactional Event Queue Grafana Dashboard
+
+![Oracle Database Dashboard](images/txeventq-dashboard-v2.png)

docs-source/site/docs/platform/dboperator.md

@@ -0,0 +1,15 @@
+---
+title: Oracle Database Operator for Kubernetes
+sidebar_position: 4
+---
+## Oracle Database Operator for Kubernetes
+
+The Oracle Database Operator for Kubernetes (_OraOperator_, or simply the _operator_) extends the Kubernetes API with custom resources and controllers to automate Oracle Database lifecycle management.
+
+[Full Documentation](https://github.com/oracle/oracle-database-operator).
+
+Learn about using the OraOperator in the Livelab [Microservices and Kubernetes for an Oracle DBA](https://apexapps.oracle.com/pls/apex/dbpm/r/livelabs/view-workshop?wid=3734)
+
+### Installing the Oracle Database Operator for Kubernetes
+
+Oracle Database Operator for Kubernetes will be installed if the `oracle-database-operator.enabled` is set to `true` in the `values.yaml` file. The default namespace for Conductor is `oracle-database-exporter-system`.

docs-source/site/docs/platform/esooperator.md

@@ -0,0 +1,20 @@
+---
+title: External Secrets Operator
+sidebar_position: 5
+---
+## External Secrets Operator
+
+:::important
+The External Secrets Operator is a pre-requisite for Oracle Backend for Microservices and AI
+:::
+
+External Secrets Operator is a Kubernetes operator that integrates external secret management systems like OCI Vault, AWS Secrets Manager,
+HashiCorp Vault, Google Secrets Manager, Azure Key Vault and many more. The operator reads information from external APIs and automatically injects the values into a Kubernetes Secret.
+
+Full [documentation](https://external-secrets.io/latest/)
+
+![External Secrets Operator](images/diagrams-high-level-simple.png)
+
+### Installing External Secrets Operator
+
+External Secrets Operator will be installed if the `external-secrets.enabled` is set to `true` in the `values.yaml` file. The default namespace for External Secrets Operator is `external-secrets`.

docs-source/site/docs/platform/eureka.md

@@ -0,0 +1,72 @@
+---
+title: Spring Boot Eureka Server
+sidebar_position: 6
+---
+## Spring Boot Eureka Server
+
+Oracle Backend for Microservices and AI includes the Spring Boot Eureka service registry, which stores information about client services. Typically, each microservice registers with Eureka at startup. Eureka maintains a list of all active service instances, including their IP addresses and ports. Other services can look up this information using a well-known key, enabling service-to-service communication without hardcoding addresses at development or deployment time.
+
+### Installing Spring Boot Eureka Server
+
+Spring Boot Eureka Server will be installed if the `eureka.enabled` is set to `true` in the `values.yaml` file. The default namespace for Spring Boot Eureka Server is `eureka`.
+
+### Access Eureka Web User Interface
+
+To access the Eureka Web User Interface, use kubectl port-forward to create a secure channel to `service/eureka`. Run the following command to establish the secure tunnel (replace the example namespace `obaas-dev` with the namespace where the Spring Boot Eureka Server is deployed):
+
+```shell
+kubectl port-forward -n obaas-dev svc/eureka 8761
+```
+
+Open the [Eureka web user interface](http://localhost:8761)
+
+![Eureka Web User Interface](images/eureka-web.png)
+
+### Enable a Spring boot application for Eureka
+
+To Spring boot application you need to add the following dependency
+
+```xml
+<dependency>
+    <groupId>org.springframework.cloud</groupId>
+    <artifactId>spring-cloud-starter-netflix-eureka-client</artifactId>
+</dependency>
+```
+
+And to configure the application to register with Eureka add the following to the `application.yaml` file. The variables in this configuration are automatically injected to your deployment and pods you deploy applications to Oracle Backend for Microservices and AI using the OBaaS deployment Helm chart.
+
+```yaml
+eureka:
+  instance:
+    hostname: ${spring.application.name}
+    preferIpAddress: true
+  client:
+    service-url:
+      defaultZone: ${eureka.service-url}
+    fetch-registry: true
+    register-with-eureka: true
+    enabled: true
+```
+
+### Enable a Helidon application for Eureka
+
+To Spring boot application you need to add the following dependency
+
+```xml
+<dependency>
+    <groupId>io.helidon.integrations.eureka</groupId>
+    <artifactId>helidon-integrations-eureka</artifactId>
+    <scope>runtime</scope>
+</dependency>
+```
+
+And to configure the application to register with Eureka add the following to the `aaplication.yaml` file:
+
+```properties
+server.features.eureka.enabled=true
+server.features.eureka.instance.name=${eureka.instance.hostname}
+server.features.eureka.client.base-uri=${eureka.client.service-url.defaultZone}
+server.features.eureka.client.register-with-eureka=true
+server.features.eureka.client.fetch-registry=true
+server.features.eureka.instance.preferIpAddress=true
+```