Rework admin configuration docs

docs/admin/configuration/authentication-and-user-management/external-idp.md

@@ -2,14 +2,16 @@
 sidebar_position: 1
 id: external-idp
 title: External OpenID Connect Identity Provider
+description: Integrating external OpenID Connect Identity Providers
+draft: false
 ---
 
 # Integrating external OpenID Connect Identity Providers
 
-## OpenCloud Configuration
-
 The following environment variables are relevant when connecting OpenCloud to an external IDP
 
+## OpenCloud Configuration
+
 - `OC_OIDC_ISSUER`: Set this to the issuer URL of the external Identity Provider
 - `OC_EXCLUDE_RUN_SERVICES`: To disable the built-in Identity Provider set this to `idp`
 - `PROXY_OIDC_REWRITE_WELLKNOWN`: Set this to `true` to expose the Identity
@@ -103,7 +105,9 @@ The default `role_claim` (or `PROXY_ROLE_ASSIGNMENT_OIDC_CLAIM`) is `roles`. The
   claim_value: opencloudGuest
 ```
 
-Note: When `PROXY_ROLE_ASSIGNMENT_DRIVER` is set to `oidc` it is recommended to set `GRAPH_ASSIGN_DEFAULT_USER_ROLE` to `false`.
+:::note
+When `PROXY_ROLE_ASSIGNMENT_DRIVER` is set to `oidc` it is recommended to set `GRAPH_ASSIGN_DEFAULT_USER_ROLE` to `false`.
+:::
 
 ## Client Configuration
 
@@ -113,9 +117,9 @@ OpenCloud requires several OIDC clients to be configured in the Identity Provide
 
 The web client is used for browser-based access to OpenCloud:
 
-- **Client ID**: `web`
-- **Client Type**: Public client
-- **Redirect URIs**:
+- Client ID: `web`
+- Client Type: Public client
+- Redirect URIs:
   - `https://your-domain.example.com/`
   - `https://your-domain.example.com/oidc-callback.html`
   - `https://your-domain.example.com/oidc-silent-redirect.html`
@@ -124,34 +128,34 @@ The web client is used for browser-based access to OpenCloud:
 
 The desktop client is used for the OpenCloud desktop application:
 
-- **Client ID**: `OpenCloudDesktop`
-- **Client Type**: Public client
-- **Redirect URIs**:
+- Client ID: `OpenCloudDesktop`
+- Client Type: Public client
+- Redirect URIs:
   - `http://127.0.0.1`
   - `http://localhost`
 
 ### Mobile App Clients
 
 #### Android App
 
-- **Client ID**: `OpenCloudAndroid`
-- **Client Type**: Public client
-- **Redirect URIs**: `oc://android.opencloud.eu`
-- **Post Logout Redirect URIs**: `oc://android.opencloud.eu`
+- Client ID: `OpenCloudAndroid`
+- Client Type: Public client
+- Redirect URIs: `oc://android.opencloud.eu`
+- Post Logout Redirect URIs: `oc://android.opencloud.eu`
 
 #### iOS App
 
-- **Client ID**: `OpenCloudIOS`
-- **Client Type**: Public client
-- **Redirect URIs**: `oc://ios.opencloud.eu`
-- **Post Logout Redirect URIs**: `oc://ios.opencloud.eu`
+- Client ID: `OpenCloudIOS`
+- Client Type: Public client
+- Redirect URIs: `oc://ios.opencloud.eu`
+- Post Logout Redirect URIs: `oc://ios.opencloud.eu`
 
 ### Additional Clients
 
 #### Cyberduck File Transfer Client
 
-- **Client ID**: `Cyberduck`
-- **Client Type**: Public client
-- **Redirect URIs**:
+- Client ID: `Cyberduck`
+- Client Type: Public client
+- Redirect URIs:
   - `x-cyberduck-action:oauth`
   - `x-mountainduck-action:oauth`

docs/admin/configuration/authentication-and-user-management/keycloak.md

@@ -2,16 +2,18 @@
 sidebar_position: 3
 id: keycloak
 title: Keycloak Integration
+description: Keycloak Integration
+draft: false
 ---
 
 # Keycloak Integration
 
 OpenCloud supports using Keycloak as an external identity provider, providing enterprise-grade identity management capabilities. This guide explains how to set up and configure Keycloak with OpenCloud.
 This guide is divided into three main sections:
 
