diff --git a/charts/opencloud/README.md b/charts/opencloud/README.md
index 7c3cd563..40fe8764 100644
--- a/charts/opencloud/README.md
+++ b/charts/opencloud/README.md
@@ -252,7 +252,7 @@ This will prepend `my-registry.com/` to all image references in the chart. For e
 | `opencloud.insecure` | Insecure mode (for self-signed certificates) | `true` |
 | `opencloud.existingSecret` | Name of the existing secret | `` |
 | `opencloud.adminPassword` | Admin password | `admin` |
-| `opencloud.createDemoUsers` | Create demo users | `false` |
+| `opencloud.demoUsers.enabled` | Create demo users in OpenCloud and Keycloak (alan, dennis, lynn, margaret, mary). **WARNING**: Demo users have hardcoded passwords and should never be used in production! | `false` |
 | `opencloud.resources` | CPU/Memory resource requests/limits | `{}` |
 | `opencloud.persistence.enabled` | Enable persistence | `true` |
 | `opencloud.persistence.size` | Size of the persistent volume | `10Gi` |
@@ -347,6 +347,29 @@ keycloak:
 
 **Note**: If `keycloak.internal.enabled` is `true`, the `global.oidc.issuer` should be left empty to not override the generated issuer URL.
 
+#### User Management
+
+When `opencloud.demoUsers.enabled` is set to `false` (default for production), you need to manually create users in Keycloak:
+
+1. **Access Keycloak Admin Console**:
+   - URL: `https://[your-keycloak-domain]/admin/`
+   - Login with Keycloak admin credentials (from `keycloak.internal.adminUser/adminPassword`)
+
+2. **Create Users in the openCloud Realm**:
+   - Switch to the "openCloud" realm (dropdown in top-left corner)
+   - Navigate to Users → Add User
+   - Create users and set passwords in the Credentials tab
+
+3. **Assign Roles**:
+   - Available roles in the openCloud realm:
+     - `opencloudAdmin` - Full administrative access
+     - `opencloudSpaceAdmin` - Space administration capabilities
+     - `opencloudUser` - Regular user access
+     - `opencloudGuest` - Guest access
+   - Assign roles in the Role Mappings tab for each user
+
+**WARNING**: The demo users (when `demoUsers.enabled: true`) have hardcoded passwords and should NEVER be used in production environments. They are intended for development and testing only.
+
 ### PostgreSQL Settings
 
 | Parameter | Description | Default |
diff --git a/charts/opencloud/files/keycloak/opencloud-realm.json.gotmpl b/charts/opencloud/files/keycloak/opencloud-realm.json.gotmpl
index 2aecf121..50c11c00 100644
--- a/charts/opencloud/files/keycloak/opencloud-realm.json.gotmpl
+++ b/charts/opencloud/files/keycloak/opencloud-realm.json.gotmpl
@@ -485,7 +485,9 @@
   "webAuthnPolicyPasswordlessAvoidSameAuthenticatorRegister" : false,
   "webAuthnPolicyPasswordlessAcceptableAaguids" : [ ],
   "webAuthnPolicyPasswordlessExtraOrigins" : [ ],
-  "users" : [ {
+  "users" : [
+{{- if .Values.opencloud.demoUsers.enabled }}
+  {
     "id" : "0ab77e6d-23b4-4ba3-9843-a3b3efdcfc53",
     "username" : "admin",
     "firstName" : "Admin",
@@ -622,7 +624,9 @@
     "realmRoles" : [ "default-roles-opencloud", "opencloudUser" ],
     "notBefore" : 0,
     "groups" : [ "/bible-readers", "/users" ]
-  } ],
+  }
+{{- end }}
+  ],
   "scopeMappings" : [ {
     "clientScope" : "offline_access",
     "roles" : [ "offline_access" ]
diff --git a/charts/opencloud/templates/opencloud/deployment.yaml b/charts/opencloud/templates/opencloud/deployment.yaml
index 85823a36..0341a1e1 100644
--- a/charts/opencloud/templates/opencloud/deployment.yaml
+++ b/charts/opencloud/templates/opencloud/deployment.yaml
@@ -278,7 +278,7 @@ spec:
                   key: adminPassword
             # Demo users
             - name: IDM_CREATE_DEMO_USERS
-              value: {{ .Values.opencloud.createDemoUsers | quote }}
+              value: {{ .Values.opencloud.demoUsers.enabled | quote }}
             {{- if .Values.opencloud.nats.external.enabled }}
             # Use the external nats as the service registry
             - name: MICRO_REGISTRY_ADDRESS
diff --git a/charts/opencloud/values.yaml b/charts/opencloud/values.yaml
index 643cd12a..1f2c0497 100644
--- a/charts/opencloud/values.yaml
+++ b/charts/opencloud/values.yaml
@@ -435,7 +435,10 @@ opencloud:
   adminPassword: admin
   
   # Create demo users
-  createDemoUsers: false
+  # Demo users configuration
+  demoUsers:
+    # Enable demo users (WARNING: Only for development/testing, NOT for production!)
+    enabled: false
   # Additional services to start
   additionalServices: []
   # Services to exclude from starting