Merge pull request #35 from ssilvert/switch-to-standalone-xml

KEYCLOAK-3196: Use WildFly management model for server configuration

topics/MigrationFromOlderVersions.adoc

@@ -12,16 +12,69 @@ It's highly recommended that you backup your database prior to upgrading Keycloa
 Migration from a candidate release (CR) to a Final release is not supported. We do however recommend that you test
 migration for a CR so we can resolve any potential issues before the Final is released.
 
+=== Migrate and convert keycloak-server.json
+
+You should copy `standalone/configuration/keycloak-server.json` from the old version to make sure any configuration changes you've done are added to the new installation.
+The version specific section below will list any changes done to this file that you have to do when upgrading from one version to another. 
+
+Keycloak is moving away from the use of keycloak-server.json.  For this release, the server will still work
+if this file is in `standalone/configuration/keycloak-server.json`, but it is highly recommended that
+you convert to using standalone.xml, standalone-ha.xml, or domain.xml for configuration. We may soon remove
+support for keycloak-server.json.
+
+To convert your keycloak-server.json, you will use a new jboss-cli operation called `migrate-json`.  
+It is recommended that you run this operation while the server is not running.
+
+The jboss-cli tool is discussed in detail in link:{{book.installguide.link}}[{{book.installguide.name}}].
+
+==== migrate-json in Standalone Mode
+
+For standalone, you will issue the `migrate-json` operation in `embed` mode without
+the server running.
+
+.Standalone keycloak-server.json migration
+[source]
+----
+$ .../bin/jboss-cli.sh
+[disconnected /] embed-server --server-config=standalone.xml
+[standalone@embedded /] /subsystem=keycloak-server/:migrate-json
+----
+The `migrate-json` operation will look for your keycloak-server.json file in
+the `standalone/configuration` directory.  You also have the option of using
+the `file` argument as shown in the domain mode example below.
+
+==== migrate-json in Domain Mode
+
+For a domain, you will stop the Keycloak server and
+issue the `migrate-json` operation against the running domain controller.
+If you choose not to stop the Keycloak server, the operation will still work,
+but your changes will not take affect until the Keycloak server is restarted.
+
+Domain mode migration requires that you use the `file` parameter to upload your 
+keycloak-server.json from a local directory.  The example below shows connecting
+to localhost.  You will need to substitute the address of your domain controller.
+
+.Domain mode keycloak-server.json migration
+[source]
+----
+$ .../bin/jboss-cli.sh -c --controller=localhost:9990
+[domain@localhost:9990 /] cd profile=auth-server-clustered
+[domain@localhost:9990 profile=auth-server-clustered] cd subsystem=keycloak-server
+[domain@localhost:9990 subsystem=keycloak-server] :migrate-json(file="./keycloak-server.json")
+----
+You will need to repeat the `migrate-json` operation for each profile containing a `keycloak-server` subsystem.
+
 === Migrate database
 
-Keycloak can automatically migration the database schema, or you can choose to do it manually.
+Keycloak can automatically migrate the database schema, or you can choose to do it manually.
 
 ==== Relational database
 
 To enable automatic upgrading of the database schema set the `migrationStrategy` property to `update` for
 the default `connectionsJpa` provider:
 
-[source]
+.Edit xml
+[source,xml]
 ----
 <spi name="connectionsJpa">
     <provider name="default" enabled="true">
@@ -33,6 +86,12 @@ the default `connectionsJpa` provider:
 </spi>
 ----        
 
+.Equivalent CLI command for above
+[source]
+----
+/subsystem=keycloak-server/spi=connectionsJpa/provider=default/:map-put(name=properties,key=migrationStrategy,value=update)
+----
+
 When you start the server with this setting your database will automatically be migrated if the database schema has
 changed in the new version.
 
@@ -49,7 +108,8 @@ Mongo doesn't have a schema, but there may still be things like collections and
 To enable automatic creation of these set the `migrationStrategy` property to `update` for the default `connectionsMongo`
 provider:
 
-[source]
+.Edit xml
+[source,xml]
 ----
 <spi name="connectionsMongo">
     <provider name="default" enabled="true">
@@ -61,16 +121,17 @@ provider:
 </spi>
 ----
 
+.Equivalent CLI command for above
+[source]
+----
+/subsystem=keycloak-server/spi=connectionsMongo/provider=default/:map-put(name=properties,key=migrationStrategy,value=update)
+----
+
 The Mongo provider does not have the option to manually apply the required changes.
 
 There's also the option to disable migration by setting the `migrationStrategy` to `validate`. With this configuration
 the database will be checked at startup and if it is not migrated the server will exit.
 
-=== Migrate keycloak-server.json
-
-You should copy `standalone/configuration/keycloak-server.json` from the old version to make sure any configuration changes you've done are added to the new installation.
-The version specific section below will list any changes done to this file that you have to do when upgrading from one version to another. 
-
 === Migrate providers
 
 If you have implemented any SPI providers you need to copy them to the new server.

topics/events/login.adoc

@@ -90,18 +90,22 @@ The Email Event Listener only supports the following events at the moment:
 To enable the Email Listener go to the `Config` tab and click on the `Event Listeners` field.  This will show a drop down list box
 where you can select email.
 
-You can exclude one or more events by editing the `keycloak-server.json` that comes with your distribution and adding for example:
+You can exclude one or more events by editing the `standalone.xml`, `standalone-ha.xml`, or `domain.xml` 
+that comes with your distribution and adding for example:
 
-[source]
+[source,xml]
 ----
-"eventsListener": {
+<spi name="eventsListener">
-    "email": {
+  <provider name="email" enabled="true">
-        "exclude-events": [ "UPDATE_TOTP", "REMOVE_TOTP" ]
+    <properties>
-    }
+      <property name="exclude-events" value="[&quot;UPDATE_TOTP&quot;,&quot;REMOVE_TOTP&quot;]"/>
-}
+    </properties>
+  </provider>
+</spi>
 ----
 
-See the link:{{book.installguide.link}}[{{book.installguide.name}}] for more details on where the `keycloak-server.json` file lives.
+See the link:{{book.installguide.link}}[{{book.installguide.name}}] for more details on 
+where the `standalone.xml`, `standalone-ha.xml`, or `domain.xml` file lives.