Contact Free trial Login

Mule Maven Plugin

The Mule Maven Plugin allows you to integrate the packaging, testing, and deployment of your Mule applications with your Maven lifecycle.
This plugin allows you to deploy your Mule application to different deployment targets such as standalone runtimes, clustered instances, and CloudHub.

The Mule Maven Plugin supports both Community and Enterprise editions.

Compatibility

  • Mule 4.x

  • Anypoint Studio 7.x

Add the Mule Maven Plugin to a Mule Project

To add the Mule Maven Plugin, you need to add its maven dependency to the project:

<plugin>
  <groupId>org.mule.tools.maven</groupId>
  <artifactId>mule-maven-plugin</artifactId>
  <version>3.2.3</version>
  <extensions>true</extensions> (1)
</plugin>
1 It’s important to enable extensions for this plugin.

From this repository:

<pluginRepositories>
    <pluginRepository>
        <id>mule-public</id>
        <url>https://repository.mulesoft.org/nexus/content/repositories/releases</url>
    </pluginRepository>
</pluginRepositories>

This enables the Mule Maven Plugin in your project.

Mule Application Packaging

The Mule Maven Plugin can package your Mule application into a deployable JAR file that you can later deploy to a running Mule Runtime.
The package contains the application and all its dependencies whether those be JAR files required by the application or by its plugins.

Every Mule application has two descriptors. These descriptors tell the plugin how to handle your Mule application’s dependencies.

  • A mule-artifact.json file.
    This file describes how your application is composed.

  • A pom.xml file.
    This file describes all the dependencies required by the package to work properly.

Package a Mule Application

  1. Make sure you added the Mule Maven Plugin to your pom.xml file.

  2. From the command line in your project’s folder, run the package goal:

    $ mvn clean package

The plugin packages your application and creates the deployable JAR file into the target directory within your project’s folder.

Import Your Generated JAR to Anypoint Studio.

If you want to import your generated JAR into Anypoint Studio, you need to package your application using the -DattachMuleSources option to include source files and metadata that Studio requires to re-import the deployable file as an open Mule project into your workspace.

$ mvn clean package -DattachMuleSources

The -DattachMuleSources argument tells the plugin to add a mule-src folder inside the META-INF directory with an exact copy of your application structure at design time. This option will also package project modules and dependencies required to create a functioning Mule deployable archive file that can be deployed into a Mule runtime.

Instead, you can skip bundling the actual modules and external dependencies required to run the Mule application in a Mule runtime, to just create a lightweight package with just the source files and metadata required to import the JAR package back into Anypoint Studio.

source,console,linenums]

$ mvn clean package -DlightweightPackage

With these flags, a lightweight JAR file of the Mule application is created that does not include any depenedencies specified in the Mule applicataion’s pom.xml file. This JAR file cannot be deployed to a Mule runtime, but instead offers a way to archive just the source files that make up the Mule application. The result of these Maven flags is the same unchecking Include project modules and dependenciess when exporting the Mule application from Anypoint Studio.

You can also combine the flags together to create a deployable Mule application package that also includes the source files and metadata to import the package back into Anypoint Studio.

$ mvn clean package -DattachMuleSources -DlightweightPackage

Mule Application Structure Reference

At design time, your Mule application must have at least these three basic components:

Component Type Description

src

Folder

The source directory for your application’s productive source code and tests.
See a reference for this folder below.

pom.xml

Descriptor

The POM file of your Mule application.
This file describes all of your application’s required dependencies.

mule-artifact.json

Descriptor

The mule-artifact file of your Mule application.
This file describes how your Mule application is composed.

These three components are mandatory. If one is missing, the plugin won’t package your project into a deployable JAR file.
Additionally, the plugin does not consider any other directory or file in the root folder of your Mule application when packaging.

Source Directory Reference

The src directory has two main folders: main and test.
The plugin does not consider any other directory inside src when packaging the application.

src/main

