Elana's feedback

README.md

@@ -1,5 +1,5 @@
 
-# Lightrun Helm Chart 
+# Lightrun Helm Chart
 The `lightrun` Helm chart provides a reliable and efficient way to deploy and manage Lightrun on Kubernetes. It includes all the essential components for a smooth setup and can scale seamlessly to support large deployments.
 ## Architecture Overview
 ### Diagram
@@ -14,15 +14,15 @@ The `lightrun` Helm chart provides a reliable and efficient way to deploy and ma
 | [**Keycloak**](docs/components/keycloak.md)         | Manages authentication.                                                                                        |
 | [**Redis**](docs/components/redis.md)               | Handles caching and pub/sub channels (can be local or external).                                               |
 | [**MySQL**](docs/components/database.md)            | Stores application data (can be local or external).                                                            |
-| [**RabbitMQ**](docs/components/rabbitmq.md)         | **Optional** Manages the event message queue, primarily for sending telemetry to Lightrun (local or external). |
-| [**Datastreamer**](docs/components/datastreamer.md) | **Optional** Sends audit logs to various SIEM systems.                                                         |
+| [**RabbitMQ**](docs/components/rabbitmq.md)         | [**Optional**] Manages the event message queue, primarily for sending telemetry to Lightrun (local or external). |
+| [**Datastreamer**](docs/components/datastreamer.md) | [**Optional**] Sends audit logs to various SIEM systems.                                                         |
 
-## Getting started
+## Getting Started
 ### **Quick Start Installation**
 
 If you just want to get Lightrun up and running with default settings, start with our [Quick Start Guide](docs/installation/quickstart.md). This guide covers all the essential steps for a basic installation.
 
