Contact Us 1-800-596-4880

Mule Maven Plugin 2.2.x

We recommend you to migrate to version 2.3.0 of the Mule Maven Plugin, as that version is able to package and deploy applications.

The mule-maven-plugin allows you to deploy Mule applications to different kinds of servers: Standalone (both Community and Enterprise), clustered, Anypoint Runtime Manager and CloudHub. It is part of the framework for developing Mule applications with Maven, an overview of which you can find in Using Maven with Mule. The most important capabilities provided by the plugin are running integration tests, and deploying applications to different environments.

The plugin allows you to:

  • Deploy a Mule application to a local standalone server

  • Run integration tests in a local standalone deployment

  • Deploy Mule applications to Anypoint Runtime Manager

  • Deploy Mule applications to CloudHub

  • Deploy Mule applications to a local cluster

The plugin supports both Community and Enterprise editions.

As an alternative to using the Maven Plugin for deploying applications to the Runtime Manager, you may also use the Runtime Manager API.

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.

We recommend that you update this plugin to its latest version, as its usability is greatly improved as of version 2.2.1

Compatibility

  • Mule 3.x

  • Anypoint Studio 6.x

Adding the Plugin

Adding the Maven Dependency for the Plugin

Edit your pom.xml file to include the following:

<plugin>
  <groupId>org.mule.tools.maven</groupId>
  <artifactId>mule-maven-plugin</artifactId>
  <version>2.2.1</version>
</plugin>

Adding the Maven Repository

The repository for the plugin is at https://repository.mulesoft.org/nexus/content/repositories/releases. To add it to your Maven installation, edit your pom.xml file to include the following:

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

Running the Plugin

To run the plugin, use your system’s console to navigate to the root directory of your project and type:

$ mvn org.mule.tools.maven:mule-maven-plugin:<goal>

A Simple Example

In the simplest scenario, the plugin performs two tasks:

  • Downloads and installs a Mule standalone server

  • Deploys the result of the Maven build to the Mule server

For the following example to work, your pom.xml must include the repository where Mule is available.
<plugin>
    <groupId>org.mule.tools.maven</groupId>
    <artifactId>mule-maven-plugin</artifactId>
    <version>2.2.1</version>
    <configuration>
        <deploymentType>standalone</deploymentType>
        <muleVersion>3.8.5</muleVersion>
    </configuration>
    <executions>
        <execution>
            <id>deploy</id>
            <phase>deploy</phase>
            <goals>
                <goal>deploy</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Then run:

$ mvn org.mule.tools.maven:mule-maven-plugin:deploy

This example also triggers the default deploy goal of the maven-deploy-plugin. If you are not deploying to a Maven repository as part of your build, you can prevent plugin execution by using:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-deploy-plugin</artifactId>
  <configuration>
    <skip>true</skip>
  </configuration>
</plugin>

Deploying to Anypoint Runtime Manager

You can deploy your application to a running Runtime Manager server, serverGroup or cluster. You need to provide the Runtime Manager credentials and configure the target name.

Only platform users are allowed in this configuration. It’s not possible to user SSO/Federated as username.
For a list and description of the parameters used in the examples, see below.
<plugin>
    <groupId>org.mule.tools.maven</groupId>
    <artifactId>mule-maven-plugin</artifactId>
    <version>2.2.1</version>
    <configuration>
        <deploymentType>arm</deploymentType>
        <username>myUsername</username>
        <password>myPassword</password>
        <target>server-name</target>
        <!-- One of: server, serverGroup, cluster -->
        <targetType>server</targetType>
        <environment>Production</environment>
    </configuration>
    <executions>
        <execution>
            <id>deploy</id>
            <phase>deploy</phase>
            <goals>
                <goal>deploy</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Then run:

$ mvn org.mule.tools.maven:mule-maven-plugin:deploy

For a list and description of the parameters employed, see Runtime Manager.

Deploying to CloudHub

To deploy your application to CloudHub:

