Merge pull request #35 from ssilvert/switch-to-standalone-xml
KEYCLOAK-3196: Use WildFly management model for server configuration
This commit is contained in:
Stian Thorgersen
GitHub
commit
f38603956c
2 changed files with 81 additions and 16 deletions
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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": {
|
||||
"email": {
|
||||
"exclude-events": [ "UPDATE_TOTP", "REMOVE_TOTP" ]
|
||||
}
|
||||
}
|
||||
<spi name="eventsListener">
|
||||
<provider name="email" enabled="true">
|
||||
<properties>
|
||||
<property name="exclude-events" value="["UPDATE_TOTP","REMOVE_TOTP"]"/>
|
||||
</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.
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue