Download, Install, Configure, and Upgrade On-Premises Mule Runtime Engine

Download, unpack, and configure on-premises runtime after you confirm Hardware and Software Requirements for On-Premises Mule Runtime Engine. This is the Download and Wrapper stages in On-Premises Runtimes Overview. After the JVM starts in the console, stop it and install an Enterprise license before you run the instance in production.

Before downloading and installing Mule runtime engine (Mule), verify that you have a supported JDK installed. This example uses Eclipse Temurin 17, which is recommended for Mule runtime engine.

$ java -version
openjdk version "17.0.13" 2024-10-15
OpenJDK Runtime Environment Temurin-17.0.13+11 (build 17.0.13+11)
OpenJDK 64-Bit Server VM Temurin-17.0.13+11 (build 17.0.13+11, mixed mode, sharing)

AdoptOpenJDK moved to the Eclipse Foundation and changed its name to the Eclipse Adoptium project. The name of the JDK changed to Temurin.

Download Mule Runtime Engine for On-Premises

Download the Enterprise standalone distribution (mule-enterprise-standalone-*.zip) when you have an Enterprise license. That zip is Mule Enterprise Edition. The Mule Kernel (Community Edition) artifact is mule-standalone-*.zip. Kernel doesn’t accept an Enterprise license and doesn’t include clustering.

Download mule-enterprise-standalone-*.zip from the MuleSoft Support portal at https://help.mulesoft.com or from your MuleSoft account representative, then unzip it. Don’t use the Anypoint Studio installer to obtain on-premises runtime. Studio already includes Mule for development.
Set an environment variable called MULE_HOME for the mule directory inside your extracted folder.

Example in the Downloads directory:
- In Windows environments:
  $ env:MULE_HOME="C:\Downloads\mule-enterprise-standalone-<version>"
- In Linux or Unix environments:
  $ export MULE_HOME=~/Downloads/mule-enterprise-standalone-<version>

The procedure for making the MULE_HOME setting permanent depends on your operating system.

Test the On-Premises Runtime

After downloading Mule, test to confirm that it runs in your system without errors by executing these commands:

In Windows environments:
```
%MULE_HOME%\bin\mule.bat
```
In Linux or Unix environments:
```
$ $MULE_HOME/bin/mule
```

These commands run Mule in foreground mode, and the startup script displays information on the terminal’s standard output. You can’t issue further commands on the terminal as long as Mule is running.

To stop Mule, press CTRL-C in the terminal in which the script is running.

After the console start succeeds, stop Mule. Next, install an Enterprise license. Then install the Windows service or Linux daemon and configure the wrapper.

Install as a Windows Service or Linux Daemon

Installing the service or daemon is the Service stage in On-Premises Runtimes Overview. Start and stop commands are in Start and Stop On-Premises Mule Runtime Engine.

Install Mule as a Windows service or as a Linux or Unix daemon:

In Windows environments:
```
$ $MULE_HOME\bin\mule.bat install
```
In Linux or Unix environments:
```
$ $MULE_HOME/bin/mule install
```

Configure the Java Service Wrapper

To point Mule runtime engine at a specific JDK, set wrapper.java.command in wrapper.conf to the java executable path, not to JAVA_HOME. An incorrect wrapper.java.command value is a common cause of startup failures.

After installing Mule as a service or as a daemon, you can modify the properties defined in the wrapper.conf file.

For details about what you can do with the configuration file, see Configuration Property Overview.

After modifying the wrapper.conf file, restart your Mule instance to enable the changes.

When you add new properties, ensure that no other properties already use the same sequence number (don’t worry about the ones in wrapper-additional.conf, as Mule adjusts those upon restart).

Don’t modify the wrapper-additional.conf file, as Mule automatically generates this file.

On Linux hosts, for Mule applications that use Java Native Access (JNA) to load native libraries, JNA loads those libraries from a temporary directory. If that directory is mounted with the noexec option, library loading fails. Add a line to the wrapper.conf file to redirect JNA to a directory that permits execution, replacing <n> with an unused sequence number: wrapper.java.additional.<n>=-Djna.tmpdir=/tmp.

Configure JVM Memory and Wrapper Timeouts

The Java Service Wrapper (Tanuki) starts the JVM that hosts on-premises Mule runtime engine. Set heap, Metaspace, and startup timeouts in $MULE_HOME/conf/wrapper.conf. Restart the runtime after you change this file.

Heap isn’t the full RAM of the host. Leave memory for the operating system and for Metaspace, which is a separate pool. Don’t set wrapper.java.maxmemory equal to the host RAM. The CloudHub vCore model doesn’t apply on-premises.

Use the wrapper memory properties, not a mix of those properties and -Xms/-Xmx additional lines, so one setting doesn’t silently override the other:

