Feat/doc for minimal export

CHANGELOG.md

@@ -20,6 +20,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ### Added
 - improved logging for realm retrieval errors [#1010](https://github.com/adorsys/keycloak-config-cli/issues/1010)
+
+### Added
+- Add documentation for minimal configuration [#1195](https://github.com/orgs/adorsys/projects/5/views/1?pane=issue&itemId=80856237&issue=adorsys%7Ckeycloak-config-cli%7C933)
 ### Fixed
 - Fix required action import handling for no-delete option [#834](https://github.com/adorsys/keycloak-config-cli/issues/834)
 

docs/config/geting-a-minimal-import-json-after-export.md

@@ -0,0 +1,67 @@
+# Getting Minimal Import After Realm Export
+
+This script is designed to clean up a Keycloak realm configuration file (in JSON format) by removing unnecessary fields, including all `id` fields, from the configuration. It is useful for simplifying the export of Keycloak realm data, especially when certain details like IDs are not needed for sharing or backup purposes.
+
+## Features
+
+- **Removes unnecessary default fields** such as `accessTokenLifespan`, `offlineSessionIdleTimeout`, and others that are typically not needed for a reimport.
+- **Simplifies the realm configuration** while retaining all necessary data for further processing or importing into another Keycloak instance.
+
+## Requirements
+
+- **jq**: This script requires `jq`, a command-line JSON processor, to manipulate the JSON data.
+
+  You can install `jq` using the following commands:
+
+    - On Ubuntu/Debian:
+      ```bash
+      sudo apt-get install jq
+      ```
+    - On macOS (with Homebrew):
+      ```bash
+      brew install jq
+      ```
+
+## Usage
+
+Ensure you have the Keycloak realm configuration file (in JSON format) that you want to clean. The file should be named `realm-config.json` or you can modify the script to use your desired file path.
+
+### Download or Copy the Script
+
+```bash
+#!/bin/bash
+
+INPUT_FILE="realm-config.json"
+OUTPUT_FILE="keycloak-realm-export-minimal.json"
+
+jq 'del(
+  .id, .containerId, .accessTokenLifespanForImplicitFlow,
+  .accessTokenLifespanForWebApps, .accessTokenLifespan, .offlineSessionIdleTimeout,
+  .accessTokenLifespanInSeconds, .ssoSessionIdleTimeout, .ssoSessionMaxLifespan,
+  .ssoSessionIdleTimeoutRememberMe, .ssoSessionMaxLifespanRememberMe,
+  .accessCodeLifespan, .accessCodeLifespanLogin, .accessCodeLifespanUserAction,
+  .accessCodeLifespanMobile, .notBefore, .registrationAllowed,
+  .registrationEmailAsUsername, .rememberMe, .verifyEmail, .resetPasswordFlow,
+  .editUsernameAllowed, .bruteForceProtected, .permanentLockout, .maxFailureWaitSeconds,
+  .minimumQuickLoginWaitSeconds, .waitIncrementSeconds, .quickLoginCheckMilliSeconds,
+  .maxDeltaTimeSeconds, .failureFactor, .requiredCredentials, .otpPolicyType,
+  .otpPolicyAlgorithm, .otpPolicyInitialCounter, .otpPolicyDigits, .otpPolicyLookAheadWindow,
+  .otpPolicyPeriod, .otpSupportedApplications, .webAuthnPolicyRpEntityName,
+  .webAuthnPolicyAttestationConveyancePreference, .webAuthnPolicyAuthenticatorAttachment,
+  .webAuthnPolicyRequireResidentKey, .webAuthnPolicyUserVerificationRequirement,
+  .webAuthnPolicyCreateTimeout, .webAuthnPolicyAssertionTimeout,
+  .webAuthnPolicyRegistrationRecoveryEnabled, .webAuthnPolicyRegistrationRecoveryCodesQuantity,
+  .webAuthnPolicyRegistrationTokenBindingRequired, .webAuthnPolicyRegistrationAttestationConveyancePreference,
+  .webAuthnPolicyRegistrationAuthenticatorSelectionCriteria, .keys
+) 
+| walk(if type == "object" then del(.id) else . end)' < "$INPUT_FILE" > "$OUTPUT_FILE"
+
+echo "Minimal export saved to $OUTPUT_FILE"
+```
+
+### make the script executable
+```bash
+    chmod +x clean-realm-config.sh
+```
+
+Now execute the script, making sure that you have inputed the correct file paths.

docs/config/remote-state-management.md

@@ -0,0 +1,147 @@
+## 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.
+
+Ensure your project directory has the following structure for sample demonstration locally:
+
+```plaintext
+keycloak-setup/
+├── docker-compose.yml
+├── import.sh
+├── keycloak-config-cli.jar
+└── realms/
+└── state-management.json
+```
+
+Each file serves the following purpose:
+
+- `docker-compose.yml`: Defines the Keycloak service.
+- `import.sh`: Custom shell script for running the Keycloak Config CLI against our Keycloak instance.
+- `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.
+
+
+In `docker-compose.yml`, configure the Keycloak service without a Keycloak Config CLI container, as we will be handling imports manually in this case.
+
+```yaml
+services:
+  keycloak:
+    image: quay.io/keycloak/keycloak:25.0.1
+    environment:
+      KEYCLOAK_ADMIN: admin
+      KEYCLOAK_ADMIN_PASSWORD: admin
+      KC_HOSTNAME: localhost
+      KC_HTTP_PORT: "8080"
+      KC_HTTP_ENABLED: "true"
+      KC_METRICS_ENABLED: "true"
+      KC_HEALTH_ENABLED: "true"
+    ports:
+      - "8080:8080"
+    volumes:
+      - ./realms:/opt/keycloak/data/import:z
+    command:
+      - "start-dev"
+```
+
+This file configures Keycloak with essential parameters and maps `./realms` for importing configuration files.
+
+
+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.
+
+
+Create `import.sh` as follows:
+
+```bash
+#!/bin/bash
+
+# Check if a configuration file is provided
+if [ -z "$1" ]; then
+  echo "Usage: ./import.sh <config-file>"
+  exit 1
+fi
+
+CONFIG_FILE=$1
+
+# Run the Keycloak Config CLI tool with the updated options
+java -jar keycloak-config-cli.jar \
+  --keycloak.url="http://localhost:8080" \
+  --keycloak.user="admin" \
+  --keycloak.password="admin" \
+  --import.managed.group="full" \
+  --import.remote-state.enabled="true" \
+  --import.files.locations="$CONFIG_FILE"
+
+echo "Import of $CONFIG_FILE with remote-state enabled is complete."
+```
+
+
+Create `state-management.json` under `realms/`, which defines a Keycloak realm, clients, and roles.
+
+
+Define the realm, clients, roles, and scope mappings for demonstration:
+
+```json
+{
+  "realm": "master",
+  "enabled": true,
+  "clients": [
+    {
+      "clientId": "imported-client",
+      "enabled": true,
+      "protocol": "openid-connect",
+      "fullScopeAllowed": false
+    }
+  ],
+  "roles": {
+    "realm": [
+      {
+        "name": "my-role",
+        "description": "A test role"
+      }
+    ]
+  },
+  "clientScopes": [
+    {
+      "name": "custom-scope",
+      "description": "Custom client scope",
+      "protocol": "openid-connect",
+      "attributes": {
+        "include.in.token.scope": "true"
+      }
+    }
+  ],
+  "scopeMappings": [
+    {
+      "client": "imported-client",
+      "roles": [
+        "my-role"
+      ]
+    }
+  ]
+}
+```
+
+### Verifying Remote State Management
+
+With remote state management enabled, Keycloak Config CLI will only modify resources it initially created, preserving custom or manually added configurations.
+
+#### Starting Keycloak
+
+To start Keycloak, run:
+
+```shell
+docker-compose up -d
+```
+
+#### Testing Remote State
+
+Manually create a dedicated client to test remote state management.
+
+####  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`.
+
+Feel free to reach out if you have any questions or need further assistance!

mkdocs.yml

@@ -0,0 +1,75 @@
+site_name: kc-config-cli
+site_url: https://adorsys.github.io/keycloak-config-cli/
+theme:
+  name: material
+  features:
+    - navigation.tabs
+    - navigation.sections
+    - toc.integrate
+    - navigation.top
+    - search.suggest
+    - search.highlight
+    - content.tabs.link
+    - content.code.annotation
+    - content.code.copy
+  language: en
+  palette:
+    - scheme: default
+      toggle:
+        icon: material/toggle-switch-off-outline 
+        name: Switch to dark mode
+      primary: teal
+      accent: purple 
+    - scheme: slate 
+      toggle:
+        icon: material/toggle-switch
+        name: Switch to light mode    
+      primary: teal
+      accent: lime
+
+plugins:
+  - social
+  - search
+
+extra:
+  social:
+    - icon: fontawesome/brands/github-alt
+      link: https://github.com/adorsys
+    - icon: fontawesome/brands/twitter
+      link: https://twitter.com/adorsys
+    - icon: fontawesome/brands/linkedin
+      link: https://www.linkedin.com/in/adorsys/
+
+nav:
+  - Home:
+      - Getting Started: index.md
+      - Supported Features: supported-features.md
+      - Import settings: import-settings.md
+      - managed-resources: managed-resource.md
+      - Redhat-sso compatibility: RedHat-SSO-compatibility.md
+      - Helm Chart: helm-chart.md
+  - Use Cases:
+      - Remote State Management: config/remote-state-management.md
+      - Adding Multiple post.logout.redirect.uris: config/addind-multiple-post-logout-redirect-uris.md
+      - Getting minimal import after realm export: config/geting-a-minimal-import-json-after-export.md
+
+
+markdown_extensions:
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - admonition
+  - pymdownx.arithmatex:
+      generic: true
+  - footnotes
+  - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.mark
+  - attr_list
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+
+copyright: |
+  &copy; 2024 <a href="https://github.com/adorsys" target="_blank" rel="noopener">Adorsys GmbH & Co. KG</a>