Merge pull request #1200 from adorsys/feat/remote-state-management

Add a documentation for remote-state-management.

docs/config/remote-state-management.md

@@ -1,27 +1,8 @@
-# Table of Contents
-
-- [Overview](#overview)
-- [Environment Setup](#environment-setup)
-- [Creating the Keycloak Configuration Import Script](#creating-the-keycloak-configuration-import-script)
-- [JSON Configuration File: State Management Example](#json-configuration-file-state-management-example)
-- [Verifying Remote State Management](#verifying-remote-state-management)
-- [Conclusion](#conclusion)
-
-## Overview
-
-### What is Keycloak?
-
-Keycloak is an open-source identity and access management solution that simplifies authentication and authorization processes. When running Keycloak in Docker, it is crucial to ensure remote state management, which helps track configuration changes while preserving existing resources. This guide highlights how to use the keycloak-config-cli tool, which allows you to manage configurations efficiently.
-
-### Benefits of Remote State Management
+# Remote State Management
 
 Remote state management ensures that configurations are tracked and only modified when necessary, enabling safe and controlled updates to Keycloak configurations without altering unmanaged resources.
 
-## Environment Setup
-
-### Directory Structure
-
-Ensure your project directory has the following structure:
+Ensure your project directory has the following structure for sample demonstration locally:
 
 ```plaintext
 keycloak-setup/
@@ -39,7 +20,6 @@ Each file serves the following purpose:
 - `keycloak-config-cli.jar`: Keycloak-config-cli is compatible with different versions of Keycloak and actively maintained.
 - `realms/state-management.json`: JSON file with realm configuration.
 
-### Docker Compose Configuration
 
 In `docker-compose.yml`, configure the Keycloak service without a Keycloak Config CLI container, as we will be handling imports manually in this case.
 
@@ -65,14 +45,12 @@ services:
 
 This file configures Keycloak with essential parameters and maps `./realms` for importing configuration files.
 
-## Creating the Keycloak Configuration Import Script
 
 The `import.sh` script uses the `keycloak-config-cli.jar` to apply configurations. This script will:
 
 1. Copy the config file to the container.
 2. Run the import using the CLI JAR file, with remote state management enabled.
 
-### Script Functionality
 
 Create `import.sh` as follows:
 
@@ -99,11 +77,9 @@ java -jar keycloak-config-cli.jar \
 echo "Import of $CONFIG_FILE with remote-state enabled is complete."
 ```
 
-## JSON Configuration File: State Management Example
 
 Create `state-management.json` under `realms/`, which defines a Keycloak realm, clients, and roles.
 
-### Defining a Realm Configuration
 
 Define the realm, clients, roles, and scope mappings for demonstration:
 
@@ -164,7 +140,7 @@ docker-compose up -d
 
 Manually create a dedicated client to test remote state management.
 
-##  Conclusion
+###  Conclusion
 
 In this guide, we covered the basics of setting up Keycloak with Docker, creating an import script for configuration, and enabling remote state management using `keycloak-config-cli`.