JBoss.orgCommunity Documentation

Chapter 26. Migration from older versions

26.1. Migrate database
26.2. Migrate keycloak-server.json
26.3. Migrate providers
26.4. Migrate themes
26.5. Migrate application
26.6. Version specific migration
26.6.1. Migrating from 1.1.Beta1 to 1.1.Beta2
26.6.2. Migrating from 1.0.x.Final to 1.1.Beta1
26.6.3. Migrating from 1.0 RC-1 to RC-2
26.6.4. Migrating from 1.0 Beta 4 to RC-1
26.6.5. Migrating from 1.0 Beta 1 to Beta 4
26.6.6. Migrating from 1.0 Alpha 4 to Beta 1
26.6.7. Migrating from 1.0 Alpha 2 to Alpha 3
26.6.8. 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.