Several of the development teams that I work with often run into the same problem: each developer has their own method of deploying Mule applications. This can create a significant amount of confusion and can lead to broken applications. Without a standard deployment process, additional time is spent on alignment or fixing broken applications as a result of using different deployment models.
The blog series will outline how to build a common framework for building and deploying Mule applications for smooth and predictable deployment for every Mule solution your team creates. This framework will use Maven as this standardization tool.
Maven for Mule application deployment
Mule projects are compiled and packaged with Maven. It’s used for all Mule Runtime deployment models. Maven supports a rich set of functional extensions through a plugin architecture. Maven can be installed and executed on a developer’s workstation and as part of an automated pipeline, making it a natural for building our standard foundation.
All the examples use Maven 3.6.3 which is bundled with Anypoint Studio 7.8. Other Maven versions may work, they just haven’t been tested. The target Mule 4 runtime version is 4.2.2.
Step 1: Install the tools
- Install a Java JDK: Use one supported by Anypoint Studio (see the release notes for the versions required)
- Install Maven: Maven is embedded into Anypoint Studio, but we want to run Maven from the workstation command line prompt (see the installation instructions and download 3.6.3)
- Verify Java compile command: javac -version
- Verify Maven command: mvn -version
Step 2: Create two standard files
The next step is to standardize the settings.xml and pom.xml files. The goal is to create two files that can be used on any workstation for any project we are working on. We’ll structure the files to minimize (or eliminate) the need to customize them later.
Step 2a: Standardize settings.xml
The first file to standardize is the settings.xml file. See more details about the settings.xml file contents.
To create the standard file start by downloading the file. Copy it to the .m2 directory and name it settings.xml. The settings.xml file contains some generic information that you will need to change to create the “standard.” These values are unique to the organization you are going to use for deploying applications.
- master.org.name is treated as a comment.
- company.abbr is the prefix to application names in Runtime Manager and should end with -.
- my-organization-anypoint-orgid is the organization ID to which assets will be deployed.
- api.businessGroup is the business org in which is used to manage APIs.
- ap_id* is the Anypoint client ID found in the master org access management.
- ap_secret* is the Anypoint client secret found in the master org access management.
Edit the bold values:
<master.org.name>blogx</master.org.name>
<company.abbr>blogx-</company.abbr>
<my-organization-anypoint-orgid>${my_ap_orgid}</my-organization-anypoint-orgid>
<api.businessGroup>APIS</api.businessGroup>
<ap_id>${my_ap_clid}</ap_id><ap_secret>${my_ap_clid_secret}</ap_secret>
In the case of the ap_id and ap_secret, it is an option to leave these values as variables and pass the actual values on the Maven command line as -Dap_id=xx and -Dap_secret=xx values.
In the settings.xml, the <servers> section and these bold values should be changed to your organization’s MuleSoft Nexus repository settings:
In the case of the ap_id and ap_secret, it is an option to leave these values as variables and pass the actual values on the Maven command line as -Dap_id=xx and -Dap_secret=xx values.
In the settings.xml, the <servers> section and these bold values should be changed to your organization’s MuleSoft Nexus repository settings:
<username>${my_mule_nexus_user}</username>
<password>${my_mule_nexus_pw}</password>
You will also find ${u} and ${p} used in the server section. For now, leave those unchanged, we will pass those values on the Maven command line.
If you want to interact with a source code management system using Maven plugins, change the bold items to match your scm connection and url values. The provided example is for GitHub, your scm will have a different format for these values which you will have to determine from the Maven and SCM documentation. Here are the values to change:
<my_scm_connection_suffix>.git</my_scm_connection_suffix> <my_scm_connection_prefix>scm:git:ssh://git@github.com/xxx/</my_scm_connection_prefix>
<my_scm_url_prefix>git@github.com:xxx/</my_scm_url_prefix>
<my_scm_url_suffix></my_scm_url_suffix>
The punctuation is important as these values are concatenated with the artifactId to form the URL or connection reference to the project’s scm location.
Save your changes. The last set of changes define the Mule runtime deployment environments that will be used.
Locate the deployment configurations in the <profiles> section of the settings.xml. There is one profile for each ARM runtime environment. The starting file defines three profiles (dev, test, and prd) corresponding to development, test, and production deployment environments defined in Anypoint Platform. Each profile defines the attributes used by the Maven command to specify the specific runtime deployment properties required to deploy the application to a specific environment. This will make more sense when we look at the pom.xml file, for now take for granted the following attribute usage definitions:
- cloudhub.name is the name the application is given when deployed to CloudHub.
- hybrid.name is the name the application is given when deployed to Mule standalone.
- rtf.name is the name the application is given when deployed to Runtime Fabric.
- deploy.environment is the name of the Anypoint Platform environment to which the application is deployed. This is the name exactly as entered in the environment definitions (matching case).
- deploy.target is the name of the Mule standalone server, server group, or cluster.
- deploy.rtf-target is the name of Runtime Fabric.
- deploy.targetType is the type of Mule standalone (server, serverGroup, cluster).
- rtf.domain is the Runtime Fabric domain (host) name configured for the runtime fabric ingress.
- The setup in this configuration is assuming the configuration of the ingress uses a simple CN and not a wildcard in the TLS certificate. It’s used to form the URL name of the deployed application in Runtime Fabric.
Edit each of the profiles to correspond to the deployment specifics you will be using. You may need to create or rename profiles. These are case-sensitive names and the profile ID and the property env value should match each other. This allows us to specify which environment we want to deploy into by using -Denv=dev or -Denv=test or -Denv=prd on the mvn command line. Adding a new profile (for instance, rtf01-dev) enables -Denv=rtf01-dev to the deployment options.
This file is shared with other developers and installed on the build servers so that the standard is useful for everyone. Pay attention to what and how you share this file so that you do not accidentally expose the credentials such as client or Nexus credentials.
Step 2b: Standardize pom.xml
The second file to standardize is the pom.xml file. See details about the pom.xml file contents.
To create the standard file start by downloading the standard file and copy it to your desktop so it can be edited. For each Mule 4 project, we will use a copy of the standardized pom.xml. For now, we will overwrite the pom.xml generated by Anypoint Studio (copying the project-specific dependencies as needed).
Edit the file:
- Locate all ${my-organization-anypoint-orgid} and change to the Anypoint group ID deploying used for runtime management. Often this is the master org, but it may also be a business group.
- Add all the dependencies that will be used in your “typical” project to the <dependencies>. Later, make sure you include all the dependencies in a project’s pom.xml before you replace it with this standard version.
- Optionally, update the artifact-repo DistributionManagement section values with the values of the artifact repository you may be using besides Anypoint Exchange.
Save the changes. When you replace the pom.xml of a project with this standardized file, make sure to update the artifactId and version with the values from the current pom.xml. Also, make sure to include the dependencies and shareLibraries from the original pom.xml.
Using the standard Maven commands
With these standard files, we can now use standardized Maven commands to publish, test, and deploy. I’ve specified the most frequently used commands for each type deployment in the sections below. Replace the braced values with the actual values (for instance your Anypoint Platform user name and password).
Download Mule artifact dependencies
mvn clean package -DskipTests -Du={anypoint user name} -Dp={anypoint user password}
Deploy to CloudHub behind the shared public load balancer
mvn clean install deploy -DmuleDeploy -DskipTests -Pcloudhub -Ppublic-lb -Denv={dev,test,prd} -Du={anypoint user name} -Dp={anypoint user password}
Deploy to CloudHub behind the dedicated load balancer
mvn clean install deploy -DmuleDeploy -DskipTests -Pcloudhub -Pdlb -Denv={dev,test,prd} -Du={anypoint user name} -Dp={anypoint user password}
Deploy to Runtime Fabric
Deploying to Runtime Fabric requires two steps. The first step publishes the binary artifact to Exchange. The second step deploys the Exchange artifact to your Runtime Fabric.
mvn clean install deploy -Pexchange -DskipTests -Du={anypoint user name} -Dp={anypoint user password}
mvn mule:deploy -Dmule.artifact=dummy -Prtf -Denv={dev,test,prd} -Du={anypoint user name} -Dp={anypoint user password}
Deploy to hybrid (Mule standalone)
mvn clean install deploy -DmuleDeploy -DskipTests -Phybrid -Denv={dev,test,prd} -Du={anypoint user name} -Dp={anypoint user password}
What’s next?
The next step is to try this out on a Mule project. You can start with this sample project, simply download the source code and import it into Studio. You will need to make some changes to the pom.xml. The README.md file contains additional instructions for running the project in Anypoint Studio.
Then merge an existing project pom.xml into the standardized pom.xml and try the standard Maven commands. These standard Maven commands facilitate creating other standards for CI/CD pipelines.
The next blog in this series is a cheat sheet for the Maven commands available with this standard setup.
