2.1.2 quilliup Upgrade Guide (Windows) – Version 2.8.1 – How can we help?

1. Prerequisites:

Java 11 and Apache Tomcat 9 must be installed before the upgrade.
Ensure that Tomcat 9 has the same access privileges as the previously used Tomcat 8.
Follow the official manuals to install:

(1) How to install Java
(2) How to install Tomcat

⚠️ Note: Quilliup v2.8.1 requires Java 11 and Tomcat 9.

2. Configure Java Environment Variables & Memory:

1. stop the Quilliup service (via Task Manager).
2. Delete all logs from ..\quilliup\logs
3. Delete the Catalina folder from ..\quilliup\work
4. Update environment variables:
  (a) Access System Environment Variables.
  (b) Set JAVA_HOME in both User and System variables to point to Java 11.
  
  (c) Remove any JRE_HOME entries.
  
  (d) Update the Path variable to reflect the Java 11 installation.
5. Update memory configuration:
  (a) Open : C:\Program Files\quilliup\bin
  
  (b) Edit service.bat:
  
  - Search for the following parameters (given memory values are just an example):
```
if "%JvmMs%" == "" set JvmMs=16384 --minmin_value
if "%JvmMx%" == "" set JvmMx=20480 -- maximum_value
```
  - Remove the parameter -Dlog4j2.formatMsgNoLookups=true.
  - If -Dnet.sf.ehcache.disabled=true exists in the old files, add it to the new one.
  
  (c) Edit catalina.bat:
  
  - Search for the next line: set JAVA_OPTS=-Xms minimum_value m -Xmx maximum_value m -XX:PermSize=512m
  - Remove the parameter -Dlog4j2.formatMsgNoLookups=true from the next row.
  - Search for the next line: --JvmOptions "-Dcatalina.home=%CATALINA_HOME%;
  if -Dnet.sf.ehcache.disabled=true exists in the old files, add it to the new one.
  - If the parameter %JvmArgs% appears in that line, move it to the end of the line:
```
--JvmOptions

"-Dcatalina.home=%CATALINA_HOME%;-Dcatalina.base=%CATALINA_BASE%;-Dja

va.endorsed.dirs=%CATALINA_HOME%\endorsed;-Djava.io.tmpdir=%CATALINA_BA

SE%\temp;-Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager;-Dja

va.util.logging.config.file=%CATALINA_BASE%\conf\logging.properties;-XX:MaxPerm

Size=512m;-XX:PermSize=512m;-XX:+CMSClassUnloadingEnabled;-XX:+CMSPerm

GenSweepingEnabled;%JvmArgs%" ^
```
  Note: all the parameter values must match the server's RAM memory value!
  
  Note: in order to complete the memory change process, you have to re-create quilliup's service.

3. Re-create quilliup service:

Note: Before making the upcoming steps, ensure that you have the account name and

password for the User that runs quilliup service.

Open CMD as Administrator.
Navigate to: cd /d ..\quilliup\bin
Delete the existing service: sc delete quilliup (where quilliup is the service name)
Confirm deletion in Services. If disabled, restart the server.
If the service is marked as disabled, restart the server.

4. After JAVA and memory parameters were modified, re-create the Apache Tomcat service:

Open CMD as Administrator
Re-install the service: service.bat install quilliup
Open the Services and refresh the list to make sure the quilliup service was created.
Define the user that runs quilliup service.

Services -> Apache Tomcat 9 quilliup -> Properties, in the Log On tab:
Start the service.
Go to..\quilliup\logs folder and open catalina file. make sure that the log rows are updated with the new Java version and the marked memory is correct:

5. Deploy New WAR File

Download the installation file: https://storage.googleapis.com/quilliup_bucket/quilliup_tomcat9_2.8.1_client.war
Stop the Quilliup service.
Backup the current ROOT folder in another location:

..\quilliup\webapps\ROOT → ROOT_backup_<version>

⚠️ Use the Tomcat 8 ROOT folder as the backup.
Delete:
- All log files (..\quilliup\logs)
- The ..\quilliup\work\Catalina folder
- ROOT folder and ROOT.war file from ..\quilliup\webapps
Copy the new WAR file into ..\quilliup\webapps and rename it ROOT.war

⚠️ Ensure file extension is .war (not .zip) & ROOT in uppercase

Note: When upgrading from version 2.7.2 or earlier to version 2.8.0 or later, use the ROOT folder from Tomcat 8 as the backup folder.
Ensure you check the location of the AppData folder - if it resides in the Tomcat 8 directory, move/ copy it to the new Tomcat folder.
Finally, after completing the upgrade, remember to update the "Test Result Location" in the Administration module (Administration → General Settings → System Properties).

First, we will run quilliup in applicative & http mode. If everything functions correctly, we will proceed to configure HTTPS or AD as needed.

5. Repository Configurations

Stop the service, clear logs, and delete Catalina again.
Open in edit mode (for example, in Notepad++) and update:
- connection.properties – Copy repository settings from backup.
- config.properties – Manually compare and transfer values
  
  Don't overwrite the new config.properties file, which can contain new/additional parameters in comparison with the old config.properties file.
  
  At this point, you will have to MANUALLY compare & replace the parameter's values with the values for the same parameters from config.properties backup file.

6. Cache Handling

