Dashboard

Table of Contents

1. Overview
   • Current Functionality
   • Planned Functionality
   • Screenshots
2. Get the Code
   • Latest Release
   • Latest Development Version
   • Git
3. How to Install
   • Optional Configuration Properties
     • enableLogin Property
4. History and Development Considerations
   • Release History
5. Additional Information and Common Errors

Overview

The Mach-II Dashboard is a Mach-II module that is designed to assist developers create and manage the development of applications. The Dashboard version 1.0.1 requires Mach-II 1.6 series only and version 1.1.0 requires Mach-II 1.8 series only. As of Mach-II 1.9, the dashboard is part of the core download.

Current Functionality

• Basic authentication (login page)
• Reload base application or individual modules
• Reload base ColdSpring bean factory or individual child factories
• Reload individual listeners, plugins, filters or properties (Dashboard 1.1.0 and requires Mach-II 1.8.0)
• Manage logging
• Manage caching including charts of logging statistics
• Recent exception snapshots for easy debugging
• Basic server and application configuration information
• JVM memory usage including charts of memory usage
• Auto-update of Dashboard and Framework packages through mach-ii.com (partially completed in Dashboard 1.1.0 and requires Mach-II 1.8.0)
• Development tools
  • RegEx tester (1.1.0)

Planned Functionality

• Development tools
  • Support for drag-n-drop developer created tools through override XML and includes
• Log file viewer
• Cluster administration
• JS / UI improvements

Screenshots

        <td><a href="wiki-attachment/Dashboard/dashboard_caching.png"><img width="75%" title="Image: Dashboard Caching" alt="Image: Dashboard Caching" src="wiki-attachment/Dashboard/dashboard_caching.png"></a></td>
        <td><a href="wiki-attachment/Dashboard/dashboard_debugging.png"><img width="75%" title="Image: Dashboard Debugging" alt="Image: Dashboard Debugging" src="wiki-attachment/Dashboard/dashboard_debugging.png"></a></td>
        <td><a href="wiki-attachment/Dashboard/dashboard_regex.png"><img width="75%" title="Image: Dashboard RegEx Tester" alt="Image: Dashboard RegEx Tester" src="wiki-attachment/Dashboard/dashboard_regex.png"></a></td>
    </tr>
</tbody>

Info	Config	Logging	Caching	Debugging	RegEx Tester

Get the Code

The 1.0.1 version of the Dashboard is currently stable for Mach-II 1.6 series only. The 1.1.0 version of the Dashboard is currently stable for Mach-II 1.8 series only.

Latest Release

• Mach-II Dashboard 1.0.1 Stable for Mach-II 1.6.0 only (9/24/2010)
• Mach-II Dashboard 1.1.0 Stable for Mach-II 1.8.0/1.8.1 (9/24/2010)

Latest Development Version

• As of Mach-II 1.9, the dashboard is integrated as part of the core download. Use the latest BER / milestone to enjoy.

Git

• Url: https://github.com/Mach-II/Mach-II-Framework/tree/master/1-9-0/trunk/dashboard
• No username / password required for anonymous read-only access

How to Install

• Download the dashboard code from one of the resources above

• Unzip the dashboard to your web root.

  1. For example, on Windows the default web root is [DRIVE]:\Inetpub\wwwroot, or if you are using your CFML server's built-in web server, your web root is likely [DRIVE]:\CFusionMX\wwwroot. If you are on a Unix system, your web root will vary.
  2. The end result of this step is that you should have the directory MachIIDashboard (no hyphen) in your web root. Inside this directory you will find the dashboard files.
  3. If you wish to place the core Mach-II Dashboard files in a location that is different from your webroot, just create a mapping called MachIIDashboard in the CFML administrator / control panel that points this mapping to the location where you placed the dashboard files.