src/main is the root folder for all the productive source code of the application.

Folder Folder Type Description

src/main/mule

source

The root folder of the Mule configuration files.
It can contain nested folders, in the way of Java packages.

This folder is mandatory.

src/main/resources

resource

It contains the application resources, such as XML, JSON, and properties files.
Jar files located here are loaded by the application classloader but as plain file resources.

The plugin sends all files inside src/main/mule and src/main/resources to the root directory of your binary package.
Nested folders within src/main/mule are preserved as directories within the root directory of the binary package.

src/test

src/test is the root folder for all the test source code of the application.

Folder Folder Type Description

src/test/java

source

It’s the root folder of the test classes used to validate the custom Java code of the app.
It follows the conventions of any normal Java application.

src/test/munit

source

It contains the MUnit source code.
It can contain nested folders in the way of packages.

src/test/resources

resource

It contains resources, such as XML, JSON, and properties files.
This folder also contains files describing metadata being referenced in the mule-config.xml.

Mule Application Deployment

The Mule Maven Plugin allows you to automate the deployment of your Mule application to your Mule servers.

By default, this plugin allows you to deploy using five different deployment strategies:

  • CloudHub deployment.
    Automate the deployment of your Mule Application to CloudHub.

  • Runtime Fabric deployment.
    Deploy your Mule Application to Runtime Fabric.

  • Runtime Manager REST API deployment.
    Deploy your Mule Application to your Mule server, or server clusters using the Runtime Manager REST API.

  • Mule Agent deployment.
    Deploy your Mule Application using the Mule Agent.
    This deployment strategy only works if all your Mule Runtime instances live under the same address space.

  • Standalone runtime deployment.
    Deploy to a runtime running on your machine.

When deploying an application using the Mule Maven Plugin you need to specify a valid deployment configuration in your pom.xml file.
You can set up a deployment configuration using their dedicated deployment references.

Deploy a Mule Application to CloudHub

Prerequisites

  • The host and port number of your HTTP Listener flow sources are properly configured.

    If you are using the HTTP Listener as sources for your flow, you need to set its host to 0.0.0.0 and its port to ${http.port}.

    CloudHub then dynamically allocates a port at deployment time.

  • All your external classes and resources are properly declared in the mule-artifact.json file of your Mule application.

    Due to Mule 4.x classloading isolation mechanism, all external classes and resources must be explicitly declared in the "exportedPackages" and "exportedResources" fields on the mule-artifact.json file before packaging and deploying the app.

    See Export Resources to learn more about working with external resources in your Mule application.

Deploying to CloudHub

  1. Make sure you added the Mule Maven Plugin to your pom.xml file.

  2. Inside the plugin element, add a configuration for your CloudHub deployment as shown below:

    <plugin>
      ...
        <configuration>
            <cloudHubDeployment>
                <uri>https://anypoint.mulesoft.com</uri>
                <muleVersion>${app.runtime}</muleVersion>
                <username>${username}</username>
                <password>${password}</password>
                <applicationName>${cloudhub.application.name}</applicationName>
                <environment>${environment}</environment>
                <properties>
                    <key>value</key>
                </properties>
            </cloudHubDeployment>
        </configuration>
    
    </plugin>

    The example is using placeholder values. Configure each value with your CloudHub information.

  3. From the command line in your project’s folder, package the app and run the deploy goal:

    $ mvn clean package deploy -DmuleDeploy

Redeploying to CloudHub

To redeploy the app, run the same command as you did to deploy.
CloudHub rewrites the app you had deployed.

Undeploying from CloudHub

To undeploy an app, run the following command:

$ mvn mule:undeploy

The undeploy command also deletes the app in Mule Maven Plugin 3.3.0 and later versions.

CloudHub Deployment Reference

Parameter Description

cloudHubDeployment

Top-Level Element.

uri

Your Anypoint Platform URI.
If not set, by default this value is set to https://anypoint.mulesoft.com.

