GITBOOK-21: Refactoring, reordering

Haarolean · gitbook-bot · commit c8e51c86a17f · 2025-05-13T17:49:41.000Z
diff --git a/SUMMARY.md b/SUMMARY.md
@@ -29,7 +29,7 @@
     * [MSK (+Serverless) Setup](quick-start/prerequisites/permissions/msk-+serverless-setup.md)
 * [Demo run](quick-start/demo-run.md)
 * [AWS Marketplace](quick-start/via-aws-marketplace.md)
-* [Persistent start](quick-start/persistent-start.md)
+* [Persisting config](quick-start/persistent-start.md)
 * [K8s / Helm](quick-start/k8s-helm.md)
 
 ## 🛠️ Configuration
@@ -46,14 +46,16 @@
 * [Misc configuration properties](configuration/misc-configuration-properties.md)
 * [Complex configuration examples](configuration/configuration/complex-configuration-examples/README.md)
   * [Kraft mode + multiple brokers](configuration/configuration/complex-configuration-examples/kraft-mode-+-multiple-brokers.md)
-* [Kafka w/ SSL](configuration/ssl.md)
+* [Kafka secured with SSL](configuration/ssl.md)
 * [Authentication](configuration/authentication/README.md)
-  * [Basic Authentication](configuration/authentication/basic-authentication.md)
-  * [OAuth2](configuration/authentication/oauth2.md)
-  * [AWS IAM](configuration/authentication/aws-iam.md)
-  * [LDAP / Active Directory](configuration/authentication/ldap-active-directory.md)
-  * [SSO Guide](configuration/authentication/sso-guide.md)
-  * [SASL\_SCRAM](configuration/authentication/sasl_scram.md)
+  * [For the UI](configuration/authentication/for-the-ui/README.md)
+    * [Basic Authentication](configuration/authentication/for-the-ui/basic-authentication.md)
+    * [OAuth2](configuration/authentication/for-the-ui/oauth2.md)
+    * [LDAP / Active Directory](configuration/authentication/for-the-ui/ldap-active-directory.md)
+    * [SSO Guide (Deprecated)](configuration/authentication/for-the-ui/sso-guide.md)
+  * [For Kafka](configuration/authentication/for-kafka/README.md)
+    * [AWS IAM](configuration/authentication/for-kafka/aws-iam.md)
+    * [SASL\_SCRAM](configuration/authentication/for-kafka/sasl_scram.md)
 * [RBAC (Role based access control)](configuration/rbac-role-based-access-control/README.md)
   * [Supported Identity Providers](configuration/rbac-role-based-access-control/supported-identity-providers.md)
 * [Data masking](configuration/data-masking.md)
@@ -65,4 +67,4 @@
 
 * [Common problems](faq/common-problems.md)
 * [FAQ](faq/faq.md)
-* [Authentication](faq/authentication.md)
+* [Authentication Issues](faq/authentication.md)
diff --git a/configuration/audit-log.md b/configuration/audit-log.md
@@ -22,9 +22,9 @@ kafka:
 
 ### Note
 
-If you create the Audit Topic manually, it  **should not** be compacted, as the audit documents do not have a key, which is required for Kafka topic compaction.
+If you create the audit topic manually, it **should not** be compacted, as the audit documents do not have a key, which is required for Kafka topic compaction.
 
 Other than **compaction**, the Kafka UI does not expect specific requirements for additional topic properties. However, as always, consider configuring the following:
 
