Upgrade the IQ Server

Upgrading the IQ Server is replacing the server jar with the latest version and restarting the service. On startup, the server detects that it has been upgraded from the files in the sonatype-work directory and performs any changes. This often includes updates to the database and files on disk.

Note
Some upgrades will take longer before the server is available due to modifications made to the database. Allow for enough time for the process to complete before interrupting the service. Disable any process that may interrupt the server while the upgrade is happening to avoid corruption. In a Kubernetes environment, a liveness probe may attempt to restart the server container during the upgrade.

We strongly recommend taking a backup of your server installation and sonatype-work directories before attempting to upgrade. Rarely does an issue happen during sequential updates, however, updates spanning multiple versions may run into unforeseen issues.

Follow the instructions to Backup the IQ Server

Upgrade Instructions

Compact the Database Before the Upgrade

A long-lived database contains some percentage of empty space to support its efficient growth. If your server's database (sonatype-work/clm-server/data/ods.h2.db) is several gigabytes large, this percentage of empty space can amount to gigabytes as well. Removing this empty space, a process called compacting, can reduce the upgrade duration.

To compact your server's database:

1. Shut down your IQ Server

2. Execute the command java -jar nexus-iq-server-x.x.x-x.jar compact-db config.yml or equivalent for your environment. If you are using the Linux package with bundled JDK, use <iq-server-install-dir>/bin/java instead of java.

3. You may restart your IQ Server once the above command has finished

Compacting the database is an I/O heavy operation and, depending on the size of your database and the storage performance, can take several minutes or longer. To help plan the needed maintenance window, we suggest you perform a test run of this process in a staging environment on comparable hardware using a recent backup of your installation.

Download the latest version from Download and Compatibility

1. Update differences from your current config.yml file and use the new config.yml. Note any new default configuration settings in the new config.yml

2. Stop the server

3. Replace the old config.yml with the new config.yml file

4. Copy the new server jar and change the startup scripts to reflect the new jar name

5. Start the server

Java runtime considerations

For IQ Server 204 or later on Linux, the Sonatype IQ Server package with bundled JDK includes the Java executable in the bin directory. To use the bundled Java executable directly, run commands with <iq-server-install-dir>/bin/java instead of java.

If IQ Server connects to LDAPS or other TLS-protected services, verify that required certificates are available to the Java runtime used after the upgrade.

Review the release-specific upgrade instructions for your current version and any versions that follow.

Upgrading IQ Server Installed as a Windows Service

If your Sonatype IQ Server is installed and running as a Windows Service, additional steps are required when upgrading, especially when the upgrade also requires a new Java version.

The steps below assume that the IQ Server was installed as a Windows service using the Java Service Wrapper.

Before starting the upgrade, take a backup of both the IQ Server installation directory and the sonatype-work directory. Review the release-specific upgrade instructions for the target IQ Server version to understand any version-dependent requirements or changes.

Finally, confirm the required Java version for the target IQ Server release to determine whether a Java upgrade is necessary as part of the process.

Note
IQ Server versions earlier than 182 typically run on Java 8 or Java 11. IQ Server releases before the June 2026 release use Java 17. IQ Server 204 and later include a bundled Java 25 runtime. Deployments using a custom Java installation or Windows service wrapper configuration may require Java runtime updates during the upgrade.

1. Stop the IQ Server Service

Stop the Windows service using the Services Manager or from an elevated command prompt:

bin\clm stop

Confirm the service has fully stopped before continuing.

2. Install a New Java Version (When Required)

If the target IQ Server version requires a newer Java version:

1. Install the supported JDK.

2. Record the absolute path to the new java.exe.

Do not remove the existing Java installation until the upgrade is verified.

3. Update the Java Executable Used by the Service

Windows services do not automatically detect changes to JAVA_HOME.

When the Java version changes, explicitly configure the Java executable used by the service:

1. Edit:

   bin\jsw\conf\wrapper.conf

2. Locate:

   wrapper.java.command=java

3. Replace it with the absolute path to the new Java executable, using forward slashes.

   Example

   wrapper.java.command=C:/Program Files/Java/jdk-25/bin/java.exe

4. Review JVM Arguments

Some upgrades or Java version changes require updates to JVM arguments.

In wrapper.conf, review entries such as:

wrapper.java.additional.<n>

JVM flags or module access settings used with earlier Java versions may require adjustment for Java 25 compatibility.

5. Replace IQ Server Application Files

6. Download the target IQ Server version.

7. Replace the existing IQ Server .jar file in the service lib directory.

8. Ensure only one IQ Server .jar file exists in that directory.

9. For IQ Server release 205 and later, update the IQ Server application entry point in bin\jsw\conf\wrapper.conf:

   wrapper.app.parameter.1=com.sonatype.insight.brain.spring.InsightBrainSpringApplication
   wrapper.app.parameter.2=server
   wrapper.app.parameter.3=./conf/config.yml

5. Update config.yml:

• Compare with the new default configuration

  • Carry forward required customizations

  • Apply new default settings where applicable

6. Start the Service

Start the service using:

bin\clm start

Or through the Windows Services Manager.

Monitor the logs to confirm:

• Successful startup.
  • Completion of any database upgrade steps.

Note
Some upgrades perform database migrations and may take longer than usual. Do not interrupt the service during this process.

7. Verify the Upgrade

• Confirm the IQ Server UI is accessible.
  • Verify the reported IQ Server version.
  • Confirm policy evaluation and application data.
  • Restart the host to verify automatic service startup.

Upgrading a High Availability (HA) Installation of IQ Server

Refer to the following links for details on upgrading an HA installation:

https://github.com/sonatype/nexus-iq-server-ha/tree/main/chart#upgrading

https://artifacthub.io/packages/helm/sonatype/nexus-iq-server-ha#upgrading