# 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](https://help.sonatype.com/en/backing-up-the-iq-server.html "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 `/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](https://help.sonatype.com/en/download-and-compatibility.html "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](https://help.sonatype.com/en/run-iq-server-as-a-service.html "Run IQ Server as a Service") 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 `/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](https://help.sonatype.com/en/release-specific-upgrade-instructions.html "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](https://help.sonatype.com/en/release-specific-upgrade-instructions.html#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. ``` JVM flags or module access settings used with earlier Java versions may require adjustment for Java 25 compatibility. 5. Replace IQ Server Application Files 1. Download the target IQ Server version. 2. Replace the existing IQ Server `.jar` file in the service lib directory. 3. Ensure only one IQ Server `.jar` file exists in that directory. 4. 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://github.com/sonatype/nexus-iq-server-ha/tree/main/chart#upgrading) [https://artifacthub.io/packages/helm/sonatype/nexus-iq-server-ha#upgrading](https://artifacthub.io/packages/helm/sonatype/nexus-iq-server-ha#upgrading)