Nav
You are viewing an older version of this section. Click here to navigate to the latest version.

Installing the Management Console

The Mule Management Console in a Web app designed to run in an application server or container, such as Tcat Server or Apache Tomcat, and usually packaged in a .war file.

This document describes where to download the required files and how to install or deploy these files for different application servers. Please contact the MuleSoft Support Team with any questions about downloading and deploying Mule Management Console.

*Trial Version vs. Production Version

Please note that if you have downloaded MuleSoft’s bundled runtime download - ESB with Mule Management Console (MMC) - it is appropriate for use only as an evaluation tool and is not considered production-ready.

To deploy the trial version, after downloading the appropriate zip archive file for your Windows, Mac, or Linux platform, all you need to do is extract the contents of the zip file and start Mule. Then, log in to the console by pointing your browser to this URL: http://localhost:8585/mmc. The username is admin and the password is admin.

(For instructions on setting up Mule for the first time, see Downloading Mule ESB.)

To use Mule Management Console for stress testing or in a production environment, download the necessary file from MuleSoft’s customer portal and deploy the console application on an application server, such as Tomcat.

Assumptions

This documents assumes that you have Mule Enterprise 3.3.x already installed. Download it from the customer portal if you need to upgrade this version. If you are using Mule Enterprise 3.4.x, please switch to the 3.4x version of this documentation.

This document also assumes that you have Web application server such as Tcat, Tomcat, or JBoss installed. Please refer to the Hardware and Software Requirements for the latest information about hardware requirements and supported application servers, Java Runtime Environments, and browsers.

Installation and Deployment Checklist

To install the Management Console:

  1. Download the Mule Management Console application (.war file) and the Management Console agent application (.zip file) from the MuleSoft customer portal.

  2. Rename your .war file to mmc.war

    Why?

    The name of the WAR file will vary depending on the version that you download, following the format <console_name>-<version>.war. Once you have downloaded this file from the customer portal, change the name to mmc.war. All instructions below assumes that your WAR file has been renamed mmc.war. If your file is named differently, note that the URL that you use to access the console will change accordingly. For example, if your war file is named mmc-foobar.war, you would need to use http://localhost:8080:mmc-foobar to access the console.

  3. Copy the Management Console agent .zip file to the the apps directory of each Mule ESB instance that you want to manage.

    If your Mule instance is packaged as a Web app, click here for alternate instructions

Special Instructions for Embedded Mode

You can also deploy the Management Console agent in a Mule ESB instance packaged as a Web app.

Note that when embedded, Mule does not support the Mule Deployment Model or High Availability. Furthermore, because the application server needs control of Mule, the Mule Management Console’s capabilities are reduced; specifically, you cannot restart the server via the Mule Management Console.

You must ensure that the class path for the Mule Web application includes the Management Console agent JAR file and the necessary files required for any additional Mule modules.

To integrate the agent on a Mule ESB instance running as a Web application, add to the libraries folder the following .jar files:

mmc-agent-mule3-impl-<latest Mule ESB version>-full.jar

mule-module-cluster-ee.jar

mule-module-tracking-ee.jar

You can obtain the .jar files from the customer portal.

A specific listener should be added to the file web.xml, as follows:


          
       
1
<listener> <listener-class>com.mulesoft.mmc.agent.web.MmcAwareContextListener</listener-class> </listener>

If your web.xml includes:


          
       
1
2
<listener> <listener-class> org.mule.config.builders.MuleXmlBuilderContextListener </listener-class> 
</listener>

…​you need to remove it. Otherwise the same Mule app would start twice.

  1. Deploy your mmc.war file to your application server or other container. See specific instructions for each supported container in the following section.

  2. Optionally, perform additional configuration to use an external database, change the default folder for mmc.data or configure a different default port and server ID.

Deployment Instructions for Specific Web Application Server/Containers

Since the procedure for deploying Web apps varies by container, you should refer to your container’s documentation for complete information of deploying Web apps.

Deploying the Management Console .war in Tcat/Tomcat

You can deploy the Management Console and your Mule applications inside Tomcat/Tcat without any modifications, other than specifying JVM parameters.

See TCat Server Documentation for instructions on how to deploy Web applications inside of Tcat.

After your JVM parameters in Tomcat as follows:

For Windows:

  1. Create a file named setenv.bat in the $TOMCAT_HOME\bin directory.

  2. Copy the following string into the file:

    setenv JAVA_OPTS=-Xmx1024m -XX:MaxPermSize=512m

  3. Save the file