wrapper.java.initmemory=1024
wrapper.java.maxmemory=2048

Those values are megabytes and map to -Xms and -Xmx. To cap Metaspace, add an unused wrapper.java.additional.<n> index:

wrapper.java.additional.<n>=-XX:MaxMetaspaceSize=512m

If two additional properties share the same <n>, the wrapper keeps one and ignores the other. Don’t edit wrapper-additional.conf; the runtime regenerates that file.

If startup fails with Timed out waiting for signal from JVM, increase wrapper.startup.timeout in wrapper.conf (seconds). The wrapper kills and can restart the JVM when Pinging the JVM took persists; fix heap, CPU, and GC before raising ping timeouts.

Install Offline or Air-Gapped

An air-gapped on-premises install doesn’t require outbound internet on the runtime host after you have the standalone zip. Download mule-enterprise-standalone-*.zip (or the Kernel zip) on a connected machine, transfer the file to the isolated host, unpack it, and set MULE_HOME.

The standalone distribution starts without Maven Central. Application JARs must already include their dependencies. Resolve and package Mule applications on a connected build agent, then copy the deployable JARs to $MULE_HOME/apps (and domain JARs to $MULE_HOME/domains).

Don’t run Studio’s "install new software" flow on the isolated host to obtain the runtime. That flow installs Anypoint Studio components, not the on-premises standalone distribution.

Run Multiple Instances on One Host

Each on-premises Mule runtime engine instance needs its own install directory and its own MULE_HOME. Don’t run two instances from the same unpacked zip. Copy or unpack a second distribution into a different folder, for example /opt/mule-runtime-a and /opt/mule-runtime-b.

Give each instance unique HTTP and other listener ports in the Mule applications (or in a domain). Wrapper and cluster ports must not collide. On Windows, install each instance as its own service from that instance’s bin directory so the service name and wrapper.conf stay isolated.

Keep a stable path for operations (a symlink such as /opt/mule that points at the current directory) if your monitoring agent or scripts hard-code MULE_HOME. Renaming the install directory after Anypoint Monitoring is installed breaks that agent; reinstall monitoring after a path change.

Configure CPU Affinity

Many operating systems provide a mechanism to bind a process to one or more central processing units (CPUs) so that the process executes only on the assigned CPUs. You can configure CPU affinity in your environment to run Mule in a nonvirtualized multicore server and comply with the number of cores included in your subscription.

Review CPU Affinity Considerations

CPUs have groups of cores that share a cache to improve thread communication and migration performance. To avoid such performance issues, check with your infrastructure team to identify which cores share this cache before setting up this feature.
Check with your infrastructure team to ensure that no existing resource allocation policy that can interfere with your CPU affinity configuration.
Ensure that the number of cores you plan to configure through CPU affinity doesn’t exceed the number of cores included in your MuleSoft subscription plan.

Remove the Service or Daemon

You can remove Mule as a Windows service or as a Unix daemon by executing the corresponding command:

In Windows environments:
```
$ $MULE_HOME\bin\mule.bat remove
```

In Linux or Unix environments:

$ $MULE_HOME/bin/mule remove
MULE_HOME is set to /Applications/mule-enterprise-standalone-<version>
MULE_BASE is set to /Applications/mule-enterprise-standalone-<version>
Detected Mac OSX:
Mule Enterprise Edition is not running.
Removing Mule Enterprise Edition daemon...

Install Anypoint Monitoring

You can install Anypoint Monitoring after you register on-premises runtime with Runtime Manager. That registered model is a Hybrid Standalone Runtime. Unregistered on-premises runtime doesn’t use this monitoring install path.

Update, Upgrade, or Migrate Mule Runtime Engine

MuleSoft releases new major, minor, and patch release versions of Mule, as well as monthly updates to patch releases of Mule that incorporate the latest bug fixes and security enhancements.

To update a patch version of Mule, see Update Patches to Mule Runtime Engine
To upgrade to a later version of Mule 4, see Upgrading Mule Runtime Engine (Versions 4.x to 4.n)

Troubleshoot Common Error Messages

`Timed out waiting for signal from JVM`

The Java Service Wrapper (Tanuki) started the JVM but didn’t receive a ready signal before wrapper.startup.timeout. Increase that timeout in wrapper.conf or fix whatever is blocking JVM startup (JDK, license, or port conflict).

`JVM received a signal SIGKILL (9)`

The operating system killed the JVM that hosts on-premises Mule runtime engine. This isn’t a graceful mule stop. Check the out-of-memory killer, ulimit settings, and whether an operator or orchestrator sent SIGKILL.

`Pinging the JVM took`

The Java Service Wrapper pinged the JVM and the response was slow. The wrapper can restart Mule runtime engine when ping delays persist. Review heap, CPU, and GC before raising ping timeouts.