Merge pull request #829 from stianst/master

KEYCLOAK-805 Add overview section to migration docs

docbook/reference/en/en-US/modules/MigrationFromOlderVersions.xml

@@ -1,23 +1,103 @@
 <chapter id="Migration_from_older_versions">
     <title>Migration from older versions</title>
-    <sect1>
+
+    <para>
+        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.
+    </para>
+
+    <section>
+        <title>Migrate database</title>
+        <para>
+            Keycloak provides automatic migration of the database. It's highly recommended that you backup your
+            database prior to upgrading Keycloak.
+        </para>
+        <para>
+            To enable automatic upgrading of the database if you're using a relational database make sure
+            <literal>databaseSchema</literal> is set to <literal>update</literal> for <literal>connectionsJpa</literal>:
+<programlisting>
+"connectionsJpa": {
+    "default": {
+        ...
+        "databaseSchema": "update"
+    }
+}
+</programlisting>
+        </para>
+        <para>
+            For MongoDB do the same, but for <literal>connectionsMongo</literal>:
+<programlisting>
+"connectionsMongo": {
+    "default": {
+        ...
+        "databaseSchema": "update"
+    }
+}
+</programlisting>
+        </para>
+        <para>
+            When you start the server with this setting your database will automatically be migrated if the database
+            schema has changed in the new version.
+        </para>
+    </section>
+
+    <section>
+        <title>Migrate keycloak-server.json</title>
+        <para>
+            You should copy <literal>standalone/configuration/keycloak-server.json</literal> 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.
+        </para>
+    </section>
+
+    <section>
+        <title>Migrate providers</title>
+        <para>
+            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.
+        </para>
+    </section>
+
+    <section>
+        <title>Migrate themes</title>
+        <para>
+            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.
+        </para>
+    </section>
+
+    <section>
+        <title>Migrate application</title>
+        <para>
+            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.
+        </para>
+    </section>
+
+    <section>
+        <title>Version specific migration</title>
+        <section>
             <title>Migrating from 1.0.x.Final to 1.1.Beta1</title>
             <itemizedlist>
+                <listitem>RealmModel JPA and Mongo storage schema has changed</listitem>
                 <listitem>UserSessionModel JPA and Mongo storage schema has changed as these interfaces have been refactored</listitem>
                 <listitem>
                     Upgrade your adapters, old adapters are not compatible with Keycloak 1.1.  We interpreted JSON Web Token and OIDC ID Token specification incorrectly.  'aud'
                     claim must be the client id, we were storing the realm name in there and validating it.
                 </listitem>
             </itemizedlist>
-    </sect1>
+        </section>
-    <sect1>
+        <section>
             <title>Migrating from 1.0 RC-1 to RC-2</title>
             <itemizedlist>
                 <listitem>A lot of info level logging has been changed to debug. Also, a realm no longer has the jboss-logging audit listener by default.
                     If you want log output when users login, logout, change passwords, etc. enable the jboss-logging audit listener through the admin console.</listitem>
             </itemizedlist>
-    </sect1>
+        </section>
-    <sect1>
+        <section>
             <title>Migrating from 1.0 Beta 4 to RC-1</title>
             <itemizedlist>
                 <listitem>
@@ -27,8 +107,8 @@
                     The signature is the same as refresh token minus the grant type form parameter.  See documentation for details.
                 </listitem>
              </itemizedlist>
-    </sect1>
+        </section>
-    <sect1>
+        <section>
             <title>Migrating from 1.0 Beta 1 to Beta 4</title>
             <itemizedlist>
                 <listitem>
@@ -56,8 +136,8 @@
                     user.
                 </listitem>
             </itemizedlist>
-    </sect1>
+        </section>
-    <sect1>
+        <section>
             <title>Migrating from 1.0 Alpha 4 to Beta 1</title>
             <itemizedlist>
                 <listitem>
@@ -84,8 +164,8 @@
                     for me details.
                 </listitem>
             </itemizedlist>
-    </sect1>
+        </section>
-    <sect1>
+        <section>
             <title>Migrating from 1.0 Alpha 2 to Alpha 3</title>
             <itemizedlist>
                 <listitem>
@@ -104,8 +184,8 @@
                     Subject in AccessToken has been changed to the User ID.
                 </listitem>
             </itemizedlist>
-    </sect1>
+        </section>
-    <sect1>
+        <section>
             <title>Migrating from 1.0 Alpha 1 to Alpha 2</title>
             <itemizedlist>
                 <listitem>
@@ -130,5 +210,6 @@
                     credentials tab in the administration console.
                 </listitem>
             </itemizedlist>
-    </sect1>
+        </section>
+    </section>
 </chapter>