157 lines
5.7 KiB
Text
157 lines
5.7 KiB
Text
[[_install_new_version]]
|
|
|
|
== Upgrading the {project_name} server
|
|
|
|
Follow these guidelines to be sure the server upgrade is successful:
|
|
|
|
* Test the upgrade in a non-production environment first to prevent any installation issues in production,
|
|
* Upgrade the {project_name} server before upgrading the adapters. Also ensure the upgraded server is functional in production before upgrading adapters.
|
|
|
|
[WARNING]
|
|
====
|
|
This upgrade procedure may require modification due to manual changes that are specific to your installation. For details on manual changes that might affect the upgrade, see xref:release_changes[Release-specific changes].
|
|
====
|
|
|
|
ifeval::[{project_product}==true]
|
|
Upgrade the server from a xref:upgrade-zip[ZIP file] or an xref:rpm-upgrade[RPM] based on the method you had used for installation.
|
|
|
|
[id="upgrade-zip"]
|
|
=== Upgrading the server from a ZIP file
|
|
endif::[]
|
|
|
|
.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.
|
|
. For standalone installations, copy the `{project_dirref}/standalone/` directory from the previous installation over the
|
|
directory in the new installation.
|
|
+
|
|
For domain installations, copy the `{project_dirref}/domain/` directory from the previous installation over the directory
|
|
in the new installation.
|
|
+
|
|
For domain installations, create the empty directory `{project_dirref}/domain/deployments`.
|
|
+
|
|
NOTE:
|
|
Files in the bin directory should not be overwritten by the files from previous versions. Changes should be made manually.
|
|
|
|
. Copy any custom modules that have been added to the modules directory.
|
|
. Continue with the section, xref:upgrade-script[Running the server upgrade script].
|
|
|
|
ifeval::[{project_product}==true]
|
|
|
|
[id="rpm-upgrade"]
|
|
=== Upgrading the server from an RPM
|
|
|
|
.Prerequisites
|
|
* Handle any open transactions and delete the /var/opt/rh/rh-sso7/lib/keycloak/standalone/data/tx-object-store/ transaction directory.
|
|
|
|
.Procedure
|
|
|
|
. Subscribe to the proper repository containing {project_name}.
|
|
+
|
|
For Red Hat Enterprise Linux 7:
|
|
+
|
|
subscription-manager repos --enable=rh-sso-7.6-for-rhel-7-x86_64-rpms
|
|
+
|
|
For Red Hat Enterprise Linux 8:
|
|
+
|
|
subscription-manager repos --enable=rh-sso-7.6-for-rhel-8-x86_64-rpms
|
|
+
|
|
|
|
. Disable the older product repository for {project_name}:
|
|
|
|
subscription-manager repos --disable=rh-sso-7.5-for-rhel-8-x86_64-rpms
|
|
|
|
. Check the list of repositories:
|
|
|
|
dnf repolist
|
|
|
|
Updating Subscription Management repositories.
|
|
repo id repo name
|
|
rh-sso-7.6-for-rhel-8-x86_64-rpms Single Sign-On 7.6 for RHEL 8 x86_64 (RPMs)
|
|
rhel-8-for-x86_64-appstream-rpms Red Hat Enterprise Linux 8 for x86_64 - AppStream (RPMs)
|
|
rhel-8-for-x86_64-baseos-rpms Red Hat Enterprise Linux 8 for x86_64 - BaseOS (RPMs)
|
|
|
|
. Back up any modified configuration files and custom modules.
|
|
|
|
. Use `dnf upgrade` to upgrade to the new Red Hat Single Sign-On version.
|
|
+
|
|
The RPM upgrade process does not replace any modified configuration files. Instead, this process creates .rpmnew files for the default configuration of the new Red Hat Single Sign-On version.
|
|
|
|
. To activate any new features in the new release, such as new subsystems, manually merge each .rpmnew file into your existing configuration files.
|
|
|
|
. Copy any custom modules that have been added to the modules directory.
|
|
|
|
. Continue with the section, xref:upgrade-script[Running the server upgrade script].
|
|
+
|
|
[NOTE]
|
|
====
|
|
{project_name} RPM server distribution is using
|
|
|
|
`{project_dirref}=/opt/rh/rh-sso7/root/usr/share/keycloak`
|
|
|
|
Use it when calling migration scripts below.
|
|
====
|
|
|
|
endif::[]
|
|
|
|
[id="upgrade-script"]
|
|
== Running the server upgrade script
|
|
|
|
Based on your previous installation, run the appropriate upgrade script that applies to your situation:
|
|
|
|
* xref:standalone-mode[Standalone mode]
|
|
* xref:standalone-ha[Standalone high availability mode]
|
|
* xref:domain-mode[Domain mode]
|
|
* xref:domain-clustered[Domain-clustered mode]
|
|
|
|
[id="standalone-mode"]
|
|
=== Running the Standalone Mode upgrade script
|
|
|
|
.Procedure
|
|
|
|
. If you are using a different configuration file than the default one, edit the migration script to specify the new file name.
|
|
. Stop the server.
|
|
. Run the upgrade script:
|
|
|
|
bin/jboss-cli.sh --file=bin/migrate-standalone.cli
|
|
|
|
[id="standalone-ha"]
|
|
=== Running the Standalone-High Availability Mode upgrade script
|
|
For standalone-high availability (HA) mode, all instances must be upgraded at the same time.
|
|
|
|
.Procedure
|
|
. If you are using a different configuration file than the default one, edit the migration script to specify the new file name.
|
|
. Stop the server.
|
|
. Run the upgrade script:
|
|
|
|
bin/jboss-cli.sh --file=bin/migrate-standalone-ha.cli
|
|
|
|
[id="domain-mode"]
|
|
=== Running the Domain Mode upgrade script
|
|
For domain mode, all instances must be upgraded at the same time.
|
|
|
|
.Procedure
|
|
|
|
. If you have changed the profile name, you must edit the upgrade script to change a variable near the beginning of the script.
|
|
. Edit the domain script to include the location of the keycloak-server.json file.
|
|
. Stop the server.
|
|
. Run the upgrade script on the domain controller
|
|
|
|
bin/jboss-cli.sh --file=bin/migrate-domain.cli
|
|
|
|
[id="domain-clustered"]
|
|
=== Running the Domain-clustered Mode upgrade script
|
|
For domain-clustered mode, all instances must be upgraded at the same time.
|
|
|
|
.Procedure
|
|
|
|
. If you have changed the profile name, you must edit the upgrade script to change a variable near the beginning of the script.
|
|
. Edit the domain-clustered script to include the location of the keycloak-server.json file.
|
|
. Stop the server.
|
|
. Run the upgrade script on the domain controller only:
|
|
|
|
bin/jboss-cli.sh --file=bin/migrate-domain-clustered.cli
|