Contact Us 1-800-596-4880

Mule Maven Plugin 2.3.x

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.

Prerequisites

This document assumes that you are familiar with Maven, managing pom.xml files, and working with Maven plugins. (If you are just getting started with Maven, we suggest you follow Maven’s Getting Started tutorial.) Additionally, this document assumes familiarity with developing Mule applications within Maven. For more information about Mule and Maven, see Using Maven with Mule.

Compatibility

  • Mule 3.x

  • Anypoint Studio 6.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>2.3.2</version>
  <extensions>true</extensions>
</plugin>
Enable extensions. If <extensions>true</extensions> is not present, the plugin does not work.

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 ZIP file that you can later deploy to a running Mule Runtime.

  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 ZIP file into the target directory within your project’s folder.

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/app

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.
ZIP files located here are loaded by the application classloader but as plain file resources.

The plugin sends all files inside src/main/app and src/main/resources to the root directory of your binary package.
Nested folders within src/main/app 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.

Including and Excluding Additional Libraries

You can include additional JAR libraries into your project by using the <inclusion> element. Included libraries will be added to the /lib folder of your project.

Example XML

<plugin>
  ...
  <configuration>
    <inclusions>
      <inclusion>
        <groupId>com.mulesoft.security</groupId>
        <artifactId>mule-module-security-property-placeholder</artifactId>
      </inclusion>
    </inclusions>
  </configuration>
  ...
</plugin>

This example includes the Security Property Placeholder module into the project’s /lib directory.

You can also use the <exclusion> element to exclude libraries from your project’s /lib folder when packaging the application.

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 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 deployment configurations 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.

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>${mule.version}</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 2.3.3 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 engine 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.

skip

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

artifact

Absolute file location of the ZIP to be deployed.
If not set, by default it is the location of the ZIP 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.

businessGroupId

The Business group id of the deployment.
This parameter is available in plugin version 2.3.4 and later.

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.

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.

skipDeploymentVerification

This feature is available in plugin version 2.3.2 and later.
Boolean value. When set to true, skips the status verification of your deployed app. Its default value is false.

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

Studio allows you to select only two project types when uploading an application to Exchange: example and template. To specify a different project type, publish your application using Maven.

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>3.9.4</muleVersion>
          <username>user</username>
          <password>pass</password>
          <applicationName>newapp</applicationName>
          <target>rtf</target>
          <environment>Sandbox</environment>
          <provider>MC</provider>
          <replicas>1</replicas>
          <properties>
            <key>value</key>
          </properties>
          <deploymentSettings>
            <enforceDeployingReplicasAcrossNodes>false</enforceDeployingReplicasAcrossNodes>
            <updateStrategy>recreate</updateStrategy>
            <clustered>false</clustered>
            <forwardSslSession>false</forwardSslSession>
            <lastMileSecurity>false</lastMileSecurity>
            <resources>
              <cpu>
                <reserved>20m</reserved>
                <limit>1500m</limit>
              </cpu>
              <memory>
                <reserved>700Mi</reserved>
                <limit>800Mi</limit>
              </memory>
            </resources>
            <http>
              <inbound>
                <publicUrl>url</publicUrl>
              </inbound>
            </http>
          </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 engine 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. Set to MC ("MC" specifies Runtime Fabric).

environment

The Anypoint Platform environment to which you want to deploy.

replicas

Specifies the number of replicas, or instances, of the Mule application to deploy

businessGroup

The Business group path of the deployment.
For example:

<businessGroup>MainOrg/SubOrg</businessGroup>

businessGroupId

The Business group id of the deployment.
This parameter is available in plugin version 2.3.4 and later.

deploymentTimeout

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

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.

deploymentSettings

See the deploymentSettings Reference table below for a complete list of parameters that can be configured inside this element.

deploymentSettings Reference

The deployment configuration for Runtime Fabric has changed in Mule Maven Plugin 2.3.5. If you are using an earlier version, see Mule Maven Plugin 2.3.5 Release Notes for a list of changed properties.

