2.2.2 quilliup upgrade user guide (Linux)

Welcome to the quilliup upgrade tutorial for the Linux server.

This guide provides an introduction to the quilliup upgrade process for the latest available version, 2.8.1.

Prerequisites:

a. Make sure you followed all the steps in the pre-steps manual before starting the upgrade process:

quilliup pre-steps version upgrade (Linux)

b. Make sure to back up the current "ROOT" folder before starting the upgrade process:

cd /opt/tomcat/webapps

Follow the next steps:

1. Go to the bin folder:

cd /opt/tomcat/bin

2. Check quilliup's service status:

ps -ef | grep tomcat

or

sudo systemctl status tomcat

3. Stop quilliup's (service):

sudo kill -9 XXXX

or

sudo systemctl stop tomcat

For example, XXXX= 785 (near the tomcat):

Note: when quilliup's service is down, you will see the following output:


Make sure that the service is down:

ps -ef | grep tomcat

or

sudo systemctl status tomcat

4. Delete log files:

Go to the quilliup logs folder:

cd /opt/tomcat/logs/

Delete the contents of the folder:

Note: make sure that you are inside the logs folder!

rm -rf *

Run the ls command to confirm the deletion.

5. Delete the Catalina folder (under the work folder):

Go to the work folder:

cd /opt/tomcat/work/ 

Delete the contents of the folder:

Note: make sure that you are inside the work folder!

rm -rf *

Run the ls command to confirm the deletion.

6. If you didn't backup ROOT, copy the current ROOT folder into a backup folder:

Create a backup folder by using the "mkdir name_of_the_file" command. 

sudo cp -R /opt/tomcat/webapps/ROOT /opt/backup_folder_name

7. Delete the ROOT folder: 

sudo rm -rf ROOT/

8. Delete the ROOT.war file: 

sudo rm -rf ROOT.war/

9. Insert the new *.war file you got from the support team into your current path (/opt/tomcat/webapps/) and rename it to “ROOT.war”.

10. Provide permission to the new ROOT.war file (if needed):

Go to the webapps folder:

cd /opt/tomcat/webapps

Check if the new ROOT.war file has permissions by running the ls command.

If it is colored with the color red (same as the picture)- you need to provide permission:

chmod 777 ROOT.war

If it is colored green- the new ROOT.war file has permissions.

11. Start quilliup (service):

Go to the bin folder:

cd /opt/tomcat/bin

Start quilliup service:

sudo ./catalina.sh start

or 

sudo systemctl start tomcat

Check that the service is up (run the comment inside the bin folder):

ps -ef | grep tomcat

or

sudo systemctl status tomcat

If the ROOT folder is colored with the other color then green - you need to provide permission:

sudo chmod 777 -R ROOT

12. Repeat steps 3-5 (stop quilliup, delete log files from "logs" folder and "Catalina" folder).

13. Set up the Repository connection details:

Open the ROOT backup folder. Go to the “../webapps/ROOT/WEB-INF/classes” folder and copy & replace the following file to the same path in the new ROOT folder:

• “connection.properties” - contains quilliup repository settings.

 

14. Edit quilliup main configuration file, "../opt/tomcat/webapps/ROOT/WEB-INF/classes/config.properties".

Do not overwrite the new config.properties file, as it may contain new or additional parameters compared to 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.propertiesbackup file.

For example:

server.ip= full DNS or ip address 
server.port=your current port
server.protocol=http/s
company.name=your current company name
qvw.exe.location=current path\\webapps\\ROOT\\WEB-INF\\lib\\qvw\\QVW.exe
qs.exe.location=current path\\webapps\\ROOT\\WEB-INF\\lib\\qs\\QS.exe
.
.
.

15. If User's permission cache is on (for more details please refer the relevant manual: User's cache) then existing *.json files should be deleted for all the Users.

The *.json files are located under "permCacheFiles" folder in the following path of quilliup server:

cd /opt/tomcat

Access the "permCacheFiles" folder and delete all the *.json files.

16. If upgrading from version 2.7.2 or lower to version 2.8.0 or higher and your DB Repository type  is MySQL, you will likely need to follow these steps::

1. 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;

2. Take the value returned by the query, increment it by 1, and update the hibernate_sequence table with the new value using the following SQL commands:

update hibernate_sequence
set next_val = (RETURNED_VALUE+1)

17. If quilliup runs in Active Directory (AD) mode:

For Jespa configuration:

1. Access the ROOT backup folder.
2. Navigate to opt\tomcat\webapps\ROOT\WEB-INF.
   • Copy the example_ntlm.prp file from the backup folder.
   • Paste it into the same path in the new ROOT folder, replacing the existing file.
3. Open the web.xml file from the WEB-INF folder in both the backup and the new ROOT folders.
   • Edit the web.xml file in the new ROOT folder to match the configuration from the backup file.

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

   Navigate to the following path: opt\tomcat\webapps\ROOT\WEB-INF\classes.

   • Copy the login.conf file from the backup folder.
   • Paste it into the same path in the new ROOT folder, replacing the existing file.

         Navigate to the following path: opt\tomcat.

•  
  • Copy the krb5.conf file from the backup folder.
  • Paste it into the same path in the new ROOT folder.

         Navigate to the following path: opt\tomcat.

•  
  • Copy the *.keytab file from the backup folder.
  • Paste it into the same path in the new ROOT folder

         Navigate to the following path: opt\tomcat.

•  
  • Copy the login.conf file from the backup folder.
  • Paste it into the same path in the new ROOT folder

After replacing the relevant files for Kerberos SPNEGO configuration, please verify all the path parameters connecting these files.
For Kerberos SPNEGO configuration, please refer relevant manual: Connect quilliup to Active Directory using Kerberos (Spnego) for Linux

18. If quilliup runs in HTTPS mode:

Please refer to the following manual and make sure that all parameters are set properly.

19. Start quilliup service:

Go to the bin folder:

cd /opt/tomcat/bin

Start quilliup service:

sudo ./catalina.sh start

Check that the service is up (bin folder):

ps -ef | grep tomcat

Note: When using Oracle as the repository database, the following
oracle.ons.NoServersAvailable: Subscription time out 
error may appear in the logs during application startup.
This error is cosmetic and does not impact service functionality. Proceed to verify that the application UI is up and running before spending time investigating this specific log entry.