muleVersion

The Mule runtime version that will run in your CloudHub instance.
You need to ensure that this value is equal to or higher than the minimum required runtime version of your application.

username

Your CloudHub username.

password

Your CloudHub password.

applicationName

The name of your application in CloudHub.
This name is part of the domain of your deployed app. For example, naming your application application-1 makes your app’s public domain application-1.cloudhub.io.

artifact

Absolute file location of the JAR to be deployed.
If not set, by default it is the location of the JAR generated at the package phase

environment

The CloudHub environment to which you want to deploy.

properties

Top-Level element.
If you need to set properties for the Mule application you are deploying, you can use the <properties> top-level element:

<properties>
  <key>value</key>
</properties>

For example:

<properties>
  <http.port>8081</http.port>
</properties>

workers

The number of workers.
By default, it is set to 1.

workerType

Size of each worker.

Accepted values are:

MICRO (0.1 vCores)
SMALL (0.2 vCores)
MEDIUM (1 vCore )
LARGE (2 vCores)
XLARGE (4 vCores)
XXLARGE (8 vCores)
4XLARGE (16 vCores)

The default value is MICRO.

region

Region of worker clouds.

Accepted values are:

  • us-east-1 - US East (N. Virginia)

  • us-west-2 - US West (Oregon)

  • eu-west-1 - EU (Ireland)

  • ap-southeast-2 - Asia Pacific (Sydney)

  • ap-southeast-1 - Asia Pacific (Singapore)

  • us-west-1 - US West (N. California)

  • eu-central-1 - EU (Frankfurt)

  • ap-northeast-1 - Asia Pacific (Tokyo)

  • eu-west-2 - EU (London)

  • ca-central-1 - Canada (Central)

  • sa-east-1 - South America (SΓ£o Paulo)

  • us-east-2 - US East (Ohio)

The default value is us-east-1.

businessGroup

Business group of the deployment.

deploymentTimeout

The allowed elapsed time, in milliseconds, between the start of the deployment process and the confirmation that the artifact has been deployed.

The default value is 1000000.

server

Maven server with Anypoint Platform credentials. This is only needed if you want to use your credentials stored in your Maven settings.xml file. This is not the Mule server name.

skip

Boolean value. When set to true, skips the plugin deployment goal. Its default value is false.

Deploy a Mule Application to Runtime Fabric

Prerequisites

  • The application must be published in Exchange.
    You can do this from Studio following the instructions here.
    Or you can use the Mule Maven Plugin following the instructions here.

Deploying to Runtime Fabric

  1. Make sure you added the Mule Maven Plugin to your pom.xml file.

  2. Inside the plugin element, add a configuration for your Runtime Fabric deployment as shown below:

    <plugin>
      ...
        <configuration>
            <runtimeFabricDeployment>
                <uri>https://anypoint.mulesoft.com</uri>
                <muleVersion>${app.runtime}</muleVersion>
                <username>${username}</username>
                <password>${password}</password>
                <applicationName>${runtime.fabric.application.name}</applicationName>
                <environment>${environment}</environment>
                <provider>${provider}</provider>
                <properties>
                    <key>value</key>
                </properties>
                <deploymentSettings>
                    <cpuReserved>500m</cpuReserved>
                    <memoryReserved>800Mi</memoryReserved>
                </deploymentSettings>
            </runtimeFabricDeployment>
        </configuration>
    
    </plugin>

    The example is using placeholder values. Configure each value with your Runtime Fabric information.

  3. From the command line in your project’s folder, package the application and run the deploy goal:

    $ mvn clean package deploy -DmuleDeploy

Redeploying to Runtime Fabric

To redeploy the application, run the same command as you did to deploy.
Runtime Fabric rewrites the application you had deployed.

Runtime Fabric Deployment Reference

Parameter Description

runtimeFabricDeployment

Top-Level Element.

uri

Your Anypoint Platform URI.
If not set, by default this value is set to https://anypoint.mulesoft.com.