<plugin>
    <groupId>org.mule.tools.maven</groupId>
    <artifactId>mule-maven-plugin</artifactId>
    <version>2.2.1</version>
    <configuration>
        <deploymentType>cloudhub</deploymentType>
         <!-- muleVersion is the runtime version as it appears on the CloudHub interface -->
        <muleVersion>3.8.5</muleVersion>
        <username>myUsername</username>
        <password>myPassword</password>
        <redeploy>true</redeploy>
        <environment>Production</environment>
    </configuration>
    <executions>
        <execution>
            <id>deploy</id>
            <phase>deploy</phase>
            <goals>
                <goal>deploy</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Then run:

$ mvn org.mule.tools.maven:mule-maven-plugin:deploy

For a list and description of the parameters employed, see CloudHub.

Selecting Your Business Group

In CloudHub and Anypoint Runtime Manager deployments, you can select a Business Group other than your root organization. In the example below, the plugin is configured to deploy to the devops business group, which resides under the engineering business group.

Business group names within a hierarchy are separated by a backslash (\). If the name of your business group includes a backslash, escape it with preceding backslash. For example, to select \group2 under \group1: \group1\\group2.

<plugin>
    <groupId>org.mule.tools.maven</groupId>
    <artifactId>mule-maven-plugin</artifactId>
    <configuration>
        <deploymentType>cloudhub</deploymentType>
        <muleVersion>${mule.version}</muleVersion>
        <username>${username}</username>
        <password>${password}</password>
        <applicationName>my-application</applicationName>
        <environment>Production</environment>
        <businessGroup>engineering\devops</businessGroup>
    </configuration>
    <executions>
        <execution>
            <id>deploy</id>
            <phase>deploy</phase>
            <goals>
                <goal>deploy</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Using a Mule Server Instead of Downloading Mule Dependency

Instead of downloading and installing a new Mule server, you can configure the plugin to deploy to an existing server, by configuring the muleHome property as shown below.

<plugin>
    <groupId>org.mule.tools.maven</groupId>
    <artifactId>mule-maven-plugin</artifactId>
    <version>2.2.1</version>
    <configuration>
        <deploymentType>standalone</deploymentType>
        <muleHome>/path/to/mule/server</muleHome>
    </configuration>
    <executions>
        <execution>
            <id>deploy</id>
            <phase>deploy</phase>
            <goals>
                <goal>deploy</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Deploying to a Mule Server Using the Agent

You can also configure the plugin to deploy to an existing Mule server using the API provided by the Mule agent. In the code shown below, the uri parameter is the endpoint of the REST API of the agent.

<plugin>
    <groupId>org.mule.tools.maven</groupId>
    <artifactId>mule-maven-plugin</artifactId>
    <version>2.2.1</version>
    <configuration>
        <deploymentType>agent</deploymentType>
        <uri>http://localhost:9999/</uri>
    </configuration>
    <executions>
        <execution>
            <id>deploy</id>
            <phase>deploy</phase>
            <goals>
                <goal>deploy</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Then run:

$ mvn org.mule.tools.maven:mule-maven-plugin:deploy

For a list and description of the parameters employed, see Agent.

Running Integration Tests

One of the most important uses for the plugin is to run integration tests on your integration application. Check the working example in src/it/standalone/example-integration-tests.

To run integration tests, the basic steps are the following:

  • Configure the maven-mule-plugin to pack your project in the Mule app format

  • Configure maven-failsafe-plugin to run integration tests and report

  • Configure mule-maven-plugin to deploy the project’s packaged application to a new Mule server downloaded from a Maven repository.

