Upgrade icom Router Management 2026.05.0

If you are coming from a binary installation of iRM you need to migrate to Docker first! Please see the migration guide.

This guide will aid you in upgrading your running iRM-Docker install to a newer version. The upgrade process encompasses placing the new application images into their respective places and replacing all script files that may have changed between versions. A short downtime of the system is to be expected.
The new Version also brings improvements for the authentication process, that protect the application better from unauthorized access, namely OAuth2 with OIDC. In order for OIDC to work, some changes regarding domains and certificates are needed. The former login flow is still usable, but usage is not recommended.

Preparation

1. Network

For systems running in https or https-mtls mode, some prerequisites need to be met, in order to use the new login flow.

Domains

Systems that can be accessed through a domain (e.g. irm.mycompany.com) now need an additional domain, that leads to the same IP address. The following setup is needed:

Domain 1 (existing): irm.mycompany.com
Domain 2 (new): auth.irm.mycompany.com

Both domains route to the same place, which is your application server. The reverse proxy (traefik) will internally route the requests to their respective place.

Certificates

Because of the changes for the domains, the existing certificates need to be modified or reissued. As two domains now point to your application server, both domains need to be present in the certificate. Otherwise connections to the application server will get certificate errors. For this use-case the SAN (Subject Alternative Name) field of the certificate is used. This field allows to add multiple known domains to the certificate, allowing the certificate to be used for both domains.

In order to add the new domain to the certificate, please contact the instance providing your certificates, or refer to the documentation of the used product.

2. Application

Make sure the files for the new version (insys-irm-2026_05_0.tar.gz) are uploaded onto the virtual machine (VM) (e.g. using scp or sftp) and are extracted in a place of your choice.

tar -xzf insys-irm-2026_05_0.tar.gz

Navigate to the installation path. (default: /opt/insys-irm)

cd <PATH/TO/INSYS-IRM>

Upgrade-Process

1. Backup the old images

Move the old images into a new directory, the installation will not use these images anymore.

# if not existent make dir 
mkdir images/old_images 

# move old images 
mv images/* images/old_images/

2. Copy the new images to installation directory

Copy the images to the directory in order to supply them for the application. Ensure only the updated images are present in this folder.

cp <PATH/TO/NEW/FILES>/images/* images/

3. Stop iRM

./stop.sh

4. Replace start.sh and stop.sh

Replace the start and stop script in order to update the setup and teardown of the application.

rm start.sh stop.sh 
cp <PATH/TO/NEW/FILES>/start.sh . 
cp <PATH/TO/NEW/FILES>/stop.sh .

5. Replace docker-compose files

Replace the compose files in order to get all changes regarding application composition and configuration.

rm docker-compose*.yaml 
cp <PATH/TO/NEW/FILES>/docker-compose*.yaml .

6. Ensure ownership for new files

Ensure ownership of the current directory to not run into permission issues when starting or configuring the application.

sudo chown -R <USER>:<GROUP> .

7. Set the hydra secret

Set a new secret for hydra, in order to not take the default one. A secret can be generated with the following command:

openssl rand -base64 32

Afterwards edit the .env file:

sudo vim .env

And add the generated value:

ORY_HYDRA_SECRET=<your_secret>

8. Start iRM

Start the application and follow the follow the instructions.

./start.sh

1. Update the Certificates

Replace the old certificates with the new certificates in the certsfolder.

2. Set the authentication mode

Log into the application, change into the system account by clicking on the button ‘Change Account’ in the app bar and go to System Administration → System settings. Change the value of CLIENT_CONFIGURATION_AUTH_MODE to OAUTH2.

Verification

Ensure that your application is reachable again. Log in with your credentials and check the System-Administration → System-Information page for the new version string ‘2026.05.0’ .

Documentation Index