muleVersion

The Mule runtime version that will run in your Runtime Fabric instance.
You need to ensure that this value is equal to or higher than the minimum required runtime version of your application.

username

Your Anypoint Platform username.

password

Your Anypoint Platform password.

applicationName

The name of your application deployed in Exchange.
This name is part of the domain of your deployed app.

target

The Runtime Fabric target name where to deploy the app.

provider

Provider type. Possible values are: MC, SERVER, CLUSTER, SERVER_GROUP.

environment

The Anypoint Platform environment to which you want to deploy.

replicationFactor

The number of instances for your application.
By default, it is set to 1.

publicUrl

Url of the deployed application.

lastMileSecurity

Enable Last-Mile security to forward HTTPS connections to be decrypted by this application.
This requires an SSL certificate to be included in the Mule application, and also requires more CPU resources.
By default, is set to false.

clusteringEnabled

Enable Mule clustering across each replica of the application. It requires to have at least two replicas.
By default, is set to false.

memoryReserved

Amount of memory to be allocated for each replica of the application. If not present, the default value is 700MB.

For example:

<deploymentSettings>
<memoryReserved>100Mi</memoryReserved>
</deploymentSettings>

This will set 100MB of memory to each replica.

memoryMax

Amount of max memory to be allocated for each replica of the application. If a memoryReserved configuration is present, ensure that this value is equal or higher.

For example:

<deploymentSettings>
<memoryMax>200Mi</memoryMax>
</deploymentSettings>

This will set 200MB of memory max to each replica.

cpuReserved

Amount of cores to be allocated for each replica of the application. If not present, the default value is 0.5 vCores.

For example:

<deploymentSettings>
<cpuReserved>500m</cpuReserved>
</deploymentSettings>

This will set 0.5 vCores for each replica.

cpuMax

Amount of max cores to be allocated for each replica of the application. If a cpuReserved configuration is present, ensure that this value is equal or higher.

For example:

<deploymentSettings>
<cpuMax>1000m</cpuMax>
</deploymentSettings>

This will set a max of 1 vCores to each replica.

businessGroup

Business group of the deployment.

deploymentTimeout

The allowed elapsed time, in milliseconds, between the start of the deployment process and the confirmation that the artifact has been deployed.

The default value is 1000000.

server

Maven server with Anypoint Platform credentials. This is only needed if you want to use your credentials stored in your Maven settings.xml file. This is not the Mule server name.

properties

Top-Level element.
If you need to set properties for the Mule application you are deploying, you can use the <properties> top-level element:

<properties>
  <key>value</key>
</properties>

For example:

<properties>
  <http.port>8081</http.port>
</properties>

skip

Boolean value. When set to true, skips the plugin deployment goal. Its default value is false.

See how to determine resource allocation for applications deployed to Runtime Fabric.

Deploy a Mule Application to a Standalone Mule Runtime

  1. Make sure you added the Mule Maven Plugin to your pom.xml file.

  2. Inside the plugin element, add a configuration for your CloudHub deployment as shown below:

    <plugin>
    
      <configuration>
        <standaloneDeployment>
          <muleHome>${mule.home.test}</muleHome>
          <muleVersion>${app.runtime}</muleVersion>
        </standaloneDeployment>
      </configuration>
    
    </plugin>

    The example is using placeholder values. Configure each value with your local Mule runtime information.

  3. From the command line in your project’s folder, package the application and run the deploy goal:

    $ mvn clean package deploy -DmuleDeploy

Standalone Deployment Reference

Parameter Description

standaloneDeployment

Top-Level Element.

muleVersion

The Mule runtime version running in your local machine instance.
If this value does not match the runtime version running in your deployment target, the plugin raises an exception.

The Mule Maven Plugin does not download a Mule runtime if these values don’t match.

muleHome

The location of the Mule Runtime instance in your local machine.

deploymentTimeout