<plugins>
    <plugin>
        <groupId>org.mule.tools.maven</groupId>
        <artifactId>mule-app-maven-plugin</artifactId>
        <version>2.2.1</version>
        <extensions>true</extensions>
    </plugin>
    <plugin>
        <groupId>org.mule.tools.maven</groupId>
        <artifactId>mule-maven-plugin</artifactId>
        <version>2.0</version>
        <configuration>
            <deploymentType>standalone</deploymentType>
            <muleVersion>3.8.5</muleVersion>
        </configuration>
        <executions>
            <execution>
                <id>deploy</id>
                <phase>pre-integration-test</phase>
                <goals>
                    <goal>deploy</goal>
                </goals>
            </execution>
            <execution>
                <id>undeploy</id>
                <phase>post-integration-test</phase>
                <goals>
                    <goal>undeploy</goal>
                </goals>
            </execution>
        </executions>
    </plugin>
    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-failsafe-plugin</artifactId>
        <executions>
            <execution>
                <id>integration-test</id>
                <goals>
                    <goal>integration-test</goal>
                    <goal>verify</goal>
                </goals>
            </execution>
        </executions>
    </plugin>
</plugins>

Full Example

For a list and description of the parameters used in the examples, see below.

In this example, the plugin is configured for a standalone deployment, and performs the following tasks:

  • Configures one application for deployment

  • Configures two external libraries to be added to the server

  • Configures a domain to deploy

  • Defines a script to run before starting the server

<plugin>
    <groupId>org.mule.tools.maven</groupId>
    <artifactId>mule-maven-plugin</artifactId>
    <version>2.2.1</version>
    <configuration>
        <muleVersion>3.8.5</muleVersion>                 (1)
        <deploymentType>standalone</deploymentType>
        <applications>
            <application>${app.location}</application>   (2)
        </applications>
        <libs>
          <lib>${basedir}/activemq-all-5.5.0.jar</lib>
          <lib>${basedir}/activemq-core.jar</lib>        (3)
        </libs>
        <arguments>
            <argument>-M-Dport.1=1337</argument>
            <argument>-M-Dport.2=1338</argument>         (4)
        </arguments>
        <domain>${project.basedir}/domain</domain>       (5)
        <script>${basedir}/script.groovy</script>        (6)
        <community>false</community>                     (7)
    </configuration>
    <executions>
        <execution>
            <id>deploy</id>
            <phase>pre-integration-test</phase>
            <goals>
                <goal>deploy</goal>                      (8)
            </goals>
        </execution>
        <execution>
            <id>undeploy</id>
            <phase>post-integration-test</phase>
            <goals>
                <goal>undeploy</goal>                    (9)
            </goals>
        </execution>
    </executions>
</plugin>
1 Configures the Mule version.
2 This points either to a Mule application deployable zip file, or to an exploded Mule app folder. Defaults to the build-generated artifact.
3 External libs to be added to Mule Standalone.
4 Mule arguments (optional).
5 Domain to deploy. To add your application to the domain, you must configure your application manually (optional).
6 Optional Groovy script to run just before deployment.
7 Use Enterprise Edition.
8 Use the deploy goal to download Mule, install it and deploy the domain and applications.
9 Use the undeploy goal to undeploy the applications and stop Mule server.

Run

$ mvn org.mule.tools.maven:mule-maven-plugin:deploy

To deploy the application.

You can then run:

$ mvn org.mule.tools.maven:mule-maven-plugin:undeploy

To stop the application

For a list and description of the parameters employed, see Standalone.

Deploying to a Local Mule Cluster

For a list and description of the parameters used in the examples, see below.
<plugin>
    <groupId>org.mule.tools.maven</groupId>
    <artifactId>mule-maven-plugin</artifactId>
    <version>2.2.1</version>
    <configuration>
        <muleVersion>3.8.5</muleVersion>
        <deploymentType>cluster</deploymentType>
        <size>2</size>                                      (1)
        <application>${app.1.location}</application>
        <libs>
          <lib>${basedir}/activemq-all-5.5.0.jar</lib>
          <lib>${basedir}/activemq-core.jar</lib>
        </libs>
        <arguments>
            <argument>-M-Dport.1=1337</argument>
            <argument>-M-Dport.2=1338</argument>
        </arguments>
    </configuration>
    <executions>
        <execution>
            <id>deploy</id>
            <phase>pre-integration-test</phase>
            <goals>
                <goal>deploy</goal>                         (2)
            </goals>
        </execution>
        <execution>
            <id>undeploy</id>
            <phase>post-integration-test</phase>
            <goals>
                <goal>undeploy</goal>                       (3)
            </goals>
        </execution>
    </executions>
