Steps to Perform upgrading Mule Runtime Version And Java version using Upgrade tool

Note: This guide uses an upgrade from Runtime 4.4.x(Java 8) to Runtime 4.9.x(Java 17) as an example. You can use any other runtime version that supports Java 17, as long as it is a higher version than the one you are upgrading from.

1. Preparation

1. Download Files: From the MuleSoft Support Portal, download two packages:

   • The Upgrade Tool

   • The new Runtime 4.9.x package (e.g., mule-enterprise-standalone-4.9.7)

2. Unzip Files: Unzip both downloaded packages into your working directory.

3. Copy Tool: Copy all files from the unzipped Upgrade Tool folder and paste them into the tools directory of your existing Runtime 4.4.x instance.
    

2. Run the Upgrade Command

Prerequisite: Ensure Runtime Server 4.4.x is stoped and Java 17 is installed and is the active Java version on your machine.(https://www.java.com/en/download/help/version_manual.html)

1. Open your terminal.

2. Navigate to the tools folder of your existing Runtime 4.4.x instance (where you just pasted the upgrade files).

3. Execute the following command, using the complete and absolute path to the newly unzipped mule-enterprise-standalone-4.9.7 folder:

   ./upgrade-tool upgrade -n /full/path/to/mule-enterprise-standalone-4.9.7 (Mac/Linux Command)
   upgrade-tool upgrade -n /full/path/to/mule-enterprise-standalone-4.9.7 (Windows Command)

3. Troubleshooting: wrapper.conf Conflict

You might encounter the following error after running the command:

ERROR: The config file 'conf/wrapper.conf' was updated in the new version, make sure the one you want to use with the changes needed is in the 'ready' folder

Solution:

1. Backup: Keep a copy of the old wrapper.conf file from your Runtime 4.4.x conf directory for reference.

2. Copy and Replace: Copy the wrapper.conf file from the new Runtime 4.9.x directory (e.g., .../mule-enterprise-standalone-4.9.7/conf/wrapper.conf).

3. Paste this new file into two locations:

   • The conf directory of your old Runtime 4.4.x instance.

   • The ready folder created by the tool: [Your-Runtime-4.4-Path]/tools/upgrade-tool/mule-config-conflicts/ready/

4. Re-run the upgrade command from Step 2.

4. Start and Verify the Server

1. Start the server using the following command from the bin directory: 
   ./mule start(Mac/Linux)
mule start(Windows)

2. Log in to Anypoint Platform and check Runtime Manager to verify that the server has been successfully upgraded to Runtime 4.9.x and the Java version is listed as 17.
    

5. Post-Upgrade Troubleshooting

If the server fails to start or is not registering correctly in Anypoint Platform:

1. Check Logs: Check the mule_ee.log file inside your runtime's logs folder for specific error messages.

2. Memory-Related Adjustments (If Required):

   • The upgrade from Java 8 to Java 17 and a new Runtime version may change memory requirements.

   • If you see memory-related issues in the logs, compare your new wrapper.conf with the backup of your old (4.4) wrapper.conf.

   • You may need to update the following properties in the new wrapper.conf to match your previous custom settings:

   Properties

   # Example memory settings to verify
   wrapper.java.additional.7 = -XX:MaxMetaspaceSize=xxxxm
   wrapper.java.additional.8 = -XX:MetaspaceSize=xxxm
   
   # Initial Java Heap Size (in MB)
   wrapper.java.initmemory = xxxx
   
   # Maximum Java Heap Size (in MB)
   wrapper.java.maxmemory = xxxx
   

   #Addition customer properties eg:
   wrapper.java.additional.17=mule.env=dev
   wrapper.java.additional.18=mule.key=myEncryptionKey123
   wrapper.java.additional.19=mulesoft.anypoint.client_id=xxxxx-x-x-x-xxx

3. After applying any necessary changes, restart the server and verify again in Anypoint Platform.