Deploying Tomcat/Grails Apps to Cluster with Bear

Introduction

This article shows how to quickly setup a Bear project to be able to deploy and run a Tomcat/Grails app.

• Install software to a cluster: JDK, Maven, Tomcat, Grails, etc.
• Deploy your application to the installed infrastructure
• Manage Tomcat hosts & instances: start, stop, check status

A complete demo can be found at the Bear's GitHub project page. If by chance you would like to run this example, a simpler way could be to modify this demo for your case and run it.

Background

Bear is a lightweight remote automation tool for Groovy/Java/JVM. Bear differs from other existing tools in that it's using programmatic approach. In Bear, your deployment is a regular Java class which may have it's main(). Bear loves static type safety, chained method calls, FP and fluent programming techniques.

Installing Bear

Bear requires:

• 1+ remote machine with Linux, standard password authentication
• JDK 8 (recommended for UI), JDK 7+ to run console/UI
• Maven 3+. mvn must be available in the command line.

How to install Maven on Windows

To install Bear, type in your command line (admin rights might be needed):

$ mvn com.chaschev:installation-maven-plugin:1.4:install -Dartifact=com.chaschev:bear

Creating a Project

To create a new Bear project, in your existing project or just in an empty folder:

$ cd pet-clinic
$ bear --create pet-clinic --user my-actual-ssh-user --password my-actual-password --host my-remote-host

This will create a folder .bear with auto-generated project files.
Note: Password storage is unsafe in the current version. If you want to store your password locally in a file, you might want to edit .bear/petclinic.properties file.

Next, if you have more than one host, edit hosts and stages in the created project in file .bear/PetClinicProject.groovy. To quickly check the setup, run:

$ bear pet-clinic.ls

This will launch a predefined ls job which is a regular method of a Java Class marked with @Method annotation. This should show the UI:

Next, you could run smoke tests to make sure that everything is ok.

Adding Plugins

You can edit a Bear project in your favourite Java IDE or in a text editor. There is an instruction of how you could do this with Intellij Idea. If you want to edit your Bear project in Eclipse or Netbeans and have trouble editing Groovy classes, you could convert it to Java and edit it as a Java class.

Plugins are added by declaring fields in a Bear project of the plugin type. Plugin instances will be injected during project initialization:

JavaPlugin java
MavenPlugin maven                  // optional, will install Maven
GitCLIPlugin git
MySqlPlugin mysqlPlugin
DeploymentPlugin deployment        // deployment builder, a Builder class to glue the plugins together
DumpManagerPlugin dumpManager      // optional, can be used for defining DbDump jobs
TomcatPlugin tomcat
GrailsPlugin2 grails

Now let's see how versions are set for tools variables are linked:

@Override
protected GlobalContext configureMe(GlobalContextFactory factory) throws Exception {
  maven.version.set("3.1.1");

  java.versionName.set("jdk-7u51-linux-x64");
  java.version.set("1.7.0_51");

  grails.version.set("2.1.1")

  tomcat.instancePorts.set("8080, 8081")      // this will create 2 Tomcat instances on each host
  tomcat.warName.setEqualTo(grails.warName);  // links tomcat war-name to deploy to grails war-name

  dumpManager.dbType.set(mongo.name());       // DB type for dump manager: mysql or mongodb

  bear.appStartTimeoutSec.set(600)            // override startup timeout for Tomcat}

Installing Software with project.setup

To install JDK remotely, you will need to manually download Oracle JDK distribution (not needed for a Node.js project) and put it to. In this example, we are using JDK 7u51:

• (Windows) c:\bear\shared\tools\jdk\jdk-7u51-linux-x64.gz
• (Unix) /var/lib/bear/shared/tools/jdk/jdk-7u51-linux-x64.gz

This will be scripted in future, for now the download is manual. Then in your console:

$ bear pet-clinic.setup --ui

Or in main():

new PetClinicProject().setup()

This will install and verify the software and will also make executables available from the command line.

Adding a Deployment

GitHub project address is set in the annotations:

@Configuration(
    ...
    vcs = "https://github.com/grails-samples/grails-petclinic.git",
    branch = "master"
    ...    
)

We are using DeploymentPlugin to build our deployment. Below is the description for the tasks. Each task is a function which is being run on each of the hosts.

• global.tasks.vcsUpdate - checkout or updates the project from GitHub
• grails.build - builds a WAR with Grails
• tomcat.stop, tomcat.start - starts/stops Tomcat instances
• tomcat.deployWar - unpacks WAR to Tomcat
• tomcat.watchStart - waits for the app to start by watching the logs
• _ - a universal object like $ in jQuery

defaultDeployment = deployment.newBuilder()
 .CheckoutFiles_2({_, task -> _.run(global.tasks.vcsUpdate); } as TaskCallable)
 .BuildAndCopy_3({_, task -> _.run(grails.build); } as TaskCallable)
 .StopService_4({_, task -> _.run(tomcat.stop); OK; } as TaskCallable)
 .StartService_6({_, task -> _.run(tomcat.deployWar, tomcat.start, tomcat.watchStart); } as TaskCallable)
 .endDeploy()
 .ifRollback()     // actions to take when there is an error
   .beforeLinkSwitch({_, task -> _.run(tomcat.stop); } as TaskCallable)
   .afterLinkSwitch({_, task -> _.run(tomcat.start, tomcat.watchStart); } as TaskCallable)
 .endRollback()

The whole thing looks a bit heavy, but it's hard to come with a shorter syntax for the same semantics. What it does is it assigns tasks to deployment phases which will be reused in other places, i.e., to start, stop or rollback the release.

Deploy and Manage Tomcat

To deploy your app, just type (main() version is always available):

$ bear pet-clinic.deploy --ui

When the deployment is finished, in your browser navigate to one of your hosts and if everything went well, there will be pets in green:

To stop or start the Tomcat instances, type:

$ bear pet-clinic.start --ui
$ bear pet-clinic.stop --ui

A complete demo can be found at the Bear's GitHub project page.

Points of Interest

The whole process might look tedious, but in reality you would just copy and modify the original project. And I believe it is much less annoying than configuring multi-instance Tomcat cluster manually, plus there are some other perks.

If at some point, you get bored by following the instruction, try exploring commands API (see Wiki), writing your own deployment or studying the source (eh... well, some things there are still in progress ;-)). Bear was written with keeping-it-simple in mind. If all you need is to build and copy a WAR to several hosts, then just do it!

In the following articles, I will write about quick Java cluster setup and an example of a simple 'no-deployment' build.

Cheers and good luck with your deployments!