-For a **production-ready deployment**, refer to the [**Step-by-Step Planning for Production**](#step-by-step-planning-for-production) section to ensure security, scalability, and best practices.
+For a **production-ready deployment**, refer to the [Step-by-Step Planning for Production](#step-by-step-planning-for-production) section to ensure security, scalability, and best practices.
 
 ---
 ### **Step-by-Step Planning for Production**
@@ -31,62 +31,62 @@ To ensure a smooth and secure production deployment of Lightrun, follow these ke
 #### **1. Capacity Planning**
 
 - Assess expected resource usage (CPU, memory, storage) and plan for scalability.
-    [More info on Capacity Planning](docs/installation/capacity_planning.md)
+    For more information, see [Capacity Planning](docs/installation/capacity_planning.md).
 #### **2. Compatibility**
 
 - Review the Compatibility matrix for the supported tools.
-    [More info on Compatibility](docs/installation/compatibility_matrix.md)
-#### **2. Secrets**
+    For more information, see [Compatibility](docs/installation/compatibility_matrix.md).
+#### **3. Secrets**
 
 - Decide whether to use Helm-managed secrets or an external secrets manager.
-    [More info on Secrets Management](docs/installation/secrets.md)
-#### **3. Lightrun Certificate**
+    For more information, see [Secrets Management](docs/installation/secrets.md).
+#### **4. Lightrun Certificate**
 
 - Plan how Lightrun certificate will be issued and managed for secure communications.
-    [More info on Certificate](docs/installation/certificate.md)
-#### **4. Database**
+    For more information, see [Certificate](docs/installation/certificate.md).
+#### **5. Database**
 
 > [!TIP]
 > Use external database
 
-- Choose between a local or external database.
-    [More info on Database Setup](docs/components/database.md)
+- Choose a local or an external database.
+    For more information, see [Database Setup](docs/components/database.md).
 
-#### **5. Router**
+#### **6. Router**
 
 - Decide how external traffic will reach the Lightrun router (Ingress, Service, OpenShift Route).
-    [More info on Router](docs/components/router/index.md)
+    For more information, see [Router](docs/components/router/index.md).
 
-#### **6. Container Images Registry**
+#### **7. Container Images Registry**
 
 - Choose where to store and manage container images (e.g., private registry, Docker Hub, Azure Container Registry, AWS ECR).
-    [More info on Container Image Registry](docs/installation/container_image_registry.md)
+    For more information, see [Container Image Registry](docs/installation/container_image_registry.md).
 
-#### **7. Redis**
+#### **8. Redis**
 > [!TIP] 
 > Use external redis
 - Determine if Redis will be local or external.
-    [More info on Redis Setup](docs/components/redis.md)
+    For more information, see [Redis Setup](docs/components/redis.md).
 
-#### **8. (Optional)RabbitMQ**
+#### **9. [Optional] RabbitMQ**
 
 - Determine if RabbitMQ is needed for sending telemetry to Lightrun.
-    [More info on RabbitMQ](docs/components/rabbitmq.md)
+    For more information, see [RabbitMQ](docs/components/rabbitmq.md).
 
-#### **9. (Optional)Network Policy**
+#### **10. [Optional] Network Policy**
 
 - Establish network policies to restrict access between services and prevent unauthorized communication.
-    [More info on Network Policy](docs/advanced/network_policy.md)
+    For more information, see [Network Policy](docs/advanced/network_policy.md).
 
-#### **10. (Optional)Internal TLS Communication**
+#### **11. [Optional} Internal TLS Communication**
 
 - Decide whether internal TLS is necessary for secure component communication.
-    [More info on Internal TLS](docs/advanced/internal_tls.md)
+    For more information, see [Internal TLS](docs/advanced/internal_tls.md).
 
-#### **11. Choose Your Deployment Option**
+#### **12. Choose Your Deployment Option**
 
 Decide where to run your Kubernetes cluster based on your infrastructure needs. Consider whether you’ll deploy all services locally (including RabbitMQ, Redis, and MySQL) or use managed cloud services.
-##### **Supported Kubernetes Platforms:**
+##### **Supported Kubernetes Platforms**
 
 Select your preferred cloud provider for deployment:
 
@@ -100,6 +100,6 @@ Review the [Known Limitations](docs/limitations.md) before deployment.
 
 ## Release Notes
 
-Check the [versions mapping documentation](docs/installation/versions_mapping.md) for version compatibility.  
-Check the [release strategy](docs/release_strategy.md) for the meaning of major minor patch.
-See the [changelog](CHANGELOG.md) for a detailed history of changes and improvements in each release.
+- Check the [versions mapping documentation](docs/installation/versions_mapping.md) for version compatibility.  
+- Check the [release strategy](docs/release_strategy.md) for the meaning of major, minor, and patch versions.
+- See the [changelog](CHANGELOG.md) for a detailed history of changes and improvements in each release.

docs/advanced/internal_tls.md

@@ -1,11 +1,11 @@
-### Overview
+# Internal TLS
 
 By default, internal communication between pods within the cluster is not encrypted, as SSL operations can be computationally expensive. Typically, SSL termination occurs at the client-facing load balancer. However, certain security policies may require SSL encryption for all internal communications. While service mesh proxies often handle this requirement, there are cases where encryption must be enforced at the pod level.
 
 > [!WARNING]
 > Enabling internal TLS increases resource consumption, as additional computational power is required for SSL operations.
 
-### Enabling Internal TLS
+### Enable Internal TLS
 
 To activate internal TLS, set the `enabled` flag to `true`:
 
@@ -15,7 +15,7 @@ general:
     enabled: true
 ```
 
-### Providing TLS Certificates
+### Provide TLS Certificates
 
 There are two ways to supply certificates to pods:
 
@@ -47,7 +47,7 @@ This prevents secrets from being recreated during `helm upgrade` operations.
 
 If you prefer to use externally generated certificates, specify the Kubernetes secret names containing them. Each secret must include the `tls.crt` and `tls.key` keys.
 
-example of a secret:
+Example of a secret:
 
 ```yaml
 apiVersion: v1

docs/advanced/network_policy.md

@@ -1,4 +1,6 @@
-The **network policy** controls how pods communicate with each other and external networks. It defines ingress (incoming) and egress (outgoing) rules to regulate traffic based on namespaces, pods, IP addresses, and ports
+# Network Policy
+
+The **network policy** controls how pods communicate with each other and external networks. It defines ingress (incoming) and egress (outgoing) rules to regulate traffic based on namespaces, pods, IP addresses, and ports.
 
 ## Enabling Network Policies
 
@@ -21,14 +23,14 @@ general:
 | Defined `networkPolicy.egress` rules                 | The service can **only access allowed destinations**. |
 ## Ingress Rules (Incoming Traffic)
 Defines which external sources can access the pods.
-- **`networkPolicy.ingress.enabled: false`** → No restrictions (all traffic allowed).
-- **`networkPolicy.ingress.enabled: true` but no rules defined** → **All incoming traffic is denied.**
+- **`networkPolicy.ingress.enabled: false`**: No restrictions (all traffic allowed).
+- **`networkPolicy.ingress.enabled: true` but no rules defined**: **All incoming traffic is denied.**
 - To allow traffic, define one or more of:
-    - **`namespacesSelector`** → Allow traffic from specific namespaces.
-    - **`ipBlock`** → Allow traffic from specific IP ranges.
-    - **`podSelector`** → Allow traffic from specific pods in the same namespace.
-    - **`namespacePodSelector`** → Allow traffic from specific pods in specific namespaces.
-    - **`ports`** → Allow traffic only on specific protocols and ports.
+    - **`namespacesSelector`**: Allow traffic from specific namespaces.
+    - **`ipBlock`**: Allow traffic from specific IP ranges.
+    - **`podSelector`**: Allow traffic from specific pods in the same namespace.
+    - **`namespacePodSelector`**: Allow traffic from specific pods in specific namespaces.
+    - **`ports`**: Allow traffic only on specific protocols and ports.
 ```yaml
 general:
   networkPolicy:
@@ -53,14 +55,14 @@ general:
 ## Egress Rules (Outgoing Traffic)
 Defines where pods can send outbound traffic.
 
-- **`networkPolicy.egress.enabled: false`** → No restrictions (all traffic allowed).
-- **`networkPolicy.egress.enabled: true` but no rules defined** → **All outgoing traffic is denied.**
+- **`networkPolicy.egress.enabled: false`**: No restrictions (all traffic allowed).
+- **`networkPolicy.egress.enabled: true` but no rules defined**: **All outgoing traffic is denied.**
 - To allow traffic, define one or more of:
-    - **`namespacesSelector`** → Allow traffic to specific namespaces.
-    - **`ipBlock`** → Allow traffic to specific IP ranges.
-    - **`podSelector`** → Allow traffic to specific pods in the same namespace.
-    - **`namespacePodSelector`** → Allow traffic to specific pods in specific namespaces.
-    - **`ports`** → Allow traffic only on specific protocols and ports.
+    - **`namespacesSelector`**: Allow traffic to specific namespaces.
+    - **`ipBlock`**: Allow traffic to specific IP ranges.
+    - **`podSelector`**: Allow traffic to specific pods in the same namespace.
+    - **`namespacePodSelector`**: Allow traffic to specific pods in specific namespaces.
+    - **`ports`**: Allow traffic only on specific protocols and ports.
 ```yaml
 general:
   networkPolicy:
@@ -77,4 +79,4 @@ general:
       ports:
       - protocol: TCP
         port: 443  # Allow HTTPS traffic
-```
+```

docs/components/backend.md

@@ -1,4 +1,4 @@
-### Overview
+# Backend Service
 
 The backend component is responsible for handling core application logic and interactions with the database, message queues, and other services. This document outlines the configurable parameters available for backend deployment.
 configuration is defined under **`deployments.backend`** in the **`values.yaml`**
@@ -152,4 +152,4 @@ extraEnvs: []
     successThreshold: 1
     failureThreshold: 3
     path: /management/health/readiness
-```
+```

docs/components/database.md

@@ -1,10 +1,10 @@
-This section configures **MySQL** as the database. You can either:  
--  Deploy a [**Local MySQL (`general.db_local true`)**](#local-mysql-generaldb_local-true).
-or  
+# MySQL
+This page describes how to configure **MySQL** as the database. The following methods are supported:  
+-  Deploy a [**Local MySQL (`general.db_local true`)**](#local-mysql-generaldb_local-true).  
 - Connect to an [**External MySQL (`general.db_local false`)**](#external-mysql-generaldb_local-false).
 
 > [!Note] 
-> **To enable SSL for both local and external MySQL instances, set `general.db_require_secure_transport: true`, which enforces secure connections by passing `require_secure_transport=ON` to the MySQL pod (db_local=true) and configuring backend services, including Keycloak, to use SSL when connecting to the database.**
+> **To enable SSL for both local and external MySQL instances, set `general.db_require_secure_transport: true`, which enforces secure connections by passing `require_secure_transport=ON` to the MySQL pod (`db_local=true`) and configuring backend services, including Keycloak, to use SSL when connecting to the database.**
 ## **External MySQL (`general.db_local: false`)**
 In this mode, MySQL is **not deployed inside the cluster**.  
 Instead, the application connects to an **existing MySQL database**.
@@ -33,7 +33,7 @@ CREATE DATABASE lightrunserver;
 
 ---
 
-### **[REQUIRED] External Database Requirements**
+### **[MANDATORY] External Database Requirements**
 
 - **MySQL Version**: `>= 8.0.37`
 - **Database Size**: CPU, Memory, and Disk must meet [**capacity table requirements**](../installation/capacity_planning.md).
@@ -44,11 +44,11 @@ CREATE DATABASE lightrunserver;
 
 While **not required**, the following HA settings are **recommended** for production:
 
-**Multi-AZ Deployment** for redundancy  
-**Master-Slave Replication** (not cluster mode)  
-**No Cluster Mode** (Avoid Galera, InnoDB Cluster, etc.)
+- **Multi-AZ Deployment** for redundancy  
+- **Source-Replica Replication** (not cluster mode)  
+- **No Cluster Mode** (Avoid Galera, InnoDB Cluster, etc.)
 
-### **Helm chart configuration**
+### **Helm Chart Configuration**
 ```yaml
 general:
   db_local: false
@@ -64,8 +64,8 @@ general:
 
 ## **Local MySQL (`general.db_local: true`)**
 In this mode, MySQL is deployed **inside the cluster** using either:  
-A **StatefulSet** with persistent storage (**Recommended**)  
-A **Deployment** with ephemeral storage (for testing purposes)
+- A **StatefulSet** with persistent storage (**Recommended**)  
+- A **Deployment** with ephemeral storage (for testing purposes)
 ### **Basic Configuration**
 ```yaml
 general:
@@ -122,8 +122,8 @@ deployments:
 | **`deployments.emptyDir.mysql.sizeLimit: 5Gi`** | Limits ephemeral storage to 5Gi.                 |
 
 ### **Pod Configuration**
-Below is the **default MySQL pod configuration**.
-configuration is defined under **`deployments.mysql`** in the **`values.yaml`**
+This is the **default MySQL pod configuration**.
+Configuration is defined under **`deployments.mysql`** in the **`values.yaml`** file.
 ```yaml
 deployments:
   mysql:
@@ -197,4 +197,4 @@ general:
   db_local: false
   db_endpoint: "mysql.external.example.com"
   db_database: lightrunserver
-```
+```

docs/components/datastreamer.md

@@ -1,4 +1,4 @@
-### Overview
+# Data Streamer
 The **Data Streamer** is an optional component that enables integration with **SIEM (Security Information and Event Management)** systems by forwarding audit logs. Configuration is split into two sections:
 
 - **`general.data_streamer`**: Controls global settings such as enabling the component and retry policies.
@@ -94,4 +94,4 @@ readinessProbe:
   successThreshold: 1
   failureThreshold: 3
   path: /ready
-```
+```

docs/components/frontend.md

@@ -1,4 +1,4 @@
-### Overview
+# Frontend Service
 
 The frontend service provides the user interface and interacts with backend services. It is deployed as a Kubernetes pod and can be configured for scaling, resource allocation, and health monitoring.
 configuration is defined under **`deployments.frontend`** in the **`values.yaml`**
@@ -94,4 +94,4 @@ readinessProbe:
   timeoutSeconds: 5
   successThreshold: 1
   failureThreshold: 3
-```
+```

docs/components/keycloak.md

@@ -1,7 +1,7 @@
-### Overview
+# Keycloak Service
 
-The keycloak service provides the authentication. It is deployed as a Kubernetes pod and can be configured for scaling, resource allocation, and health monitoring.
-configuration is defined under **`deployments.keycloak`** in the **`values.yaml`**
+The Keycloak service provides authentication. It is deployed as a Kubernetes pod and can be configured for scaling, resource allocation, and health monitoring.
+Configuration is defined under **`deployments.keycloak`** in the **`values.yaml`** file.
 ### Configuration Options
 
 #### General Settings
@@ -11,11 +11,11 @@ configuration is defined under **`deployments.keycloak`** in the **`values.yaml`
   clusterMode: true 
 ```
 
-#### Horizontal Pod Autoscaling (HPA) And Replicas
+#### Horizontal Pod Autoscaling (HPA) and Replicas
 
 ```yaml
   hpa:
-    enabled: false          # Enables or disables HPA
+    enabled: false         # Enables or disables HPA
     cpu: 70                # Target CPU utilization percentage
     maxReplicas: 5         # Maximum number of replicas
   replicas: 1              # Default number of replicas
@@ -87,7 +87,7 @@ initContainers:
       tag: latest
       pullPolicy: ""
 ```
-> **Note:** The `cluster_cert` init container is used only with internal_tls and keycloak cluster mode.
+> **Note:** The `cluster_cert` init container is used only with `internal_tls` and keycloak cluster mode.
 
 #### Pod Disruption Budget & Scheduling
 
@@ -118,4 +118,4 @@ readinessProbe:
   timeoutSeconds: 5
   successThreshold: 1
   failureThreshold: 3
-```
+```