[[_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