If the user utilizes the Whoami cache and has upgraded to version 2.8.1 or higher, please delete all the *.json files are located in the folder ..\quilliup\permCacheFiles before starting the service.

Enter the permCacheFiles folder and delete all the *.json files:

For more information about these steps, please refer to the manual.

Note: If you upgrade from a version before 2.8.0, you would have to create a new folder named ‘permCacheFiles’ in the new quilliup folder.

7. Database Adjustments

>> If you are upgrading from version 2.7.2 or earlier to version 2.8.0 or later with a MySQL DB Repository, please follow these instructions:

Execute the following query in DB Repository level:

SELECT MAX(max_id) AS max_id_across_tables
FROM (
    SELECT MAX(id) AS max_id FROM authorities
    UNION ALL
    SELECT MAX(id) AS max_id FROM deleteJobExecution
    UNION ALL
    SELECT MAX(id) AS max_id FROM kpitestindicator
    UNION ALL
    SELECT MAX(id) AS max_id FROM logins
    UNION ALL
    SELECT MAX(id) AS max_id FROM objectattributes
) AS all_max_ids;

Take the value returned by the query, increase it by 1, and update the "hibernate_sequence" table with this new value.

update hibernate_sequence
set next_val = (RETURNED_VALUE+1)

>> If you are upgrading from a version 2.7.2 or earlier to version 2.8.0 or later with a MSSQL DB Repository, ensure that:

There is a table named 'datasource'
If not, change the name from 'DataSource' to 'datasource' using this query:
EXEC sp_rename 'DataSource', 'datasource';
There is a column 'getTablesUpper' in the 'datasource' table
If not, add the column to the table using this query:
ALTER TABLE datasource ADD getTablesUpper BIT NULL;
There is a table named 'GROUPS'
If not, change the name from 'groups' to 'GROUPS' using this query:
EXEC sp_rename 'groups', 'GROUPS';
There is a column 'enabled' in the 'GROUPS' table
If not, add the column to the table using this query:
ALTER TABLE GROUPS ADD enabled BIT NULL;

>> If you're using MSSQL as the repository and the JDBC connection string in your connection.properties file contains the parameter IntegratedSecurity:

Run command java -version in order to ensure if Java 64 or 32 version is used.
If output contains, for example, ... 64-Bit Server ... => you need "../auth/x64/mssql-jdbc_auth-9.4.1.x64.dll", otherwise you need "../auth/x86/mssql-jdbc_auth-9.4.1.x86.dll"
Download JDBC jar from https://learn.microsoft.com/en-us/sql/connect/jdbc/release-notes-for-the-jdbc-driver?view=sql-server-ver15#94
- unzip it
- access "..\sqljdbc_9.4.1.0_enu\sqljdbc_9.4enu\auth" folder, access "x64" folder or "x86" in accordance to previously implemented "java -version" command
Copy "mssql-jdbc_auth-9.4.1.x86.dll" to "../quilliup/bin" folder

Note: this change requires service restart.

7. Start Service

Go to Windows Services and start the Apache Tomcat quilliup service
Ensure Startup Type is Automatic.
Verify UI access in browser.
If errors occur, review logs and contact Support.

If everything is functioning properly, proceed to configure HTTPS or AD as required

Repeat the following steps once again:
- Stop Tomcat service.
- Delete all log files.
- Delete the ‘Catalina’ folder.

1. Active Directory (AD) mode:

Open the ROOT backup folder.
Navigate to: quilliup\webapps\ROOT\WEB-INF
Copy the file: example_ntlm.prp from the backup folder into the same path in the new ROOT folder, replacing the existing file.
Open the file web.xml in both the backup and the new ROOT folder under: quilliup\webapps\ROOT\WEB-INF
Manually edit the new web.xml file so that its AD configuration matches the backup version.

In case the user working with Kerberos as an AD connection:

Navigate to: quilliup\webapps\ROOT\WEB-INF
Copy login.conf from the backup into this folder, replacing the existing file.
Navigate to the quilliup root directory:
Copy krb5.ini from the backup into this folder, replacing the existing file.
Copy the Kerberos keytab file (*.keytab) from the backup into this folder, replacing the existing file.

After replacing the relevant files for Kerberos SPNEGO configuration, please refer to the appropriate manual to ensure everything is configured correctly, especially verifying all the path parameters connecting these files.

2. HTTPS mode:

Navigate to: ..\quilliup\webapps\ROOT\WEB-INF\classes\spring
Locate the file: security-config.xml
Compare the file in the new ROOT folder against the version in the ROOT backup folder.
Update the parameters in the new file to match the configuration from the backup.

⚠️ Note: This file contains Quilliup’s HTTPS settings.
Please refer to the official HTTPS manual to ensure all parameters are correctly set.

When finished setting up HTTPS / AD / both, check that quilliup’s UI is available.

3. Update Cache Parameter in UI

Adjust the cache.perm parameter in the Quilliup UI so that it matches the cache parameter from the config.properties file.
Path in UI: Module Administration → System Settings → System Properties

4. Update Test Results Location

Update the test results location in the Quilliup UI to point to the new AppData folder inside the upgraded Quilliup installation.
Path in UI: Administration → System Admin → System Settings → General Settings → System Properties
Use related manual

If you have any questions, please contact the support team!

Related articles