</plugin>

This example is similar to the last one, with the following differences:

1 Specify the number of nodes to use to create the cluster. The plugin then creates the cluster for you.
2 To start the cluster, you need to specify the clusterDeploy goal.
3 To stop the cluster, you need to specify the clusterStop goal.

For a list and description of the parameters employed, see Cluster.

Deploying Multiple Applications

For a list and description of the parameters used in the examples, see below.

To deploy more than one application, you need to configure one plugin execution for each application to deploy.

<plugin>
    <groupId>org.mule.tools.maven</groupId>
    <artifactId>mule-maven-plugin</artifactId>
    <version>2.2.1</version>
    <configuration>
        <muleVersion>3.8.5</muleVersion>
        <deploymentType>standalone</deploymentType>
    </configuration>
    <executions>
        <execution>
            <id>deploy1</id>
            <phase>pre-integration-test</phase>
            <goals>
                <goal>deploy</goal>
            </goals>
            <configuration>
                <application>${app.1.location}</application>
            </configuration>
        </execution>
        <execution>
            <id>deploy2</id>
            <phase>pre-integration-test</phase>
            <goals>
                <goal>deploy</goal>
            </goals>
            <configuration>
                <application>${app.2.location}</application>
            </configuration>
        </execution>
        <execution>
            <id>undeploy1</id>
            <phase>post-integration-test</phase>
            <goals>
                <goal>undeploy</goal>
            </goals>
            <configuration>
                <application>${app.1.location}</application>
            </configuration>
        </execution>
        <execution>
            <id>undeploy2</id>
            <phase>post-integration-test</phase>
            <goals>
                <goal>undeploy</goal>
            </goals>
            <configuration>
                <application>${app.2.location}</application>
            </configuration>
        </execution>
    </executions>
</plugin>

Skipping Plugin Execution

When true, skip causes plugin execution to be skipped. This property works with all plugin goals. The most common scenario is to configure its value to skipTests, so that you don’t need to prepare your test infrastructure when you do not want your tests to run.

<plugin>
    <groupId>org.mule.tools.maven</groupId>
    <artifactId>mule-maven-plugin</artifactId>
    <configuration>
        <muleVersion>3.8.5</muleVersion>
        <deploymentType>standalone</deploymentType>
        <skip>${skipTests}</skip>
    </configuration>
    <executions>
        <execution>
            <id>deploy</id>
            <phase>deploy</phase>
            <goals>
                <goal>deploy</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Anypoint Runtime Manager On Premises TLS Errors

When trying to connect to an instance of the 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 trust store, 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 insecure connection is a very risky practice. You shouldn’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>
    <groupId>org.mule.tools.maven</groupId>
    <artifactId>mule-maven-plugin</artifactId>
    <configuration>
        <deploymentType>arm</deploymentType>
        <muleVersion>${mule.version}</muleVersion>
        <username>${username}</username>
        <password>${password}</password>
        <applicationName>my-application</applicationName>
        <environment>Production</environment>
        <uri>https://anypoint.mulesoft.local</uri>
        <armInsecure>true</armInsecure>
    </configuration>
    <executions>
        <execution>
            <id>deploy</id>
            <phase>deploy</phase>
            <goals>
                <goal>deploy</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Full List of Parameters

The following tables list all available parameters that you can use. Parameters are grouped by the element or configuration that you can use them for:

Standalone

Parameter Description

application

The application’s filepath. If not specified, the result of the Maven build is used as the default.

applicationName

The application name to be used for the deployment. If not specified, uses the value of artifactName.

arguments

Arguments to be passed to the Mule runtime at the command line:

Syntax:

<argument>-M-DmyArgument=myValue</argument>

community

If set to true, this downloads the community runtime instead of the Enterprise.