-- **Retention period** How long the data should be stored in Kafka.  
-- **Number of partitions** This affects parallelism and how the data will be consumed.
+* **Retention period** How long the data should be stored in Kafka.
+* **Number of partitions** This affects parallelism and how the data will be consumed.
diff --git a/configuration/authentication/for-kafka/README.md b/configuration/authentication/for-kafka/README.md
@@ -0,0 +1,6 @@
+---
+description: List of authentication methods to kafka itself
+---
+
+# For Kafka
+
diff --git a/configuration/authentication/for-kafka/aws-iam.md b/configuration/authentication/for-kafka/aws-iam.md
@@ -10,7 +10,7 @@ You could pass SASL configs in the properties section for each cluster.
 
 More details could be found here: [aws-msk-iam-auth](https://github.com/aws/aws-msk-iam-auth)
 
-More about permissions: [msk-+serverless-setup.md](../../quick-start/prerequisites/permissions/msk-+serverless-setup.md "mention")
+More about permissions: [msk-+serverless-setup.md](../../../quick-start/prerequisites/permissions/msk-+serverless-setup.md "mention")
 
 ### Examples:
 
diff --git a/configuration/authentication/for-kafka/sasl_scram.md b/configuration/authentication/for-kafka/sasl_scram.md
diff --git a/configuration/authentication/for-the-ui/README.md b/configuration/authentication/for-the-ui/README.md
@@ -0,0 +1,6 @@
+---
+description: Authentication methods for authenticating your users into the UI itself
+---
+
+# For the UI
+
diff --git a/configuration/authentication/for-the-ui/basic-authentication.md b/configuration/authentication/for-the-ui/basic-authentication.md
@@ -4,7 +4,9 @@ description: Basic username+password authentication
 
 # Basic Authentication
 
-In order to enable basic username+passworda authentication add these properties:
+Basic authentication supports only one local user. If you need multiple, running a Keycloak instance is the easiest way.
+
+To enable basic username+password authentication, add these properties:
 
 ```properties
       AUTH_TYPE: "LOGIN_FORM"
@@ -25,4 +27,4 @@ spring:
       password: pass
 ```
 
-Please note that basic auth is not compatible with neither any other auth method nor RBAC.
+Please note that basic auth is incompatible with any other auth method or RBAC.
diff --git a/configuration/authentication/for-the-ui/ldap-active-directory.md b/configuration/authentication/for-the-ui/ldap-active-directory.md
@@ -12,9 +12,14 @@ spring:
     user-filter-search-base: "dc=planetexpress,dc=com"
     user-filter-search-filter: "(&(uid={0})(objectClass=inetOrgPerson))"
     group-filter-search-base: "ou=people,dc=planetexpress,dc=com" # required for RBAC
+```
+
+If you're running AD rather than LDAP, also add these:
+
+```
 oauth2:
   ldap:
-    activeDirectory: false
+    activeDirectory: true
     aсtiveDirectory:
       domain: memelord.lol
 ```
diff --git a/configuration/authentication/for-the-ui/oauth2.md b/configuration/authentication/for-the-ui/oauth2.md
diff --git a/configuration/authentication/for-the-ui/sso-guide.md b/configuration/authentication/for-the-ui/sso-guide.md
@@ -1,4 +1,8 @@
-# SSO Guide
+---
+description: Deprecated. See OAuth2 guides
+---
+
+# SSO Guide (Deprecated)
 
 ## How to configure SSO
 
diff --git a/configuration/rbac-role-based-access-control/supported-identity-providers.md b/configuration/rbac-role-based-access-control/supported-identity-providers.md
@@ -8,7 +8,7 @@ description: The list of supported auth providers for RBAC
 
 Any OAuth provider not on the list of all providers below this one.
 
-Set up the auth itself first, docs [here](../authentication/oauth2.md) and [here](../authentication/sso-guide.md). **Don't forget "custom-params.type: oauth".**
+Set up the auth itself first, docs [here](../authentication/for-the-ui/oauth2.md) and [here](../authentication/for-the-ui/sso-guide.md). **Don't forget "custom-params.type: oauth".**
 
 ```yaml
       subjects:
@@ -22,7 +22,7 @@ Set up the auth itself first, docs [here](../authentication/oauth2.md) and [here
 
 ### Google
 
-Set up google auth [first](../authentication/oauth2.md#google)
+Set up google auth [first](../authentication/for-the-ui/oauth2.md#google)
 
 ```yaml
         - provider: oauth_google
@@ -35,7 +35,7 @@ Set up google auth [first](../authentication/oauth2.md#google)
 
 ### Github
 
-Set up github auth [first](../authentication/oauth2.md#github)
+Set up github auth [first](../authentication/for-the-ui/oauth2.md#github)
 
 ```yaml
         - provider: oauth_github
@@ -51,7 +51,7 @@ Set up github auth [first](../authentication/oauth2.md#github)
 
 ### Cognito
 
-Set up cognito auth [first](../authentication/oauth2.md#cognito)
+Set up cognito auth [first](../authentication/for-the-ui/oauth2.md#cognito)
 
 ```yaml
         - provider: oauth_cognito
@@ -64,7 +64,7 @@ Set up cognito auth [first](../authentication/oauth2.md#cognito)
 
 ### LDAP
 
-Set up LDAP auth [first](../authentication/ldap-active-directory.md)
+Set up LDAP auth [first](../authentication/for-the-ui/ldap-active-directory.md)
 
 ```yaml
         - provider: ldap
@@ -90,7 +90,7 @@ Set up LDAP auth [first](../authentication/ldap-active-directory.md)
 
 You can map Okta Groups to roles. First, confirm that your okta administrator has included the `group` claim or the groups will not be passed in the auth token.
 
-Ensure `roles-field` in the auth config is set to `groups` and that `groups` is included in the `scope`, see [here](../authentication/oauth2.md#okta) for more details.
+Ensure `roles-field` in the auth config is set to `groups` and that `groups` is included in the `scope`, see [here](../authentication/for-the-ui/oauth2.md#okta) for more details.
 
 Configure the role mapping to the okta group via generic provider mentioned above:
 
@@ -105,7 +105,7 @@ Configure the role mapping to the okta group via generic provider mentioned abov
 
 You can map GoAuthentic Groups to roles. First, confirm that your GoAuthentic administrator has included the `profile` claim or the groups will not be passed in the auth token.
 
-Ensure `roles-field` in the auth config is set to `groups` and that `profile` is included in the `scope`, as groups are passed by default in the profile scope. See [here](../authentication/oauth2.md#goauthentic) for more details.
+Ensure `roles-field` in the auth config is set to `groups` and that `profile` is included in the `scope`, as groups are passed by default in the profile scope. See [here](../authentication/for-the-ui/oauth2.md#goauthentic) for more details.
 
 Configure the role mapping to the GoAuthentic group via generic provider mentioned above:
 
diff --git a/configuration/serialization-serde.md b/configuration/serialization-serde.md
@@ -16,7 +16,7 @@ Base64 (RFC4648) binary data representation. Can be useful in case if the actual
 
 #### Hex
 
-[Hexadecimal](https://en.wikipedia.org/wiki/Hexadecimal) binary data representation. Bytes delimiter and case can be configured.&#x20;
+[Hexadecimal](https://en.wikipedia.org/wiki/Hexadecimal) binary data representation. Bytes delimiter and case can be configured.
 
 Class name: `io.kafbat.ui.serdes.builtin.HexSerde`
 
@@ -35,7 +35,7 @@ kafka:
 
 #### String
 
-Treats binary data as a string in specified encoding. Default encoding is UTF-8.
+Treats binary data as a string in the specified encoding. Default encoding is UTF-8.
 
 Class name: `io.kafbat.ui.serdes.builtin.StringSerde`
 
@@ -109,7 +109,7 @@ Deserialize-only serde. Decodes protobuf payload without a predefined schema (li
 
 #### SchemaRegistry
 
-SchemaRegistry serde is automatically configured if schema registry properties set on cluster level. But you can add new SchemaRegistry-typed serdes that will connect to another schema-registry instance.
+SchemaRegistry serde is automatically configured if schema registry properties are set on the cluster level. But you can add new SchemaRegistry-typed serdes that will connect to another schema-registry instance.
 
 Class name: `io.kafbat.ui.serdes.builtin.sr.SchemaRegistrySerde`
 
@@ -137,11 +137,9 @@ kafka:
             url:  http://another-yet-schema-registry:8081
 ```
 
-
-
 ### Setting serdes for specific topics
 
-You can specify preferable serde for topics key/value. This serde will be chosen by default in UI on topic's view/produce pages. To do so, set `topicValuesPattern/topicValuesPattern` properties for the selected serde. Kafka-ui will choose a first serde that matches specified pattern.
+You can specify a preferred serde for the topics key/value. This serde will be chosen by default in UI on topic's view/produce pages. To do so, set `topicValuesPattern/topicValuesPattern` properties for the selected serde. Kafka-ui will choose the first serde that matches the specified pattern.
 
 Sample configuration:
 
@@ -162,7 +160,7 @@ kafka:
 
 ### Default serdes
 
-You can specify which serde will be chosen in UI by default if no other serdes selected via `topicKeysPattern/topicValuesPattern` settings.
+You can specify which serde will be chosen in UI by default if no other serdes are selected via `topicKeysPattern/topicValuesPattern` settings.
 
 Sample configuration:
 
@@ -183,11 +181,11 @@ If selected serde couldn't be applied (exception was thrown), then fallback (Str
 
 ### Custom pluggable serde registration
 
-You can implement your own serde and register it in kafbat-ui application. To do so:
+You can implement your serde and register it in the UI. To do so:
 
 1. Add `serde-api` dependency, [link to maven central](https://central.sonatype.com/artifact/io.kafbat.ui/serde-api)
 2. Implement `io.kafbat.ui.serde.api.Serde` interface. See javadoc for implementation requirements.
-3. Pack your serde into uber jar, or provide directory with no-dependency jar and it's dependencies jars
+3. Pack your serde into an uber jar, or provide a directory with no-dependency jar and its dependencies jars
 
 Example pluggable serdes : [kafka-smile-serde](https://github.com/kafbat/ui-serde-smile), [kafka-glue-sr-serde](https://github.com/kafbat/ui-serde-glue)
 
diff --git a/development/building/prerequisites.md b/development/building/prerequisites.md
@@ -8,7 +8,7 @@ This page explains how to get the software you need to use on Linux or macOS for
 * `git` installed
 * `docker` installed
 
-> Note: For contribution, you must have a `github` account.
+> Note: For contributing, you must have a github account to be able to raise PRs.
 
 #### For Linux
 
@@ -27,12 +27,13 @@ OpenJDK Runtime Environment (build 21.0.5+8-Ubuntu-2ubuntu120.04)
 OpenJDK 64-Bit Server VM (build 21.0.5+8-Ubuntu-2ubuntu120.04, mixed mode, sharing)
 ```
 
-Note: In case OpenJDK 21 is not set as your default Java, run 
-```bash 
+Note: In case OpenJDK 21 is not set as your default Java, run
+
+```bash
 sudo update-alternatives --config java
 ```
 
-command to list all installed Java versions.
+to list all installed Java versions.
 
 ```
 Selection    Path                                            Priority   Status
@@ -46,7 +47,7 @@ Selection    Path                                            Priority   Status
 Press <enter> to keep the current choice[*], or type selection number:
 ```
 
-you can set it as the default by entering the selection number for it in the list and pressing Enter. For example, to set Java 21 as the default, you would enter "4" and press **Enter**.
+You can set it as the default by entering the selection number for it in the list and pressing Enter. For example, to set Java 21 as the default, you would enter "4" and press **Enter**.
 
 2. Install `git`:
 
@@ -101,7 +102,7 @@ export PATH="$(/usr/libexec/java_home -v 21)/bin:$PATH"
 export JAVA_HOME="$(/usr/libexec/java_home -v 21)"
 ```
 
-If java_home doesn't recognize homebrew installed java you can run below cmd to symlink brew installed java path to jvm
+If java\_home doesn't recognize homebrew installed java you can run below cmd to symlink brew installed java path to jvm
 
 ```bash
 sudo ln -sfn $(brew --prefix openjdk@21)/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk-21.jdk
diff --git a/faq/faq.md b/faq/faq.md
@@ -2,15 +2,15 @@
 
 ### Basic (username password) authentication
 
-[basic-authentication.md](../configuration/authentication/basic-authentication.md "mention")
+[basic-authentication.md](../configuration/authentication/for-the-ui/basic-authentication.md "mention")
 
 ### Role-based access control
 
 [rbac-role-based-access-control](../configuration/rbac-role-based-access-control/ "mention")
 
 ### OAuth 2
 
-[oauth2.md](../configuration/authentication/oauth2.md "mention")
+[oauth2.md](../configuration/authentication/for-the-ui/oauth2.md "mention")
 
 ### LDAP
 
diff --git a/overview/features.md b/overview/features.md
@@ -6,13 +6,11 @@
 * **Metrics Dashboard** – Track key Kafka metrics in real time with a streamlined, lightweight dashboard.
 * **Kafka Brokers Overview** – Inspect brokers, including partition assignments and controller status.
 * **Consumer Group Details** – Analyze parked offsets per partition, and monitor both combined and partition-specific lag.
-* **Message Browser** – Explore messages in JSON, plain text, or Avro encoding formats.
+* **Message Browser** – Explore messages in JSON, plain text, or Avro encoding formats. Live view is supported, enriched with user-defined CEL message filters.
 * **Dynamic Topic Management** – Create and configure new topics with flexible, real-time settings.
 * **Pluggable Authentication** – Secure your UI using OAuth 2.0 (GitHub, GitLab, Google), LDAP, or basic authentication.
 * **Cloud IAM Support** – Integrate with **GCP IAM**, **Azure IAM**, and **AWS IAM** for cloud-native identity and access management.
 * **Managed Kafka Service Support** – Full support for **Azure EventHub**, **Google Cloud Managed Service for Apache Kafka**, and **AWS Managed Streaming for Apache Kafka (MSK)**—both server-based and serverless.
 * **Custom SerDe Plugin Support** – Use built-in serializers/deserializers like AWS Glue and Smile, or create your own custom plugins.
 * **Role-Based Access Control** – [Manage granular UI permissions](../configuration/rbac-role-based-access-control/) with RBAC.
 * **Data Masking** – [Obfuscate sensitive data](../configuration/data-masking.md) in topic messages to enhance privacy and compliance.
-
-
diff --git a/overview/getting-started.md b/overview/getting-started.md
@@ -1,16 +1,16 @@
 # Getting started
 
-To run Kafbat UI, you can use either a pre-built Docker image or build it (or a jar file) yourself.
+To run Kafbat UI, you can use either a pre-built Docker image or build the app yourself.
 
 ### Quick start (Demo run)
 
 ```bash
 docker run -it -p 8080:8080 -e DYNAMIC_CONFIG_ENABLED=true ghcr.io/kafbat/kafka-ui
 ```
 
-Then access the web UI at [http://localhost:8080](http://localhost:8080)
+Then, access the web UI at [http://localhost:8080](http://localhost:8080)
 
-The command is sufficient to try things out. When you're done trying things out, you can proceed with a [persistent installation](getting-started.md#persistent-installation)
+The command is sufficient to try things out. When you're done trying these things out, you can proceed with a [persistent installation](getting-started.md#persistent-installation)
 
 ### Persistent installation
 
diff --git a/quick-start/persistent-start.md b/quick-start/persistent-start.md
@@ -1,8 +1,8 @@
-# Persistent start
+# Persisting config
 
-Please ensure the target volume (`~/kui/config.yml`) of your config file does exist.
+Please ensure the target volume (`~/kui/config.yml`) of your config file does exist. If it doesn't, docker will create it as a directory instead of a file, and everything will explode.
 
-Create a yml file with the following contents:
+Create a YAML file with the following contents:
 
 ```yaml
 services:

-Original file line number
+Diff line change
@@ @@ -0,0 +1,6 @@ @@
 +---
 +description: List of authentication methods to kafka itself
 +---
++
 +# For Kafka
++