keycloak-scim/server_admin/topics/MigrationFromOlderVersions.adoc

// MOVED TO SEPARATE UPGRADE GUIDE!
// Add Keycloak migration changes to upgrading/topics/keycloak/changes.adoc


== Migration from older versions

To upgrade to a new version of Keycloak first download and install the new version of Keycloak. Once the new version
is installed migrate the config files, database, keycloak-server.json, providers, themes and applications to the new applications.

This chapter contains some general migration details which are applicable to all versions. There are instructions for
migration that is only applicable to a specific release. If you are upgrading from a very old version you need to go
through all intermediate version specific migration.

It's highly recommended that you backup your database prior to upgrading Keycloak.

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.

=== Migration of config files using migration scripts
As part of your migration, you should use your old versions of config files `standalone.xml`, `standalone-ha.xml`, and/or `domain.xml`.
These files typically contain configuration that is unique to your own environment.  So, the first thing to do as part
of a migration is to copy those files to the new Keycloak server installation, replacing the default versions.

If migrating from Keycloak version 2.1.0 or older, you should also copy `keycloak-server.json` to `standalone/configuration`
and/or `domain/configuration`.

There will be configuration in those config files that pertains to Keycloak, which will need to be upgraded.  For that,
you should run one or more of the appropriate upgrade scripts.  They are `migrate-standalone.cli`, `migrate-standalone-ha.cli`, 
`migrate-domain-standalone.cli` and `migrate-domain-clustered.cli`.

The server should not be running when you execute a migration script.

.Example for running migrate-standalone.cli
[source]
----
$ .../bin/jboss-cli.sh --file=migrate-standalone.cli
----

Note that for upgrading domain.xml, there are two migration scripts, `migrate-domain-standalone.cli` and
`migrate-domain-clustered.cli`.  These scripts migrate separate profiles within your domain.xml that were
originally shipped with Keycloak.  If you have changed the name of the profile there is a variable near
the top of the script that you will need to change.
 
If you are migrating `keycloak-server.json`, this will also be migrated as needed.  If you prefer,
you can migrate `keycloak-server.json` beforehand using the instructions in the next section.

One thing to note is that the migration scripts only work for Keycloak versions 1.8.1 forward.  If migrating an older
version you will need to manually upgrade your config files to at least be 1.8.1 compliant.

Lastly, you may want to examine the contents of the scripts before running.  They show exactly what will be changed
for each version.  They also have values at the top of the script that you may need to change based on your
environment.

=== Migrate and convert keycloak-server.json
If you ran one of the migration scripts from the previous section then you have probably already migrated
your keycloak-server.json.  This section is kept here for reference.  If you prefer, you can follow the
instructions in this section before running the migration scripts above.

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 jboss-cli operation called `migrate-json`.
It is recommended that you run this operation while the server is not running.

The `migrate-json` operation assumes you are migrating with an xml configuration file from an old version.  For example,
you should not try to migrate your keycloak-server.json to a standalone.xml file that already contains <spi> and <theme>
tags under the keycloak subsystem.  Before migration, your keycloak subsystem should look like the one below:

.standalone.xml
[source,xml]
----
<subsystem xmlns="urn:jboss:domain:keycloak-server:1.1">
    <web-context>auth</web-context>
</subsystem>
----

The jboss-cli tool is discussed in detail in link:{installguide_link}[{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 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:

.Edit xml
[source,xml]
----
<spi name="connectionsJpa">
    <provider name="default" enabled="true">
        <properties>
            ...
            <property name="migrationStrategy" value="update"/>
        </properties>
    </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.

To manually migrate the database set the `migrationStrategy` to `manual`. When you start the server with this
configuration it will check if the database needs migration. If changes are needed the required changes are written
to an SQL file that you can review and manually run against the database.

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.

==== Mongo

Mongo doesn't have a schema, but there may still be things like collections and indexes that are added to new releases.
To enable automatic creation of these set the `migrationStrategy` property to `update` for the default `connectionsMongo`
provider:

.Edit xml
[source,xml]
----
<spi name="connectionsMongo">
    <provider name="default" enabled="true">
        <properties>
            ...
            <property name="migrationStrategy" value="update"/>
        </properties>
    </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 providers

If you have implemented any SPI providers you need to copy them to the new server.
The version specific section below will mention if any of the SPI's have changed.
If they have you may have to update your code accordingly.

=== Migrate themes

If you have created a custom theme you need to copy them to the new server.
The version specific section below will mention if changes have been made to themes.
If there is you may have to update your themes accordingly.

=== Migrate application

If you deploy applications directly to the Keycloak server you should copy them to the new server.
For any applications including those not deployed directly to the Keycloak server you should upgrade the adapter.
The version specific section below will mention if any changes are required to applications.