brooklyn Introduction

brooklyn is a library that simplifies application deployment and management. It allows you to:

  • Describe an application topology once, and use this definition to set it up (provision) and keep it up (manage)
  • Describe the application topology in code, for re-use, version control, power and readability
  • Run multiple tiers and even varying stacks, configured and managed together
  • Run in multiple locations with efficient, secure, wide-area management


This guide requires that you have the Java 6 JDK, curl, wget and Maven 3 installed.

If you are using Eclipse, you will likely want the Git, Groovy, and Maven plugins. Via Help -> Install New Software, or from the Eclipse Marketplace, we recommend:

For more information and other development environments, visit the IDE section of the brooklyn web site.

Web Cluster and Database Example

Here is an example class which uses the Brooklyn library to launch a three-tier application in the cloud, complete with management:

public class WebClusterDatabaseExample extends AbstractApplication {
    ControlledDynamicWebAppCluster webCluster = new ControlledDynamicWebAppCluster(this,
        war: "classpath://hello-world-webapp.war");

    MySqlNode mysql = new MySqlNode(this,
        creationScriptUrl: "classpath://visitors-database-setup.sql");
            httpPort: "8080+",
                // -Dbrooklyn.example.db.url="jdbc:mysql://\\&password=br00k11n"
                ["brooklyn.example.db.url": valueWhenAttributeReady(mysql, MySqlNode.MYSQL_URL,
                    { "jdbc:"+it+"visitors?user=brooklyn\\&password=br00k11n" }) ]);
            new ResizerPolicy(DynamicWebAppCluster.AVERAGE_REQUESTS_PER_SECOND).
                setSizeRange(1, 5).
                setMetricRange(10, 100);

This consists of a JBoss web-app tier behind an nginx load-balancer (built up in the class ControlledDynamicWebAppCluster), connected to a MySQL database instance.

The web.factory.configure call tells the appservers to run on the first available port >= 8080 (which will be 8080 except when running multiple instances on localhost), and wires the URL where the database is running in to the app servers. The MySQL URL is exposed as an attribute sensor, as soon as the MySQL instance is started, and the valueWhenAttributeReady call sets up a Java Future so that the provisioning of the appservers can proceed as much as possible until the value is actually required. This "just-in-time" approach to dependent configuration simplifies -- as much as possible -- some of the trickiest issues when setting up sophisticated applications.

A management plane is launched with the application, running the policy configured with the web.cluster.addPolicy command (as well as other policies which ensure the load-balancer is updated whenever the web.cluster members change). Keeping a handle on the application instance allows programmatic monitoring, manual management, and policy change; the management plane can also be accessed through a command-line console, a web console, or a REST web API. The management web console shows the hierarchy of entities active in real-time -- from a high-level view all the way down to the level of each JBoss process on every VM, if desired.