deploymentTimeout

Deployment timeout in milliseconds.

libs

External JARs to be added to <MULE_HOME>/user/lib.

Example:

<lib>${basedir}/activemq-core.jar</lib>

muleVersion

The Mule version to download and extract. Not needed if you specify muleHome.

muleHome

The path to your Mule installation, a Mule distribution needs to be present at this location. Not needed if you use muleVersion.

Cluster

Parameter Description

application

The application’s filepath. If not specified, the result of the Maven build is used as the default.

applicationName

The application name to be used for the deployment. If not specified, uses the value of artifactName.

arguments

Arguments to be passed to the Mule runtime at the command line.

Syntax:

<argument>-M-DmyArgument=myValue</argument>

deploymentTimeout

Deployment timeout in milliseconds.

libs

External JARs to be added to <MULE_HOME>/user/lib

Example:

<lib>${basedir}/activemq-core.jar</lib>

muleVersion

The Mule version to download and extract.

Runtime Manager

Parameter Description

application

The application’s filepath. If not specified, the result of the Maven build is used as the default.

applicationName

The application name to use for the deployment. If not specified, uses the value of artifactName.

businessGroup

Specifies the path to the business group you want to deploy to, if any. The default is the main organization.

Example:

<businessGroup>main\subOrg1\subOrg2</businessGroup>

environment

The Anypoint environment to deploy to.

muleVersion

The Mule version to download and extract. The muleVersion parameter takes the exact value of what you see in CloudHub’s ‘runtime version’.

Example:

<muleVersion>API Gateway 2.2.0</muleVersion>

username

Anypoint Platform username.

password

Anypoint Platform password.

target

Target server name.

targetType

Target server type, specified as one of server, serverGroup, cluster.

uri

Anypoint Platform URI, by default anypoint.mulesoft.com.

CloudHub

Parameter Description

application

The application’s filepath. If not specified, the result of the Maven build is used as the default.

applicationName

The application name to use for the deployment. If not specified, the value of artifactName is used.

businessGroup

Specifies the path to the business group you deploy to, if any. The default is the main organization.

Example:

<businessGroup>main\subOrg1\subOrg2</businessGroup>

environment

The Anypoint environment to deploy to.

muleVersion

The Mule version to download and extract. The muleVersion parameter takes the exact value of what you see in CloudHub’s ‘runtime version’.

Example:

<muleVersion>API Gateway 2.2.0</muleVersion>

username

Anypoint platform username.

password

Anypoint platform password.

properties

Cloudhub properties to configure. Each nested element inside <properties> is considered a property name and its value is its text.

Example:

<properties>
   <key1>value1</key1>
   <anotherKey>this is a value</anotherKey>
</properties>

This creates two properties in the Runtime Manager console: key1=value and anotherKey=this is a value. Note that the properties you specify override existing properties for this application in the Runtime Manager.

The properties defined here override the properties set in the mule-app.properties file of your application.
If you choose to add a property here, make sure to also add the ones you are declaring in mule-app.properties.

region

Region where you want your worker(s) to be created. See available regions for a list of accepted values.

uri

Anypoint platform URI, by default anypoint.mulesoft.com.

workerType

Size of the worker(s) specified as one of: Micro (0.1 vCores), Small (0.2 vCores), Medium (1 vCores), Large (2 vCores), xLarge (4 vCores). Note that the value is case sensitive.

Example:

<workerType>Small</workerType>

workers

Number of workers to create.

Agent

Parameter Description

application

The application’s filepath. If not specified, the result of the Maven build is used as the default.

applicationName

The application name to use for the deployment. If not specified, the value of artifactName is used.

uri

Local URI where the agent is listening.

Skipping Maven Deployment

Executing deploy phase also triggers the default deploy goal of the maven-deploy-plugin. If you are not deploying to a Maven repository as part of your build, you can prevent the plugin execution by using:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-deploy-plugin</artifactId>
  <configuration>
    <skip>true</skip>
  </configuration>
</plugin>