Updating Keycloak¶

Hint - version changes

The new Keycloak version comes with some important changes, see Changes

Updating from Version 15.0.0 and Later¶

... with Automatic Export and Import of the Configuration¶

Hint - internal data structure changes

Due to Keycloak-internal data structure changes the installation script proceeds as follows:

Export of the old Keycloak configuration (with timestamp and keycloak version).
Move the old configuration (*.install-bak).
Update Keycloak.
Reimport the exported configuration.

In a browser, log on to the SEAL Systems delivery platform with your logon data:

https://delivery.sealsystems.de

Hint - logon data

You receive the logon data from your Technical Project Manager at SEAL Systems.
Download the Keycloak - 23.0.0.66 - msi folder. It is saved as Keycloak - 23.0.0.66 - msi.zip.
Extract the .zip archive.

In a PowerShell (Administrator), change to the Keycloak - 23.0.0.66 - msi directory and start installing the package:

cd "Keycloak - 23.0.0.66 - msi"

Set-ExecutionPolicy Bypass -Scope Process -Force; .\install.ps1

The script executes the following steps:

1. Export the existing Keycloak configuration (using the command described in [configuration export](../configuration/config_export.md)) with the previous version (15 or 21) to the following directory:

    - Windows

        ```
        $env:ProgramData\SEAL Systems\data\seal-keycloak-export_from-version_<old_version>_<timestamp>.install-bak
        ```

    - Linux

        ```
        /opt/seal/data/seal-keycloak-export_from-version_<old_version>_<timestamp>.install-bak
        ```

    !!! example "Example - log message"

        - Windows

            ```
            Exporting settings from old version 21.0.1.40 to directory C:\ProgramData\SEAL Systems\data\seal-keycloak-export_from-version_21_20230925T133600977026309.install-bak...
            ...finished successfully.
            ```

        - Linux

            ```
            Exporting settings from old version 21.0.1 to directory /opt/seal/data/seal-keycloak-export_from-version_21_20230925_133600977026309.install-bak...
            ...finished successfully.
            ```

1. Stop the service.

1. Back up the content of the data directory:

    - Windows

        ```
        $env:ProgramData\SEAL Systems\data\seal-keycloak\` directory into `$env:ProgramData\SEAL Systems\data\seal-keycloak_<timestamp>.install-bak\
        ```

    - Linux

        ```
        /opt/seal/data/seal-keycloak/` directory to `/opt/seal/data/seal-keycloak_<timestamp>.install-bak/
        ```

    !!! example "Example - log message"

        - Windows

            ```
            Moving old data directory C:\ProgramData\SEAL Systems\data\seal-keycloak to C:\ProgramData\SEAL Systems\data\seal-keycloak_20230925T133600977026309.install-bak...
            ...finished successfully.
            ```

        - Linux

            ```
            Moving old data directory /opt/seal/data/seal-keycloak to /opt/seal/data/seal-keycloak_20230925_133600977026309.install-bak...
            ...finished successfully.
            ```

1. Import the old Keycloak configuration (using the command described in [configuration import](../configuration/config_import.md)).

    !!! example "Example - log message"

        - Windows

            ```
            Importing settings from old version 21.0.1.40 into new version 22.0.0.61 from directory C:\ProgramData\SEAL Systems\data\seal-keycloak-export_from-version_21_20230925T133600977026309.install-bak...
            ...finished successfully.
            ```

        - Linux

            ```
            Importing settings from old version 21.0.1 into new version 22.0.0 from directory /opt/seal/data/seal-keycloak-export_from-version_21_20230925_133600977026309.install-bak...
            ...finished successfully.
            ```

Hint - insufficient java version

If the Java Version is insufficient, the install.sh script stops the installation with an error. Keycloak 22.0 requires at least version 17, see requirements.

Open the required firewall ports:

Set-ExecutionPolicy Bypass -Scope Process -Force; .\firewall.ps1

Change to the common configuration directory:
```
cd C:\ProgramData\SEAL Systems\config
```
In an editor, compare the new keycloak.conf configuration file to the old keycloak.conf.install-bak configuration file.

Add your customer-specific changes, e. g. certificates.

For details on the general configuration, see Configuring the TLS Encryption.
Start the service:
```
start-service seal-keycloak
```
After the successful update, delete no longer required directories and files from the SEAL data directory:
- Windows
```
$env:ProgramData\SEAL Systems\data\
```
- Linux
```
/opt/seal/data/
```

... with Manual Export and Import of the Configuration¶

As of version 22.0 the installation script automatically performs the export and import of the configuration. If you prefer a manual update, you can proceed as described in the following instructions.

Hint - internal data structure changes

Due to Keycloak-internal data structure changes you have to proceed as follows:

Export the old Keycloak configuration.
Remove the old configuration.
Update Keycloak.
Reimport the exported configuration.

Export the existing Keycloak configuration with version 15 or 21.
In a browser, log on to the SEAL Systems delivery platform with your logon data:

https://delivery.sealsystems.de

Hint - logon data

You receive the logon data from your Technical Project Manager at SEAL Systems.
Download the Keycloak - 23.0.0.66 - msi folder. It is saved as Keycloak - 23.0.0.66 - msi.zip.
Extract the .zip archive.
Stop the service:
```
stop-service seal-keycloak
```
Remove the content of the $env:ProgramData\SEAL Systems\data\seal-keycloak\ directory:
```
Remove-Item "$env:ProgramData\SEAL Systems\data\seal-keycloak\*" -Force -Recurse
```
In a PowerShell (Administrator), change to the Keycloak - 23.0.0.66 - msi directory and start installing the package:
```
cd "Keycloak - 23.0.0.66 - msi"
```
```
Set-ExecutionPolicy Bypass -Scope Process -Force; .\install.ps1
```
Hint - insufficient java version

If the Java Version is insufficient, the install.sh script stops the installation with an error. Keycloak 22.0 requires at least version 17, see requirements.

Open the required firewall ports:

Set-ExecutionPolicy Bypass -Scope Process -Force; .\firewall.ps1

Start the service:
```
start-service seal-keycloak
```
Import the old Keycloak configuration into the new version.