For MacOS/Linux:

  1. Create a file named setenv.sh in the $TOMCAT_HOME/bin directory.

  2. Copy the following string into the file:

    
                 
              
    1
    2
    3
    
    #!/bin/sh
     
    setenv JAVA_OPTS=-Xmx1024m -XX:MaxPermSize=512m
  3. Save the file

  4. Make it executable, for example with the command chmod u+x setenv.sh.

We recommend running on a IPv4 stack. Tomcat will run by default with IPv6, so in order to specify IPv4 instead, add the following line to the setenv.sh file:


          
       
1
-Djava.net.preferIPv4Stack=true

Be sure not to run programs on your system that try to bind to the same port using different versions of the IP protocol.

For Tomcat, first deploy the mmc.war file by copying it to your Tomcat /webapps directory. Tomcat, when started, deploys the Management Console application. You should see a mmc folder in the Tomcat /webapps folder after Tomcat deploys the console Web application.

Deploying the Management Console .war in JBoss

Due to JMX conflicts generated by an old MBeanServer implementation, you must configure JBoss to use the Java5 MBeanServer. You do this by providing the -Djboss.platform.mbeanserver parameter in the startup command. For example:


          
       
1
./run.sh -c all -Djboss.platform.mbeanserver

On Windows, before startup, ensure that environment variable JAVA_OPTS contains:


          
       
1
-Djboss.platform.mbeanserver-Djavax.management.builder.initial=org.jboss.mx.server.MBeanServerBuilderImpl

Note, too, that memory-related JVM options are still mandatory. For instance:


          
       
1
export JAVA_OPTS="-XX:MaxPermSize=512m -Xmx1G"

You may also try specifying smaller memory parameters depending on your environment, such as:


          
       
1
export JAVA_OPTS="-XX:MaxPermSize=300m -Xmx256m"

To successfully deploy the console JBoss 6, you need to remove the following files from JBoss:

  • common/lib/quartz.jar

  • server/<your_profile>/deploy/quartz-ra.rar, where <your_profile> is your server profile.

Starting the Management Console

To run the Management Console, make sure your container is running and the Management Console Web app has been deployed correctly. Then enter http://localhost:8080/mmc in your browser. (Note that if you are using the trial version, the default port is 8585 instead of 8080.) If you see the login screen (see below), you installed correctly and are now running the console.

MMC_login

If another app is using port 8080, you can change the port in your container’s configuration (such as the /conf/server.xml file under your Tomcat home directory). If you want to run the Management Console remotely from another computer, enter the correct name (or IP address) of the host computer instead of localhost.

When you start the Management Console for the first time, you can log in with the username admin and the password admin.

Additional Configuration

By default, the Management Console uses its own internal database; however, you can configure it to use an external database, which can be useful for disaster recovery.

See Persisting Environment Data for instructions on how to set up the Management Console to use an external database for storing environment information, such as users, groups, applications, etc.

See Persisting Transaction Data for instructions on how to set up the Management Console to use an external database for storing transaction data (Business Events).

Configuring a Custom Folder for mmc-data

To specify a new folder for mmc-data, use the following parameter in the Mule startup command:


          
       
1
<MULE_HOME>/bin/mule -M-Dmmc.data=<path>

For example:


          
       
1
<MULE_HOME>/bin/mule start -M-Dmmc.data=/opt/mule/3.4.0/data/mmc-data

Customizing the Agent Configuration

You may want to configure a different default port for agent communication, or a different server ID before running Mule.

You can change the agent configuration from that of the default URL, which is displayed when registering a new server instance. The agent configuration determines the bind port for the server instance. You may wish to change the agent URL if you want to start multiple instances of Mule ESB within the same box and connect the console to these different instances, or if you want to connect to remote server instances.

Unless a port is specified, the console will look in the 7777-7877 port range and bind the first free port by default. When you start Mule from a command line, you can change the port to which the server binds. You specify the new port as a switch or option in the command used to start Mule, as follows:


          
       
1
-M-Dmule.mmc.bind.port=7773

For example:


          
       
1
/opt/mule/3.4.0/bin/mule start -M-Dmule.mmc.bind.port=7773

You may also specify a custom port range, as follows:


          
       
1
-M-Dmule.mmc.bind.port=7783-7883

In addition, when you change the agent bind port to accommodate multiple Mule instances, you also must start Mule from the bin directory that corresponds to the particular Mule instance. For example, you might run a second instance of Mule as follows, where this second instance is installed at /opt/second_mule:


          
       
1
/opt/second_mule/bin/mule -M-Dmule.mmc.bind.port=7773

Disabling the Management Console Agent at Startup

To disable the Management Console agent on Mule ESB startup, use the mule.agent.enabled property as shown below:


          
       
1
-M-Dmule.agent.enabled=false

The agent is enabled by default.

See Also