The allowed elapsed time, in milliseconds, between the start of the deployment process and the confirmation that the artifact has been deployed.

The default value is 1000000.

skip

Boolean value. When set to true, skips the plugin deployment goal. Its default value is false.

Deploy a Mule Application Using the Runtime Manager REST API

Prerequisites

Deploying Using the Runtime Manager REST API

  1. Make sure you added the Mule Maven Plugin to your pom.xml file.

  2. Inside the plugin element, add a configuration for your Runtime Manager deployment as shown below:

    <plugin>
      ...
        <configuration>
          <armDeployment>
              <uri>https://anypoint.mulesoft.com</uri>
              <target>${target}</target>
              <targetType>${target.type}</targetType>
              <username>${username}</username>
              <password>${password}</password>
              <environment>${environment}</environment>
              <properties>
                <key>value</key>
              </properties>
          </armDeployment>
        </configuration>
    
    </plugin>

    The example is using placeholder values. Configure each value with your Runtime Manager information.

  3. From the command line in your project’s folder, package the application and run the deploy goal:

    $ mvn clean package deploy -DmuleDeploy

Runtime Manager REST API Deployment Reference

Parameter Description

armDeployment

Top-Level Element.

muleVersion

The runtime version required for your application to run in your deployment target.
If this value does not match the runtime version running in your deployment target, the plugin raises an exception.

The Mule Maven Plugin does not download a Mule runtime if these values don’t match.

uri

The server URI where your Mule runtime instances are installed.
If not set, by default this value is set to https://anypoint.mulesoft.com.

target

The server name for the server where your Mule runtime instances are installed.

targetType

The type of target to which you are deploying.

Valid values are:

  • server

  • serverGroup

  • cluster

username

Your username for the server where your Mule runtime instances are installed.

password

Your password for the server where your Mule runtime instances are installed.

environment

The environment name for the server where your Mule runtime instances are installed.

deploymentTimeout

The allowed elapsed time, in milliseconds, between the start of the deployment process and the confirmation that the artifact has been deployed.

The default value is 1000000.

server

Maven server with Anypoint Platform credentials. This is only needed if you want to use your credentials stored in your Maven settings.xml file. This is not the Mule server name.

properties

Top-Level element.
If you need to set properties for the Mule application you are deploying, you can use the <properties> top-level element:

<properties>
  <key>value</key>
</properties>

For example:

<properties>
  <http.port>8081</http.port>
</properties>

skip

Boolean value. When set to true, skips the plugin deployment goal. Its default value is false.

Deploy a Mule Application Using the Mule Agent

  1. Make sure you added the Mule Maven Plugin to your pom.xml file.

  2. Inside the plugin element, add a configuration for your Mule Agent deployment as shown below:

    <plugin>
      ...
      <configuration>
        <agentDeployment>
          <uri>http://localhost:9999/</uri>
        </agentDeployment>
      </configuration>
    
    </plugin>

    The example is using placeholder values. Configure the URI value with your remote server information.

  3. From the command line in your project’s folder, package the application and run the deploy goal:

    $ mvn clean package deploy -DmuleDeploy

Mule Agent Deployment Reference

Parameter Description

agentDeployment

Top-Level Element.

muleVersion

The runtime version required for your application to run in your deployment target.
If this value does not match the runtime version running in your deployment target, the plugin raises an exception.

The Mule Maven Plugin does not download a Mule runtime if these values don’t match.

uri

The server URI where your Mule runtime instances are installed.

deploymentTimeout

The allowed elapsed time, in milliseconds, between the start of the deployment process and the confirmation that the artifact has been deployed.

The default value is 1000000.

skip

Boolean value. When set to true, skips the plugin deployment goal. Its default value is false.

Encrypting credentials

