Contact Us 1-800-596-4880

Mule Plugin for Maven

Mule Runtime Engine versions 3.5, 3.6, and 3.7 reached End of Life on or before January 25, 2020. For more information, contact your Customer Success Manager to determine how you can migrate to the latest Mule version.

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.

Adding the Plugin

Adding the Maven Dependency for the Plugin

Edit your settings.xml or project file to include the following:

<plugin>
  <groupId>org.mule.tools.maven</groupId>
  <artifactId>mule-maven-plugin</artifactId>
  <version>2.0</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 settings.xml or project file to include the following:

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

You can also find the plugin .jar and POM files manually at the online repository for the plugin, or get if from the Maven Central Repository.

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 settings.xml or pom.xml must include the repository where Mule is available.
<plugin>
    <groupId>org.mule.tools.maven</groupId>
    <artifactId>mule-maven-plugin</artifactId>
    <version>2.0</version>
    <configuration>
        <deploymentType>standalone</deploymentType>
        <muleVersion>3.7.0</muleVersion>
    </configuration>
    <executions>
        <execution>
            <id>deploy</id>
            <phase>deploy</phase>
            <goals>
                <goal>deploy</goal>
            </goals>
        </execution>
    </executions>
</plugin>

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.

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.0</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>

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.0</version>
    <configuration>
        <deploymentType>cloudhub</deploymentType>
        <!-- muleVersion is the runtime version as it appears on the CloudHub interface -->
        <muleVersion>3.7.0</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>

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

Selecting Your Business Group

In 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.0</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.0</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>

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>1.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.7.0</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.0</version>
    <configuration>
        <muleVersion>3.7.0</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 de applications and stop Mule server.

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.0</version>
    <configuration>
        <muleVersion>3.7.0</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.0</version>
    <configuration>
        <muleVersion>3.7.0</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.7.0</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 On-Premises installation of Anypoint Runtime Manager, the plugin validates certificates for that server. If you haven’t installed the server certificates in your trust store, you see an SSL error. To avoid this problem you can run the plugin in an insecure mode. In this way, the security validations are skipped. You can use the armInsecure tag or the arm.insecure system property. 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>
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.

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 use 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>

muleHome

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

muleVersion

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

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, the artifactName is used.

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, the value of artifactName is used.

businessGroup

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

Example:

<master><subOrg1><subOrg2>

environment

The Anypoint environment to deploy to.

username

Anypoint platform username.

password

Anypoint platform password.

target

Target server name.

targetType

Target server type.

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>

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 want to deploy to, if any. The default is the Master organization.

Example:

<master><subOrg1><subOrg2>

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.

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 the 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>