JBoss.orgCommunity Documentation

Chapter 25. Migration from older versions

25.1. Migrate database
25.2. Migrate keycloak-server.json
25.3. Migrate providers
25.4. Migrate themes
25.5. Migrate application
25.6. Version specific migration
25.6.1. Migrating from 1.0.x.Final to 1.1.Beta1
25.6.2. Migrating from 1.0 RC-1 to RC-2
25.6.3. Migrating from 1.0 Beta 4 to RC-1
25.6.4. Migrating from 1.0 Beta 1 to Beta 4
25.6.5. Migrating from 1.0 Alpha 4 to Beta 1
25.6.6. Migrating from 1.0 Alpha 2 to Alpha 3
25.6.7. Migrating from 1.0 Alpha 1 to Alpha 2

To upgrade to a new version of Keycloak first download and install the new version of Keycloak. You then have to migrate the database, keycloak-server.json, providers, themes and applications from the old version.

Keycloak provides automatic migration of the database. It's highly recommended that you backup your database prior to upgrading Keycloak.

To enable automatic upgrading of the database if you're using a relational database make sure databaseSchema is set to update for connectionsJpa:

"connectionsJpa": {
    "default": {
        ...
        "databaseSchema": "update"
    }
}

For MongoDB do the same, but for connectionsMongo:

"connectionsMongo": {
    "default": {
        ...
        "databaseSchema": "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.

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.

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.

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.

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.