diff --git a/docs/documentation/topics/templates/document-attributes.adoc b/docs/documentation/topics/templates/document-attributes.adoc index a10366439b..6bc252fbb0 100644 --- a/docs/documentation/topics/templates/document-attributes.adoc +++ b/docs/documentation/topics/templates/document-attributes.adoc @@ -7,6 +7,9 @@ :project_versionNpm: 999.0.0-SNAPSHOT :project_versionDoc: DEV +:archivebasename: keycloak +:archivedownloadurl: https://github.com/keycloak/keycloak/releases/download/{project_version}/keycloak-{project_version}.zip + :standalone: :api-management!: :on-prem: diff --git a/docs/documentation/upgrading/topics.adoc b/docs/documentation/upgrading/topics.adoc index b49287785c..07d57a0e4f 100644 --- a/docs/documentation/upgrading/topics.adoc +++ b/docs/documentation/upgrading/topics.adoc @@ -1,3 +1,3 @@ -include::topics/keycloak/intro.adoc[leveloffset=0] -include::topics/keycloak/upgrading.adoc[leveloffset=0] -include::topics/keycloak/changes.adoc[leveloffset=0] \ No newline at end of file +include::topics/intro.adoc[leveloffset=0] +include::topics/changes/changes.adoc[leveloffset=0] +include::topics/upgrading.adoc[leveloffset=0] diff --git a/docs/documentation/upgrading/topics/keycloak/changes-16_0_0.adoc b/docs/documentation/upgrading/topics/changes/changes-16_0_0.adoc similarity index 100% rename from docs/documentation/upgrading/topics/keycloak/changes-16_0_0.adoc rename to docs/documentation/upgrading/topics/changes/changes-16_0_0.adoc diff --git a/docs/documentation/upgrading/topics/keycloak/changes-17_0_0.adoc b/docs/documentation/upgrading/topics/changes/changes-17_0_0.adoc similarity index 100% rename from docs/documentation/upgrading/topics/keycloak/changes-17_0_0.adoc rename to docs/documentation/upgrading/topics/changes/changes-17_0_0.adoc diff --git a/docs/documentation/upgrading/topics/keycloak/changes-18_0_0.adoc b/docs/documentation/upgrading/topics/changes/changes-18_0_0.adoc similarity index 100% rename from docs/documentation/upgrading/topics/keycloak/changes-18_0_0.adoc rename to docs/documentation/upgrading/topics/changes/changes-18_0_0.adoc diff --git a/docs/documentation/upgrading/topics/keycloak/changes-19_0_0.adoc b/docs/documentation/upgrading/topics/changes/changes-19_0_0.adoc similarity index 100% rename from docs/documentation/upgrading/topics/keycloak/changes-19_0_0.adoc rename to docs/documentation/upgrading/topics/changes/changes-19_0_0.adoc diff --git a/docs/documentation/upgrading/topics/keycloak/changes-19_0_2.adoc b/docs/documentation/upgrading/topics/changes/changes-19_0_2.adoc similarity index 100% rename from docs/documentation/upgrading/topics/keycloak/changes-19_0_2.adoc rename to docs/documentation/upgrading/topics/changes/changes-19_0_2.adoc diff --git a/docs/documentation/upgrading/topics/keycloak/changes-20_0_0.adoc b/docs/documentation/upgrading/topics/changes/changes-20_0_0.adoc similarity index 100% rename from docs/documentation/upgrading/topics/keycloak/changes-20_0_0.adoc rename to docs/documentation/upgrading/topics/changes/changes-20_0_0.adoc diff --git a/docs/documentation/upgrading/topics/keycloak/changes-21_0_0.adoc b/docs/documentation/upgrading/topics/changes/changes-21_0_0.adoc similarity index 100% rename from docs/documentation/upgrading/topics/keycloak/changes-21_0_0.adoc rename to docs/documentation/upgrading/topics/changes/changes-21_0_0.adoc diff --git a/docs/documentation/upgrading/topics/keycloak/changes-21_0_2.adoc b/docs/documentation/upgrading/topics/changes/changes-21_0_2.adoc similarity index 100% rename from docs/documentation/upgrading/topics/keycloak/changes-21_0_2.adoc rename to docs/documentation/upgrading/topics/changes/changes-21_0_2.adoc diff --git a/docs/documentation/upgrading/topics/keycloak/changes-21_1_0.adoc b/docs/documentation/upgrading/topics/changes/changes-21_1_0.adoc similarity index 100% rename from docs/documentation/upgrading/topics/keycloak/changes-21_1_0.adoc rename to docs/documentation/upgrading/topics/changes/changes-21_1_0.adoc diff --git a/docs/documentation/upgrading/topics/keycloak/changes-22_0_0.adoc b/docs/documentation/upgrading/topics/changes/changes-22_0_0.adoc similarity index 100% rename from docs/documentation/upgrading/topics/keycloak/changes-22_0_0.adoc rename to docs/documentation/upgrading/topics/changes/changes-22_0_0.adoc diff --git a/docs/documentation/upgrading/topics/keycloak/changes-22_0_2.adoc b/docs/documentation/upgrading/topics/changes/changes-22_0_2.adoc similarity index 100% rename from docs/documentation/upgrading/topics/keycloak/changes-22_0_2.adoc rename to docs/documentation/upgrading/topics/changes/changes-22_0_2.adoc diff --git a/docs/documentation/upgrading/topics/keycloak/changes-22_0_4.adoc b/docs/documentation/upgrading/topics/changes/changes-22_0_4.adoc similarity index 100% rename from docs/documentation/upgrading/topics/keycloak/changes-22_0_4.adoc rename to docs/documentation/upgrading/topics/changes/changes-22_0_4.adoc diff --git a/docs/documentation/upgrading/topics/keycloak/changes-23_0_0.adoc b/docs/documentation/upgrading/topics/changes/changes-23_0_0.adoc similarity index 99% rename from docs/documentation/upgrading/topics/keycloak/changes-23_0_0.adoc rename to docs/documentation/upgrading/topics/changes/changes-23_0_0.adoc index 3981daa420..28b769345e 100644 --- a/docs/documentation/upgrading/topics/keycloak/changes-23_0_0.adoc +++ b/docs/documentation/upgrading/topics/changes/changes-23_0_0.adoc @@ -180,6 +180,7 @@ some user profile classes and some validator related classes (but not builtin va `keycloak-server-spi` module. However, the packages for java classes remain the same. You might be affected in some corner cases, such as when you are overriding the built-in implementation with your own `UserProfileProvider` implementation However, note that `UserProfileProvider` is an unsupported SPI. +ifeval::[{project_community}==true] = Removal of the Map Store The Map Store has been an experimental feature in previous releases. @@ -187,6 +188,7 @@ Starting with this release, it is removed and users should continue to use the c Since this release, it is no longer possible to use `--storage` related CLI options. The modules `keycloak-model-map*` have been removed. +endif::[] = Removed namespaces from our translations We moved all translations into one file for the admin-ui, if you have made your own translations or extended the admin ui you will need to migrate them to this new format. diff --git a/docs/documentation/upgrading/topics/keycloak/changes-23_0_2.adoc b/docs/documentation/upgrading/topics/changes/changes-23_0_2.adoc similarity index 100% rename from docs/documentation/upgrading/topics/keycloak/changes-23_0_2.adoc rename to docs/documentation/upgrading/topics/changes/changes-23_0_2.adoc diff --git a/docs/documentation/upgrading/topics/keycloak/changes-23_0_4.adoc b/docs/documentation/upgrading/topics/changes/changes-23_0_4.adoc similarity index 100% rename from docs/documentation/upgrading/topics/keycloak/changes-23_0_4.adoc rename to docs/documentation/upgrading/topics/changes/changes-23_0_4.adoc diff --git a/docs/documentation/upgrading/topics/keycloak/changes-23_0_5.adoc b/docs/documentation/upgrading/topics/changes/changes-23_0_5.adoc similarity index 100% rename from docs/documentation/upgrading/topics/keycloak/changes-23_0_5.adoc rename to docs/documentation/upgrading/topics/changes/changes-23_0_5.adoc diff --git a/docs/documentation/upgrading/topics/keycloak/changes-24_0_0.adoc b/docs/documentation/upgrading/topics/changes/changes-24_0_0.adoc similarity index 100% rename from docs/documentation/upgrading/topics/keycloak/changes-24_0_0.adoc rename to docs/documentation/upgrading/topics/changes/changes-24_0_0.adoc diff --git a/docs/documentation/upgrading/topics/keycloak/changes-25_0_0.adoc b/docs/documentation/upgrading/topics/changes/changes-25_0_0.adoc similarity index 100% rename from docs/documentation/upgrading/topics/keycloak/changes-25_0_0.adoc rename to docs/documentation/upgrading/topics/changes/changes-25_0_0.adoc diff --git a/docs/documentation/upgrading/topics/keycloak/changes.adoc b/docs/documentation/upgrading/topics/changes/changes.adoc similarity index 100% rename from docs/documentation/upgrading/topics/keycloak/changes.adoc rename to docs/documentation/upgrading/topics/changes/changes.adoc diff --git a/docs/documentation/upgrading/topics/download.adoc b/docs/documentation/upgrading/topics/download.adoc new file mode 100644 index 0000000000..0910855f22 --- /dev/null +++ b/docs/documentation/upgrading/topics/download.adoc @@ -0,0 +1,14 @@ +[[_install_new_version]] + +== Downloading the {project_name} server + +Once you have prepared for the upgrade, you can download the server. + +.Procedure + +. Download and extract {archivedownloadurl}[{archivebasename}-{project_version}.zip] +from the {project_name} website. ++ +After extracting this file, you should have a directory that is named `{archivebasename}-{project_version}`. +. Move this directory to the desired location. +. Copy `conf/`, `providers/` and `themes/` from the previous installation to the new installation. \ No newline at end of file diff --git a/docs/documentation/upgrading/topics/install_new_version.adoc b/docs/documentation/upgrading/topics/install_new_version.adoc deleted file mode 100644 index de249c8f41..0000000000 --- a/docs/documentation/upgrading/topics/install_new_version.adoc +++ /dev/null @@ -1,14 +0,0 @@ -[[_install_new_version]] - -== Upgrading the {project_name} server - -It is important that you upgrade {project_name} server before upgrading the adapters. - -.Prerequisites -* Handle any open transactions and delete the data/tx-object-store/ transaction directory. - -.Procedure -. Download the new server archive -. Move the downloaded archive to the desired location. -. Extract the archive. This step installs a clean instance of the latest {project_name} release. -. Copy `conf/`, `providers/` and `themes/` from the previous installation to the new installation. \ No newline at end of file diff --git a/docs/documentation/upgrading/topics/intro.adoc b/docs/documentation/upgrading/topics/intro.adoc new file mode 100644 index 0000000000..2daa2a91ae --- /dev/null +++ b/docs/documentation/upgrading/topics/intro.adoc @@ -0,0 +1,11 @@ +[[intro]] + +== Upgrading {project_name} + +This guide describes how to upgrade {project_name}. Use the following procedures in this order: + +. Review the migration changes from the previous version of {project_name}. +. Upgrade the {project_name} server. +. Upgrade the {project_name} adapters. +. Upgrade the {project_name} Admin Client. + diff --git a/docs/documentation/upgrading/topics/keycloak/intro.adoc b/docs/documentation/upgrading/topics/keycloak/intro.adoc deleted file mode 100644 index e620d62323..0000000000 --- a/docs/documentation/upgrading/topics/keycloak/intro.adoc +++ /dev/null @@ -1,9 +0,0 @@ -[[intro]] - -== Upgrading Keycloak - -This guide describes how to upgrade {project_name}. It is recommended that you start by upgrading the {project_name} -server first and {project_name} adapters second. - -Before upgrading make sure to read the instructions carefully and carefully review the changes listed in -<>. \ No newline at end of file diff --git a/docs/documentation/upgrading/topics/keycloak/upgrading.adoc b/docs/documentation/upgrading/topics/keycloak/upgrading.adoc deleted file mode 100644 index e839cab8cd..0000000000 --- a/docs/documentation/upgrading/topics/keycloak/upgrading.adoc +++ /dev/null @@ -1,15 +0,0 @@ -[[_upgrading]] - -== Upgrading the {project_name} server - -include::../prep_migration.adoc[leveloffset=1] - -include::../install_new_version.adoc[leveloffset=1] - -include::../migrate_db.adoc[leveloffset=1] - -include::../migrate_themes.adoc[leveloffset=1] - -include::../upgrade_adapters.adoc[leveloffset=1] - -include::../upgrade_admin_client.adoc[leveloffset=1] diff --git a/docs/documentation/upgrading/topics/migrate_db.adoc b/docs/documentation/upgrading/topics/migrate_db.adoc index f5e7f93f1f..4e65d2e6cb 100644 --- a/docs/documentation/upgrading/topics/migrate_db.adoc +++ b/docs/documentation/upgrading/topics/migrate_db.adoc @@ -1,21 +1,15 @@ [[_migrate_db]] -== Database migration +== Migrating the database {project_name} can automatically migrate the database schema, or you can choose to do it manually. By default the database is automatically migrated when you start the new installation for the first time. === Automatic relational database migration -To perform an automatic migration, start the server connected to the desired database. -If the database schema has changed for the new version of the server, it will be migrated. +To perform an automatic migration, start the server connected to the desired database. If the database schema has changed for the new server version, the migration starts automatically unless the database has too many records. -Creating an index on huge tables with millions of records can easily take a huge amount of time -and potentially cause major service disruption on upgrades. -For those cases, we added a threshold (the number of records) for automated index creation. -By default, this threshold is `300000` records. -When the number of records is higher than the threshold, the index is not created automatically, -and there will be a warning message in server logs including SQL commands which can be applied later manually. +For example, creating an index on tables with millions of records can be time-consuming and cause a major service disruption. Therefore, a threshold of `300000` records exists for automatic migration. If the number of records exceeds this threshold, the index is not created. Instead, you find a warning in the server logs with the SQL commands that you can apply manually. To change the threshold, set the `index-creation-threshold` property, value for the default `connections-liquibase` provider: @@ -34,7 +28,7 @@ default `connections-jpa` provider: kc.[sh|bat] start --spi-connections-jpa-quarkus-migration-strategy=manual ---- -When you start the server with this configuration it checks if the database needs to be migrated. +When you start the server with this configuration, the server checks if the database needs to be migrated. The required changes are written to the `bin/keycloak-database-update.sql` SQL file that you can review and manually run against the database. To change the path and name of the exported SQL file, set the `migration-export` property for the @@ -45,6 +39,6 @@ default `connections-jpa` provider: kc.[sh|bat] start --spi-connections-jpa-quarkus-migration-export=/ ---- -For further details on how to apply this file to the database, see the documentation for the relational database you're using. +For further details on how to apply this file to the database, see the documentation for your relational database. After the changes have been written to the file, the server exits. diff --git a/docs/documentation/upgrading/topics/migrate_themes.adoc b/docs/documentation/upgrading/topics/migrate_themes.adoc index 9126bfcfb1..869130cf83 100644 --- a/docs/documentation/upgrading/topics/migrate_themes.adoc +++ b/docs/documentation/upgrading/topics/migrate_themes.adoc @@ -1,80 +1,58 @@ [[_migrate_themes]] -== Theme migration +== Migrating themes -If you have created any custom themes they must be migrated to the new server. Any changes to the built-in themes might -need to be reflected in your custom themes, depending on which aspects you have customized. +If you created custom themes, those themes must be migrated to the new server. Also, any changes to the built-in themes might need to be reflected in your custom themes, depending on which aspects you customized. -You must copy your custom themes from the old server `themes` directory to the new server `themes` directory. -After that you need to review the changes below and consider if the changes need to be applied to your custom theme. +.Procedure -In summary: - -* If you have customized any of the changed templates listed below you need to compare the template from the base theme - to see if there are changes you need to apply. -* If you have customized any of the styles and are extending the {project_name} themes you need to review the changes to - the styles. If you are extending the base theme you can skip this step. -* If you have customized messages you might need to change the key or value or to add additional messages. - -ifeval::[{project_product}==true] -Each step is described in more detail below the list of changes. - -include::rhsso/migrate_themes-changes-73.adoc[leveloffset=0] -include::rhsso/migrate_themes-changes-72.adoc[leveloffset=0] -include::rhsso/migrate_themes-changes-71.adoc[leveloffset=0] -endif::[] +. Copy your custom themes from the old server `themes` directory to the new server `themes` directory. +. Use the following sections to migrate templates, messages, and styles. +* If you customized any of the updated templates listed in <>, compare the template from the base theme to check for any changes you need to apply. +* If you customized messages, you might need to change the key or value or to add additional messages. +* If you customized any styles and you are extending the {project_name} themes, review the changes to the styles. If you are extending the base theme, you can skip this step. === Migrating templates -If you have customized any of the templates you need to carefully review the changes that have been made to the templates -to decide if you need to apply these changes to your customized templates. Most likely you will need to apply the same -changes to your customized templates. If you have not customized any of the listed templates you can skip this section. +If you customized any template, review the new version to decide about updating your customized template. If you made minor changes, you could compare the updated template to your customized template. However, if you made many changes, consider comparing the new template to your customized template. This comparison will show you what changes you need to make. -A best practice is to use a diff tool to compare the templates to see what changes you might need to make to your -customized template. If you have only made minor changes it is simpler to compare the updated template to your -customized template. However, if you have made many changes it might be easier to compare the new template to your -customized old template, as this will show you what changes you need to make. +You can use a diff tool to compare the templates. The following screenshot compares the `info.ftl` template from the Login theme and an example custom theme: -The following screenshot compares the info.ftl template from the Login theme and an example custom theme: +.Updated version of a Login theme template versus a custom Login theme template +image:images/theme-migration-meld-info-1.png[Updated version of a Login theme template versus a custom Login theme template] -.Comparison of the updated version of a Login theme template with an example custom Login theme template -image:images/theme-migration-meld-info-1.png[] - -From this comparison it is easy to identify that the first change (`Hello world!!`) was a customization, while the +This comparison shows that the first change (`Hello world!!`) is a customization, while the second change (`if pageRedirectUri`) is a change to the base theme. By copying the second change to your custom template, you have successfully updated your customized template. -For the alternative approach the following screenshot compares the info.ftl template from the old installation with -the updated info.ftl template from the new installation: +In an alternative approach, the following screenshot compares the `info.ftl` template from the old installation with +the updated `info.ftl` template from the new installation: -.Comparison of the Login theme template from the old installation with the updated version of the Login theme template -image:images/theme-migration-meld-info-2.png[] +.Login theme template from the old installation versus the updated Login theme template +image:images/theme-migration-meld-info-2.png[Login theme template from the old installation versus the updated Login theme template] -From this comparison it is easy to identify what has been changed in the base template. You will then manually have to -make the same changes to your modified template. Since this approach is not as simple as the first approach, only use -this approach if the first one is not feasible. +This comparison shows what has been changed in the base template. You can then manually make the same changes to your modified template. Since this approach is more complex, use +this approach only if the first approach is not feasible. === Migrating messages -If you have added support for another language, you need to apply all the changes listed above. If you have not added -support for another language, you might not need to change anything; you only have to make changes if you have changed +If you added support for another language, you need to apply all the changes listed above. If you have not added +support for another language, you might not need to change anything. You need to make changes only if you have changed an affected message in your theme. -For added values, review the value of the message in the base theme to determine if you need to customize that message. +.Procedure -For renamed keys, rename the key in your custom theme. +. For added values, review the value of the message in the base theme to determine if you need to customize that message. -For changed values, check the value in the base theme to determine if you need to make changes to your custom theme. +. For renamed keys, rename the key in your custom theme. + +. For changed values, check the value in the base theme to determine if you need to make changes to your custom theme. === Migrating styles -If you are inheriting styles from the keycloak or rh-sso themes you might need to update your custom styles to reflect -changes made to the styles from the built-in themes. +You might need to update your custom styles to reflect changes made to the styles from the built-in themes. Consider using a diff tool to compare the changes to stylesheets between the old server installation and the new server installation. -A best practice is to use a diff tool to compare the changes to stylesheets between the old server installation and the -new server installation. - -For example, using the diff command: +For example: [source,bash,subs=+attributes] ---- @@ -83,4 +61,3 @@ $ diff {project_dirref}_OLD/themes/keycloak/login/resources/css/login.css \ ---- Review the changes and determine if they affect your custom styling. - diff --git a/docs/documentation/upgrading/topics/prep_migration.adoc b/docs/documentation/upgrading/topics/prep_migration.adoc index 1a5fefd8db..2a32389fc0 100644 --- a/docs/documentation/upgrading/topics/prep_migration.adoc +++ b/docs/documentation/upgrading/topics/prep_migration.adoc @@ -2,20 +2,18 @@ == Preparing for upgrading -Before you upgrade, be aware of the order in which you need to perform the upgrade steps. In particular, be sure to upgrade {project_name} server before you upgrade the adapters. +Perform the following steps before you upgrade the server. + +.Procedure +. Back up the old installation, such as configuration, themes, and so on. +. Handle any open transactions and delete the `data/tx-object-store/` transaction directory. + +. Back up the database using instructions in the documentation for your relational + database. ++ +The database will no longer be compatible with the old server after you upgrade the server. If you need to revert the upgrade, first restore the old installation, and then restore the database from the backup copy. [WARNING] ==== -In a minor upgrade of {project_name}, all user sessions are lost. After the upgrade, all users will have to log in again. +After upgrade of {project_name}, except for offline user sessions, user sessions are lost. Users will have to log in again. ==== - -.Procedure -. Back up the old installation (configuration, themes, and so on). -. Back up the database using instructions in the documentation for your relational - database. -. Upgrade the {project_name} server. -+ -The database will no longer be compatible with the old server after the upgrade. -. If you need to revert the upgrade, first restore the old installation, and then restore the database from the backup copy. -. Upgrade the adapters. - diff --git a/docs/documentation/upgrading/topics/upgrade_adapters.adoc b/docs/documentation/upgrading/topics/upgrade_adapters.adoc index 315799d451..7f7be9b09a 100644 --- a/docs/documentation/upgrading/topics/upgrade_adapters.adoc +++ b/docs/documentation/upgrading/topics/upgrade_adapters.adoc @@ -2,58 +2,30 @@ [[_upgrade_adapters]] -It is important that you upgrade {project_name} server first, and then upgrade the adapters. Earlier versions of the -adapter might work with later versions of {project_name} server, but earlier versions of {project_name} server might not +After you upgrade the {project_name} server, you can upgrade the adapters. Earlier versions of the +adapter might work with later versions of the {project_name} server, but earlier versions of the {project_name} server might not work with later versions of the adapter. [[_compatibility_with_older_adapters]] == Compatibility with older adapters -As mentioned above, we try to support newer release versions of {project_name} server working with older release versions of the adapters. -However, in some cases we need to include fixes on the {project_name} server side which may break compatibility with older versions -of the adapters. For example, when we implement new aspects of the OpenID Connect specification, which older client adapter versions -were not aware of. +Newer versions of the {project_name} server potentially work with older versions of the adapters. +However, some fixes of the {project_name} server may break compatibility with older versions +of the adapters. For example, a new implementation of the OpenID Connect specification may not match older client adapter versions. -In those cases, we added Compatibility modes. For OpenId Connect clients, there is a section named `OpenID Connect Compatibility Modes` -in the {project_name} admin console, on the page with client details. Here, you can disable some new aspects of the {project_name} server -to preserve compatibility with older client adapters. More details are available in the tool tips of individual switches. +For this situation, you can use Compatibility modes. For OpenID Connect clients, the Admin Console includes *OpenID Connect Compatibility Modes* on the page with client details. With this option, you can disable some new aspects of the {project_name} server +to preserve compatibility with older client adapters. For more details, see the tool tips of individual switches. [[_upgrade_eap_adapter]] == Upgrading the EAP adapter -ifeval::[{project_product}==true] - -.Procedure -If you originally installed the adapter using a downloaded archive, to upgrade the {appserver_name} adapter, perform the following procedure. - -. Download the new adapter archive. -. Remove the previous adapter modules by deleting the `{appserver_dirref}/modules/system/add-ons/keycloak/` directory. -. Unzip the downloaded archive into `{appserver_dirref}`. - -.Procedure -If you originally installed the adapter using RPM, to upgrade the adapter, complete the following steps, which are different depending on whether you are performing a minor or a micro upgrade: - -. For minor upgrades, use Yum to uninstall any adapters you currently have installed and then use Yum to install the new version of the adapters. -. For micro upgrades, use Yum to upgrade the adapter. This is the only step for micro upgrades. -+ -[source,bash,options="nowrap"] ----- -yum update ----- - -endif::[] - -ifeval::[{project_community}==true] - -.Procedure To upgrade the {appserver_name} adapter, complete the following steps: +.Procedure . Download the new adapter archive. . Remove the previous adapter modules by deleting the `{appserver_dirref}/modules/system/add-ons/keycloak/` directory. . Unzip the downloaded archive into `{appserver_dirref}`. -endif::[] - [[_upgrade_js_adapter]] == Upgrading the JavaScript adapter @@ -62,15 +34,15 @@ To upgrade a JavaScript adapter that has been copied to your web application, pe .Procedure . Download the new adapter archive. -. Overwrite the keycloak.js file in your application with the keycloak.js file from the downloaded archive. +. Overwrite the `keycloak.js` file in your application with the `keycloak.js` file from the downloaded archive. [[_upgrade_nodejs_adapter]] -== Upgrading the Node.js adapter +== Upgrading the `Node.js` adapter -To upgrade a Node.js adapter that has been copied to your web application, perform the following procedure. +To upgrade a `Node.js` adapter that has been copied to your web application, perform the following procedure. .Procedure . Download the new adapter archive. -. Remove the existing Node.js adapter directory +. Remove the existing `Node.js` adapter directory . Unzip the updated file into its place -. Change the dependency for keycloak-connect in the package.json of your application +. Change the dependency for keycloak-connect in the `package.json` of your application diff --git a/docs/documentation/upgrading/topics/upgrade_admin_client.adoc b/docs/documentation/upgrading/topics/upgrade_admin_client.adoc index 049e243b1d..86dd22aceb 100644 --- a/docs/documentation/upgrading/topics/upgrade_admin_client.adoc +++ b/docs/documentation/upgrading/topics/upgrade_admin_client.adoc @@ -2,7 +2,7 @@ [[_upgrade_admin_client]] -It is important that you upgrade the {project_name} server first, and then upgrade the admin-client. Earlier versions of the +Be sure that you upgrade the {project_name} server before you upgrade the admin-client. Earlier versions of the admin-client might work with later versions of {project_name} server, but earlier versions of {project_name} server might not -work with later versions of the admin-client. It is recommended to use the admin-client version that matches the used +work with later versions of the admin-client. Therefore, use the admin-client version that matches the current {project_name} server version. diff --git a/docs/documentation/upgrading/topics/upgrading.adoc b/docs/documentation/upgrading/topics/upgrading.adoc new file mode 100644 index 0000000000..324b980bbc --- /dev/null +++ b/docs/documentation/upgrading/topics/upgrading.adoc @@ -0,0 +1,17 @@ +[[_upgrading]] + +== Upgrading the {project_name} server + +You upgrade the server before you upgrade the adapters. + +include::prep_migration.adoc[leveloffset=1] + +include::download.adoc[leveloffset=1] + +include::migrate_db.adoc[leveloffset=1] + +include::migrate_themes.adoc[leveloffset=1] + +include::upgrade_adapters.adoc[leveloffset=1] + +include::upgrade_admin_client.adoc[leveloffset=1]