Upgrading

Important: each new version of the Olvid Plugin imposes a minimal version for the iOS, Android and Desktop clients. Before updating, please make sure all your users will have the ability to update to the latest version of Olvid.

This short guide describes the main steps to follow when upgrading Keycloak and the Olvid Plugin. The official Keycloak upgrading guide is available here:

https://www.keycloak.org/docs/latest/upgrading/

Here are the recommended steps when upgrading Keycloak and Olvid.

Version specific steps

• If upgrading the Olvid Plugin from a version lower than 3.1.0, first check the themes configured for your different realms. This can be accessed from the Keycloak Console, in the Realm settings section, in the Themes tab. For all realms, make sure the base theme is not selected for any Login theme. If unsure, use the olvid theme for Login or leave them on Select a theme. Also, if your server requires a proxy for outgoing connections, make sure to update the syntax in the run-keycloak.sh script by removing double quotes (see the updated documentation)
• If upgrading the Olvid Plugin from a version lower than 4.0.0, first check that Java 21 is installed on the server as the latest version of Keycloak require it. Otherwise, update your installed version of Java before proceeding with the update. Older versions of Keycloak should be able to run on Java 21 without any problem.
  • the old --proxy=edge option is no longer supported and proxy behaviour depends on the headers sent by the reverse-proxy. Be sure to include all the X-Forwarded... headers specified in the configuration documentation.
• If upgrading the Olvid Plugin from a version lower than 4.1, please be aware that the hostname management has changed. Our run-keycloak.sh script specifies a --hostname-strict=false option so that Keycloak accepts connections using any hostname. This is not a problem if running Keycloak behind a proxy, but if Keycloak is exposed directly, this option should be replaced by the effective hostname used for the server (see the official documentation).

Standard upgrade steps

1. Backup your keycloak database: whenever you launch a newer version of Keycloak or of the Olvid Plugin, it will run a migration process on the database. This migration cannot be undone easily, so if for any reason your upgrade fails, and you want to restart your current Keycloak version, you will need to restore a pre-migration snapshot of the database.
2. Prepare an independent installation of Keycloak: rather than overwriting any current Keycloak files, we recommend using a completely different install, either on the same server in a different folder, or on a new server. If using a new server, make sure it has the same internet access as the current one and remember that the reverse proxy configuration will need to be updated. Here, we suppose you use a different folder on the same server:
   1. Create a new install folder next to the current one
   2. Unpack the latest Olvid Plugin bundle in this new folder (as in the standard installation guide)
   3. Copy your current configuration file to the new installation folder. This file is located in conf/keycloak.conf for Keycloak. This will copy the database url and credentials required to connect to your current database.
   4. If you customized the 1.olvid_scripts/run-keycloak.sh script, you will need to apply the same customizations to the run-keycloak.sh script in the new installation. If your server needs to go through a proxy to communicate with the Olvid server, you probably added some options to this file.
   5. Similarly, if you customized the conf/quarkus.properties file (typically to change some HTTP security headers of the Olvid console), copy this file to the new installation folder.
3. Stop the current Keycloak instance and make sure there is no Keycloak process running on the server:

   > systemctl stop keycloak
   > ps -ef | grep keycloak
   

   Keep in mind that while the Keycloak server is stopped, your employees can still use Olvid normally. They only lose the capacity to add new contacts using the directory. So it is usually not a problem to stop the server for a few minutes.

4. Manually start the new Keycloak instance: contrary to the first launch described in the installation guide, no need to set the first admin username and password, they are already set in the database. You can simply run 1.olvid_scripts/run-keycloak.sh inside the new folder. Have a look at the standard output and check for errors

   This will run the database migration step, so from this point, any attempt to return to your old Keycloak instance will require to restore your database snapshot.

5. Test connectivity with the new instance: using a phone with Olvid installed and bound to Keycloak, open the user directory and make sure the search if functional. If everything works, you can kill the manually started Keycloak instance (a Ctrl+C should work).
6. Update the keycloak.service systemd service: if you created the keycloak.service as in the installation guide you simply need to update the ExecStart line to reference the new folder.
7. Start the updated Keycloak instance by reloading all unit files and restarting the keycloak service

   > systemctl daemon-reload
   > systemctl start keycloak
   

That’s it, the update is done! Once you are sure everything is working as expected, you can clean up your old install by deleting the old installation folder.