Encrypted credentials are available in all platform deployments: CloudHub, Runtime Fabric, and Runtime Manager. To use encrypted credentials when deploying, you need to set up your Maven master encrypted password and your settings-security.xml file.

  1. Create a master password for your Maven configuration.

    $ mvn --encrypt-master-password <yourMasterPassword>

    Maven returns your master password encrypted:

    {l9vZ2uM5SdgHy+H12z4pX7LEOZn3Kbnqmt3kIquLjnQ=}
  2. Create a settings-security.xml file in your ~/.m2 repository and add your encrypted master password.

    <settingsSecurity>
      <master>{l9vZ2uM5SdgHy+H12z4pX7LEOZn3Kbnqmt3kIquLjnQ=}</master>
    </settingsSecurity>
  3. Encrypt your Anypoint platform password:

    $ mvn --encrypt-password <yourAnypointPlatformPassword>

    Maven returns your Anypoint platform password encrypted:

    {HTWFGH5BG9QmvJ1B=}
  4. Add your encrypted Anypoint Platform password to your settings.xml file in the <server> section:

    <settings>
     ...
      <servers>
       ...
        <server>
          <id>my.anypoint.credentials</id>
          <username>my.anypoint.username</username>
          <password>{HTWFGH5BG9QmvJ1B=}</password>
        </server>
       ...
      </servers>
     ...
    </settings>
  5. In your configuration deployment, reference the credentials injecting the server id configured in your settings.xml file. Below is an example of a CloudHub Deployment using encrypted credentials:

<plugin>
  ...
    <configuration>
        <cloudHubDeployment>
            <uri>https://anypoint.mulesoft.com</uri>
            <muleVersion>${app.runtime}</muleVersion>
            <server>my.anypoint.credentials</server>
            <applicationName>${cloudhub.application.name}</applicationName>
            <environment>${environment}</environment>
            <properties>
                <key>value</key>
            </properties>
        </cloudHubDeployment>
    </configuration>

</plugin>
Make sure that username and password are not set in the deployment configuration, as they have precedence over the defined server id.

Skipping Plugin Execution

You can skip the plugin execution by setting the skip flag to true inside your deployment configuration:

<plugin>
  ...
  <configuration>
    <standaloneDeployment>
      <muleHome>${mule.home.test}</muleHome>
      <skip>true</skip>
    </standaloneDeployment>
  </configuration>
</plugin>

Skipping Deployment Verification

You can skip the status verification of your deployed app by setting the skipDeploymentVerification flag to true inside of any of the platform deployments (Cloudhub, Runtime Manager, and Runtime Fabric):

<plugin>
  <groupId>org.mule.tools.maven</groupId>
  <artifactId>mule-maven-plugin</artifactId>
  <version>${mule.maven.plugin.version}</version>
  <extensions>true</extensions>
  <configuration>
    <runtimeFabricDeployment>
      ...
      <skipDeploymentVerification>true</skipDeploymentVerification>
      ...
    </runtimeFabricDeployment>
  </configuration>
</plugin>

If the skipDeploymentVerification flag is not present, the default value is false.
This feature is available in plugin version 3.2.5 and later.

Anypoint Runtime Manager On-Premises TLS Errors

When trying to connect to an instance of Runtime Manager that’s on an Anypoint Platform Private Cloud Edition installation, the plugin validates certificates for that server. If you haven’t installed the server certificates in your truststore, an SSL error occurs. To avoid this problem, you can run the plugin in an insecure mode, which skips the security validations. You can use the armInsecure tag or the arm.insecure system property.

Enabling an insecure connection is a dangerous practice. Don’t use this unless you know what you are doing and your On-Premises installation is isolated in a local network.

See the configuration example below:

<plugin>
  ...
    <configuration>
      <armDeployment>
          <target>${target}</target>
          <targetType>${target.type}</targetType>
          <username>${username}</username>
          <password>${password}</password>
          <environment>${environment}</environment>
          <armInsecure>true</armInsecure>
      </armDeployment>
    </configuration>
</plugin>

Was this article helpful?

πŸ’™ Thanks for your feedback!

Edit on GitHub