• Add the dashboard as a module in your Mach-II application configuration file and set the password in the override XML section:

    <modules>
        <module name="dashboard" file="/MachIIDashboard/config/mach-ii_dashboard.xml">
            <mach-ii>
                <properties>
                    <property name="password" value="PLACE YOUR PASSWORD HERE" />
                </properties>
            </mach-ii>
        </module>
    </modules>

• Reload your Mach-II application and navigate to:

    http://www.example.com/index.cfm?event=dashboard:info.index

(You may have to modify this url if you use a different event parameter other than "event")

Optional Configuration Properties

There are a few optional configuration properties that can be added to change the behavior of the Dashboard at runtime.

enableLogin Property

This property allows you to disable the login page. By default, this is set to true if you do not specify this property. You can disable the login page like this:

    <modules>
        <module name="dashboard" file="/MachIIDashboard/config/mach-ii_dashboard.xml">
            <mach-ii>
                <properties>
                    <property name="password" value="PLACE YOUR PASSWORD HERE" />
                    <property name="enableLogin" value="false" />
                </properties>
            </mach-ii>
        </module>
    </modules>

However, this could potentially be a large security whole in your application if your application is deployed to production in this manner. If you are using Mach-II 1.8, you enable the login page by environment group or explicit environment name. The following example disables the login page for all environments that belong to the "local" and "development" environment groups and an explicit environment name "fooBar". If your application is deployed to an environment that does not match any of the environment listed, the login page will be *enabled* by default as this provides the most secure option.

    <modules>
        <module name="dashboard" file="/MachIIDashboard/config/mach-ii_dashboard.xml">
            <mach-ii>
                <properties>
                    <property name="password" value="PLACE YOUR PASSWORD HERE" />
                    <property name="enableLogin">
                        <struct>
                            <key name="group:local,development" value="false"/>
                            <key name="fooBar" value="false"/>
                        </struct>
                    </property>
                </properties>
            </mach-ii>
        </module>
    </modules>

Note that environment groups use the "group:" syntax in the key name. This can contain a list of environment groups. Also, explicit environments can be defined as a list as well. Environment value resolution is always performed by explicit environment name, then environment group and finally the default value (in this case "true") if no environment resolution can be found. Environment value resolution is only available in Mach-II 1.8+.

History and Development Considerations

The Mach-II Dashboard grew out of a simple module originally written by Peter Farrell that allowed you to reload Mach-II modules and ColdSpring bean factories. This was never released to the public, however that module was used as the basis for the Mach-II Dashboard. During the development of Mach-II 1.6, Team Mach-II realized that there was a need to programmatically control features such as the Mach-II caching and logging packages. Under continued development, the Mach-II Dashboard has already proved itself to be an invaluable tool for developing and managing Mach-II applications.

The dashboard was design to run as an module (independent sub-application) from your base Mach-II application. Since the dashboard is not designed to be a high-traffic module, we decided to serve all images, CSS and javascript files by serving them through a Mach-II event-handler using <cfcontent>. This allows developers to easily deploy the dashboard without having to copy image, CSS and javascript assets to a web-accessible location in your web root.

Release History

Version	Stable Release Date	Lead Developers	Framework Versions
1.0.0 Stable	5/12/2009	Peter Farrell, Kurt Wiersma	1.6.0 only
1.1.0 RC1	8/2/2010	Peter Farrell, Kurt Wiersma, Derrick Jackson	1.8.0+
1.0.1 Stable	9/24/2010	Peter Farrell, Kurt Wiersma, Derrick Jackson	1.6.0
1.1.0 Stable	9/24/2010	Peter Farrell, Kurt Wiersma, Derrick Jackson	1.8.0/1.8.1

Additional Information and Common Errors

• You must use the new MachII.properties.ColdSpringProperty included with Mach-II 1.6 for ColdSpring integration to work in the Dashboard otherwise the dashboard will report that there no ColdSpring available. This is because the ColdSpringProperty bundled with Mach-II includes functionality that is utilized by the dashboard.
• The config page show the status of Mach-II and ColdSpring configuration files. It does not report if a CFC file has changed; only if a configuration file has changed.