One Ring Install

1. One Ring Install

Installing One Ring is as simple as any Java EE web app, and simpler than most. Here’s the quick way to get running with Tomcat:

These builds work with Java 7. Make sure you have Java 7 installed.

If you haven’t installed tomcat before, I recommend downloading the .zip package including tomcat below and just unpacking it to get started.

Install Tomcat. see http://tomcat.apache.org/
Copy the war rulesEngine-1.0.1.war file to the webapp folder as rulesEngine.war

OR download one-ring-1.0.1-tomcat-7.0.22.zip and unzip it somewhere

Make sure java is in your path and run apache-tomcat-7.0.22/bin/startup.sh
Point your browser at http://localhost:8080/rulesEngine and you see the One Ring web interface after a short wait
Edit rules in your editor and copy to the One Ring servers rules directory - by default at [server home directory]/.OneRing/rules
Go to the web interface, click the rules menu link, then click the update menu item to read the new rule sets into the engine

If you are installing on Windows you need to create a c:\tmp directory (or d:\tmp). The complete set of RuleSets are copied into rules.groovy in \tmp to assist with debugging. (This will be fixed shortly https://github.com/nerdErg/One-Ring/issues/4)

If you’ve installed it on any other server please consider writing up how you did it to share here :-)

2. Configuration

There is one configuration option: rulesDirectory, which tells One Ring where to load the rules from.

You can set the directory in a configuration file or via JNDI. To set it in JNDI make a context .xml file in the [tomcat home]/conf/Catalina/localhost/ directory called rulesEngine.xml that looks like this:

rulesengine.xml

<Context>
<Environment name="rulesDirectory" value="[some path to rules dir]/testRules"
    type="java.lang.String" override="false"/>
</Context>

To use a configuration file you need to create a properties file called oneRing.properties then tell the web app where to find it by setting a system environment variable called ONE_RING_CONFIG, e.g.

# export ONE_RING_CONFIG=/[path to the file]/oneRing.properties

In the oneRing.properties file you only need one line:

oneRing.rules.directory=[some path to rules dir]/testRules

3. Recommended Setup

We started out with One Ring editing the rules and storing them in the HSQL database, however this doesn’t provide a robust control over changes and the ability to test and transfer. We decided to fall back on the existing infrastructure we use every day to develop software, Version Controlled files. This lets us use our IDE or favourite editor to edit the rules, save the latest version in Git, use our Continuous Integration server to test and possibly deploy the rules, and helps with deployment. So out went the editor and we split out the rules engine so that it can be used in the IDE or and script with jUnit to test your rules.

We recommend you set-up something like this:-

On your development system (rule designer) install an IDE or editor that understands groovy
Associate files with the extension ".ruleset" with Groovy in your IDE
Create a Groovy (or Java) project with a source directory for your rules
Copy the engine.jar to the projects lib directory
Create a Git (or mercurial) repository for your rules
Create a unit test file like the following to test your rules

TestRules.groovy

import com.nerderg.rules.RulesEngine
import com.nerderg.rules.RulesetDelegate
import groovy.io.FileType

/**
 * User: pmcneil
 * Date: 18/10/11
 *
 */
File dir = new File(".")
def nameMatch = ~/.*\.ruleset/
int count = 0
long startProcess = System.currentTimeMillis()
try {
    dir.eachFileRecurse(FileType.FILES) { File ruleFile ->
        if (ruleFile.name ==~ nameMatch) {
            count++
            println "Processing RuleSet File ${ruleFile.absolutePath}"
            List<RulesetDelegate> ruleSets = RulesEngine.processRules(ruleFile)
            assert ruleSets.size() > 0
            List fails = RulesEngine.testRuleset(ruleSets[0])
            fails.each {
                println "$it"
            }
            println '---------'
            assert fails.size() == 0

            ruleSets.each { RulesetDelegate rsd ->
                rsd.runRules([testdata: 'fred.jpg'])
            }
        }
    }
} catch (AssertionError e) {
    println e
    System.exit(-1)
}
println "Tested $count rules in " + (System.currentTimeMillis() - startProcess) + "ms"

Once you have written and tested your rules push them to a central repository (like Github or Bitbucket or you own private repo). From the central repository your CI server can pull down the rules and test them. You can then go to your test One Ring server, change to the rules directory and pull the changes in. Then its simply a matter of updating the rules via the web interfaces "update" menu link. You can automate all of this via Jenkins (CI server).

Once you’re happy with the tests you can push or pull the rule changes to your production server and "update" it.