Parameter Description

enforceDeployingReplicasAcrossNodes

Enforces the deployment of replicas across different nodes. The default value is false.

Configuration example:

<deploymentSettings>
  <enforceDeployingReplicasAcrossNodes>false</enforceDeployingReplicasAcrossNodes>
</deploymentSettings>

updateStrategy

Accepted values Description

rolling

Maintains availability by updating replicas incrementally. Requires one additional replica’s worth of resources to succeed.
If enforceDeployingReplicasAcrossNodes is enabled, the maximum number of replicas you can configure is one less than the total number of nodes.

recreate

Terminates replicas before re-deployment. Re-deployment is quicker than rolling and doesn’t require additional resources.
If enforceDeployingReplicasAcrossNodes is enabled, the maximum number of replicas you can configure is equal to the number of nodes.

The default value is rolling.

Configuration example:

<deploymentSettings>
  <updateStrategy>recreate</updateStrategy>
</deploymentSettings>

forwardSslSession

Enables SSL forwarding during a session. The default value is false.

Configuration example:

<deploymentSettings>
  <forwardSslSession>true</forwardSslSession>
</deploymentSettings>

clustered

Enables clustering across two or more replicas of the application. The default value is false.

Configuration example:

<deploymentSettings>
    <clustered>true</clustered>
</deploymentSettings>

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. The default value is false.
Configuration example:

<deploymentSettings>
    <lastMileSecurity>true</lastMileSecurity>
</deploymentSettings>

resources

cpu

reserved

Specifies the number of cores to allocate for each application replica. The default value is 0.5 vCores.

limit

Specifies the number of max cores to allocate for each replica of the application.
If a reserved configuration is present, ensure that this value is equal or higher.

memory

reserved

Specifies the amount of memory to allocate for each application replica. The default value is 700 MB.

limit

Specifies the maximum amount of memory to allocate for each replica of the application.
If a reserved configuration is present, ensure that this value is equal or higher.

Configuration example:

<deploymentSettings>
  <resources>
    <cpu>
      <reserved>20m</reserved>
      <limit>1500m</limit>
    </cpu>
    <memory>
      <reserved>700Mi</reserved>
      <limit>800Mi</limit>
    </memory>
  </resources>
</deploymentSettings>

http

inbound

publicURL

URL of the deployed application.

Configuration example:

<deploymentSettings>
  <http>
    <inbound>
      <publicUrl>myapp.anypoint.com</publicUrl>
    </inbound>
  </http>
</deploymentSettings>

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>${mule.version}</muleVersion>
        </standaloneDeployment>
      </configuration>
    
    </plugin>

    The example is using placeholder values. Configure each value with your local Mule runtime engine 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 engine 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 engine if these values don’t match.

muleHome

The location of the Mule instance in your local machine.

deploymentTimeout

The allowed elapsed time, in milliseconds, between the instant when the deployable is copied to the runtime and the creation of the respective anchor file.

skip

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

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 engine if these values don’t match.

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.

uri

The server URI where your Mule 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 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 instances are installed.

password

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

environment

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

businessGroup

The Business group path of the deployment.

businessGroupId

The Business group id of the deployment.
This parameter is available in plugin version 2.3.4 and later.

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>

armInsecure

Boolean value. When set to true, the plugin does not validate certificates for the configured server.

skip

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

skipDeploymentVerification

This feature is available in plugin version 2.3.2 and later.
Boolean value. When set to true, skips the status verification of your deployed app. 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 engine if these values don’t match.

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.

uri

The server URI where your Mule instances are installed.

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 main encrypted password and your settings-security.xml file.

  1. Create a main password for your Maven configuration.

    $ mvn --encrypt-main-password <yourMainPassword>

    Maven returns your main password encrypted:

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

    <settingsSecurity>
      <main>{l9vZ2uM5SdgHy+H12z4pX7LEOZn3Kbnqmt3kIquLjnQ=}</main>
    </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> element:

    <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>${mule.version}</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 2.3.2 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>