[[_install_new_version]]

== Upgrading the {project_name} server

[WARNING]
====
The steps covered in this section are the default upgrade procedure, and may not always be possible due to manual changes required to the configuration guide.

Please refer to the migration changes for details on the version you are upgrading to.
====

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.
. 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.
. Run the applicable upgrade script below.

[id="upgrade-script"]
== Run the server upgrade script

Based on your previous installation, run the appropriate upgrade script that applies to your situation:

ifeval::[{project_product}==true]
* xref:rpm-upgrade[RPM distribution]
endif::[]
* xref:standalone-mode[Standalone mode]
* xref:standalone-ha[Standalone high availability mode]
* xref:domain-mode[Domain mode]
* xref:domain-clustered[Domain-clustered mode]

ifeval::[{project_product}==true]

[id="rpm-upgrade"]
=== Run the RPM distribution script

.Prerequisites
* Handle any open transactions and delete the /var/opt/rh/rh-sso7/lib/keycloak/standalone/data/tx-object-store/ transaction directory.

.Procedure

. Make sure you have subscribed to the proper repositories containing JBOSS EAP and {project_name}.
+
For Red Hat Enterprise Linux 7:
+
 subscription-manager repos --enable=rh-sso-7.5-for-rhel-7-x86_64-rpms
+
For Red Hat Enterprise Linux 8:
+
 subscription-manager repos --enable=rh-sso-7.5-for-rhel-8-x86_64-rpms
+
[NOTE]
====
To disable older product repositories for both JBOSS EAP and {project_name} use:

 subscription-manager repos --disable=<OLDER_PRODUCT_REPO>

To check the repositories use:

 yum repolist
====
. The RPM upgrade process will not replace any of your modified configuration files, and will instead create .rpmnew files for the default configuration of the new {project_name} version.
+
To activate any new features in the new release, such as new subsystems, you must manually merge each .rpmnew file into your existing configuration files
+
. Copy any custom modules that have been added to the modules directory.
. Run the applicable upgrade script as described below.
+
[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="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