-- **[Keycloak Integration Overview](#opencloud-configuration-for-keycloak-general)**: A brief overview of the integration process.
-- **[Shared User Directory Mode](#configuration-for-shared-directory-mode)**: Keycloak and OpenCloud share a common LDAP directory for user management.
-- **[Autoprovisioning Mode](#configuration-for-autoprovisioning-mode)**: OpenCloud autoprovisions users in a separate LDAP directory managed by OpenCloud.
+- [Keycloak Integration Overview](#opencloud-configuration-for-keycloak-general): A brief overview of the integration process.
+- [Shared User Directory Mode](#configuration-for-shared-directory-mode): Keycloak and OpenCloud share a common LDAP directory for user management.
+- [Autoprovisioning Mode](#configuration-for-autoprovisioning-mode): OpenCloud autoprovisions users in a separate LDAP directory managed by OpenCloud.
 
 ## OpenCloud Configuration for Keycloak (General)
 
@@ -64,8 +66,8 @@ If you need to manually configure the clients in Keycloak:
 
 OpenCloud supports Keycloak's backchannel logout feature, which allows Keycloak to notify OpenCloud when a user logs out. This ensures that all sessions are properly terminated:
 
-- **Backchannel Logout URL**: `https://your-domain.example.com/backchannel_logout`
-- **Backchannel Logout Session Required**: `true`
+- Backchannel Logout URL: `https://your-domain.example.com/backchannel_logout`
+- Backchannel Logout Session Required: `true`
 
 ## Shared User Directory Mode
 
@@ -97,7 +99,7 @@ graph TD
 
 In this mode, a readable LDAP Directory with existing users serves as a central user directory for both Keycloak and OpenCloud.
 
-**Key characteristics:**
+Key characteristics:
 
 - LDAP is the source of truth for user information
 - The LDAP server uses standard attributes (uid, cn, sn, givenName, mail)
@@ -115,7 +117,7 @@ OpenCloud can work with any LDAP schema containing standard attributes:
 - Groups are stored in a dedicated organizational unit
 - Default configuration sets LDAP as read-only
 
-**Example LDAP Structure:**
+Example LDAP Structure:
 
 ```bash
 dc=example,dc=org              # Base DN
@@ -185,7 +187,7 @@ OpenCloud provides complete example deployments using Docker Compose:
 1. Navigate to `deployments/examples/opencloud_full`
 2. Edit the `.env` file to enable the Shared Directory Mode:
 
-**For Shared Directory Mode:**
+For Shared Directory Mode:
 
 ```bash
 # Enable services
@@ -202,7 +204,7 @@ Keycloak is configured during startup by importing the `keycloak-realm.dist.json
 
 :::warning
 
-Keycloak can import the realm configuration file **only once** during the first startup. If you need to change the configuration, you must delete the Keycloak container and volume and restart it. This will reset Keycloak to its initial state.
+Keycloak can import the realm configuration file only once during the first startup. If you need to change the configuration, you must delete the Keycloak container and volume and restart it. This will reset Keycloak to its initial state.
 
 :::
 
@@ -214,14 +216,14 @@ This mode is suitable in scenarios where the OpenIDConnect provider is external
 ```mermaid
 graph TD
     subgraph opencloud["OpenCloud Deployment"]
-        LDAP[("`**LDAP Server**
+        LDAP[("`LDAP Server
             - managed by opencloud
             - custom schema`")]
-        OpenCloud["`**OpenCloud Server**`"]
+        OpenCloud["`OpenCloud Server`"]
         Stop((("Block <br>disabled<br>Users")))
     end
     subgraph existing["Existing Infrastructure"]
-        Keycloak("`**Keycloak**<br>(OIDC Provider)`")
+        Keycloak("`Keycloak<br>(OIDC Provider)`")
         UserDirectory[("`Federated Identity Provider
         - Microsoft
         - Google
@@ -245,7 +247,7 @@ graph TD
 ```
 
 - Keycloak manages the users, groups, and roles
-- The openCloud Clients and Sessions are configured in Keycloak
+- The OpenCloud Clients and Sessions are configured in Keycloak
 - Simplified user management with "just-in-time" provisioning
 - Federation with external identity providers is supported (e.g., Google, GitHub, Facebook, Microsoft)
 - In this case, we need to provide an LDAP server which is fully controlled by OpenCloud and needs a custom [LDAP Schema](https://github.com/opencloud-eu/opencloud/blob/main/deployments/examples/shared/config/ldap/schemas/10_opencloud_schema.ldif).
@@ -292,7 +294,7 @@ OpenCloud provides complete example deployments using Docker Compose:
 1. Navigate to `deployments/examples/opencloud_full`
 2. Edit the `.env` file to enable the Autoprovisioning Mode:
 
-**For Autoprovisioning Mode:**
+For Autoprovisioning Mode:
 
 ```bash
 # Enable services
@@ -308,17 +310,17 @@ Keycloak is configured during startup by importing the `keycloak-autoprovisionin
 
 :::warning
 
-Keycloak can import the realm configuration file **only once** during the first startup. If you need to change the configuration, you must delete the Keycloak container and volume and restart it. This will reset Keycloak to its initial state.
+Keycloak can import the realm configuration file only once during the first startup. If you need to change the configuration, you must delete the Keycloak container and volume and restart it. This will reset Keycloak to its initial state.
 
 :::
 
 ## Troubleshooting
 
 Common issues and solutions:
 
-- **User cannot log in**:
+- User cannot log in:
   - Check LDAP connectivity and user existence
   - Check if each user has an OpenCloud Role assigned
   - Verify that the client IDs and redirect URIs match exactly
-- **Groups not synchronized**: Verify group mappings in Keycloak
-- **User creation fails (autoprovisioning mode)**: Ensure LDAP has write permissions in Autoprovisioning Mode
+- Groups not synchronized: Verify group mappings in Keycloak
+- User creation fails (autoprovisioning mode): Ensure LDAP has write permissions in Autoprovisioning Mode

docs/admin/configuration/logging.md

@@ -2,18 +2,14 @@
 sidebar_position: 13
 id: logging
 title: Logging
+description: Logging in OpenCloud
+draft: false
 ---
 
 # Logging in OpenCloud
 
----
-
-## Introduction
-
 Logging helps monitor OpenCloud’s health and diagnose issues. Log output varies by level, from minimal to detailed. By default, logs are written to `stderr`. In Docker deployments, logs are accessible via `docker logs`.
 
----
-
 ## Log Levels
 
 Set the global log level using the `OPEN_CLOUD_LOG_LEVEL` environment variable. You can also override it per service using service-specific variables. Default is `error`.
@@ -40,8 +36,6 @@ Routine events that confirm expected behavior and operation.
 
 Highly detailed messages for diagnosing problems. Use cautiously in production due to verbosity.
 
----
-
 ## Request Correlation
 
 ### X-Request-ID

docs/admin/configuration/mail-notifications.md

@@ -2,16 +2,15 @@
 sidebar_position: 9
 id: mail-notificatons
 title: Mail Notifications
-description: 'How to activate mail notifications in OpenCloud.'
+description: How to activate mail notifications in OpenCloud.
+draft: false
 ---
 
 # Mail notifications in OpenCloud
 
-## This guide shows how to configure your OpenCloud instance to send notification E-Mails by modifying the `.env` file in your OpenCloud setup
+This guide shows how to configure your OpenCloud instance to send notification E-Mails by modifying the `.env` file in your OpenCloud setup
 
----
-
-### 🛠️ Step 1: Open the .env File
+## Open the .env File
 
 Edit the file with your preferred text editor:
 
@@ -21,14 +20,12 @@ nano .env
 
 Or use vim, code, or gedit as you prefer.
 
----
-
-### 📝 Step 2: Add or Modify These Environment Variables
+## Add or modify these Environment Variables
 
 Adjust the following lines in your `.env` file according to your SMTP provider and requirements.  
 Note: `SMTP_TRANSPORT_ENCRYPTION` and `SMTP_INSECURE` may vary depending on your setup.
 
-**SMTP Settings:**
+SMTP Settings:
 
 ```env
 SMTP_HOST=YOUR_SMTP_HOST
@@ -40,17 +37,15 @@ SMTP_TRANSPORT_ENCRYPTION=none
 SMTP_INSECURE=true
 ```
 
-⚠️ In the .env file, values should be written without quotation marks. Do not use 'single quotes' or "double quotes" — just enter the plain value.
-
----
+:::warning
+In the .env file, values should be written without quotation marks. Do not use 'single quotes' or "double quotes" — just enter the plain value.
+:::
 
-### 💾 Step 3: Save and Exit
+## Save and exit
 
 For nano, press Ctrl + O to save and Ctrl + X to exit.
 
----
-
-### 🔄 Step 4: Restart OpenCloud
+## Restart OpenCloud
 
 Apply the changes by restarting the OpenCloud services:
 
@@ -59,6 +54,4 @@ docker compose down
 docker compose up -d
 ```
 
----
-
 OpenCloud is now successfully configured to deliver notification emails, including those triggered by actions such as file sharing.

docs/admin/configuration/radicale-integration.md

@@ -2,9 +2,12 @@
 sidebar_position: 12
 id: radicale-integration
 title: Calendar and Contacts Integration with Radicale
-description: 'How to enable Calendar and Contacts integration via Radicale in OpenCloud.'
+description: How to enable Calendar and Contacts integration via Radicale in OpenCloud.
+draft: false
 ---
 
+# Integration with Radicale
+
 OpenCloud is able to act as an authenticating reverse proxy for the open-source
 CalDAV and CardDAV Server [Radicale](https://radicale.org). With that, users
 get a calender- and contacts server out of the box with OpenCloud that can be
@@ -26,7 +29,7 @@ To use this feature you need at least OpenCloud Version 2.3.0. Earlier releases
 some of the required features. This guide assumes that you already have a running
 deployment based on the `opencloud_full` deployment example.
 
-### 1. Configure the `.env` file to deploy Radicale
+### Configure the `.env` file to deploy Radicale
 
 In the root directory of the `opencloud_full` deployment example, usually `opencloud/deployments/examples/opencloud_full`,
 remove the `#` symbol from the line:
@@ -35,7 +38,7 @@ remove the `#` symbol from the line:
 #RADICALE=:radicale.yml
 ```
 
-### 2. Update the deployment
+### Update the deployment
 
 ```bash
 docker compose up -d

docs/admin/configuration/storage/cephfs.md

@@ -2,5 +2,6 @@
 sidebar_position: 2
 id: storage-cephfs
 title: 'CephsFS'
+description: CephsFS
 draft: true
 ---