Cloud Foundry now supports Play 2.0 as a first-class framework. Play is a lightweight, stateless, web-friendly framework for Java and Scala. Developers can leverage this event-driven non-blocking IO architecture to build highly scalable applications. Play 1.0 applications were previously deployable to Cloud Foundry as WAR files. Play 2.0, which doesn’t have built-in support for WAR files, can now be deployed to CloudFoundry.com and take advantage of being a fully supported framework that includes auto-reconfiguration, simplified service connections, and automatic database management. Play developers, welcome to Cloud Foundry!

Getting Started with Play 2.0

First, we will need to install or update the Cloud Foundry command line tool, VMC, to the latest version by using the following command:

gem install vmc

We can verify that we have the right version using:

vmc -v

which should show the version to be 0.3.18 or higher.

Now let’s get started with the Java zentasks sample found in the Play 2.0 distribution. We’ll run the “play dist” command which will compile our code, retrieve all the required dependencies and create a self-contained binary that can be uploaded to Cloud Foundry.

dev$: cd play-2.0.1/samples/java/zentasks
zentasks$: play clean dist
[info] Loading project definition from /Users/jencompgeek/development/resources/play-2.0.1/samples/java/zentasks/project
[info] Set current project to zentask (in build file:/Users/jencompgeek/development/resources/play-2.0.1/samples/java/zentasks/)
[success] Total time: 0 s, completed May 15, 2012 2:27:29 PM
[info] Updating {file:/Users/jencompgeek/development/resources/play-2.0.1/samples/java/zentasks/}zentask...
[info] Done updating.
[info] Compiling 10 Scala sources and 9 Java sources to /Users/jencompgeek/development/resources/play-2.0.1/samples/java/zentasks/target/scala-2.9.1/classes...
[warn] Note: Some input files use unchecked or unsafe operations.
[warn] Note: Recompile with -Xlint:unchecked for details.
[info] Packaging /Users/jencompgeek/development/resources/play-2.0.1/samples/java/zentasks/target/scala-2.9.1/zentask_2.9.1-1.0.jar ...
[info] Done packaging.

Your application is ready in /Users/jencompgeek/development/resources/play-2.0.1/samples/java/zentasks/dist/zentask-1.0.zip

Now we can deploy the application to Cloud Foundry with the VMC push command:

zentasks$: vmc push --path=dist/zentask-1.0.zip
Application Name: zentasks
Detected a Play Framework Application, is this correct? [Yn]:
Application Deployed URL [zentasks.cloudfoundry.com]:
Memory reservation (128M, 256M, 512M, 1G, 2G) [256M]:
How many instances? [1]:
Create services to bind to 'zentasks'? [yN]: y
1: mongodb
2: mysql
3: postgresql
4: rabbitmq
5: redis
What kind of service?: 3
Specify the name of the service [postgresql-38199]: tasks-db
Create another? [yN]:
Would you like to save this configuration? [yN]: y
Manifest written to manifest.yml.
Creating Application: OK
Creating Service [tasks-db]: OK
Binding Service [tasks-db]: OK
Uploading Application:
  Checking for available resources: OK
  Processing resources: OK
  Packing application: OK
  Uploading (186K): OK
Push Status: OK
Staging Application 'zentasks': OK
Starting Application 'zentasks': OK

Looks like zentasks deployed successfully. Let’s check the logs:

zentasks$: vmc logs zentasks
====> logs/stdout.log <====

Auto-reconfiguring default
Enabling JPA auto-reconfiguration
Play server process ID is 13269
[warn] play - Plugin [play.db.jpa.JPAPlugin] is disabled
[info] play - database [default] connected at jdbc:postgresql://172.31.244.70:5432/dd2c9bc5b72134998adcfe4dcfa6660f4
[info] play - Application started (Prod)
[info] play - Listening for HTTP on port 59907...

Our Play 2.0 application is up and running on Cloud Foundry in 2 simple steps, no modification required!

Like most Play applications, zentasks contains database evolutions. Cloud Foundry automatically applied these evolutions to the database on application start. But how was the app able to make use of the PostgreSQL service we provisioned and bound to the application during deployment? If we look at the application.conf file, we see that the application is configured to use an in-memory database:

db.default.driver=org.h2.Driver
db.default.url="jdbc:h2:mem:play"

Cloud Foundry actually used a mechanism called auto-reconfiguration to automatically connect the Play application to the relational database service. If a single database configuration is found in the Play configuration (for example, “default” from above) and a single database service instance is bound to the application, Cloud Foundry will automatically override the connection properties in the configuration to point to the PostgreSQL or MySQL service bound to the application.

This is a great way to get simple apps up and running quickly. However, it is quite possible that your application will contain SQL that is specific to the type of database you are using. For example, several of the samples that come with Play make use of sequences in evolution scripts. This, of course, works with the in-memory database and will also work on PostgreSQL, but it will not work on MySQL. In these cases, or if your app needs to bind to multiple services, you may choose to avoid auto-reconfiguration and explicitly specify the service connection properties.

Connecting to Cloud Foundry Services

As always, Cloud Foundry provides all of your service connection information to your application in JSON format through the VCAP_SERVICES environment variable. However, connection information is also available as series of properties you can use in your Play configuration. Here is an example of connecting to a PostgreSQL service named “tasks-db” from within an application.conf file:

db.default.driver=${?cloud.services.tasks-db.connection.driver}
db.default.url=${?cloud.services.tasks-db.connection.url}
db.default.password=${?cloud.services.tasks-db.connection.password}
db.default.user=${?cloud.services.tasks-db.connection.username}

This information is available for all types of services, including NoSQL and messaging services. Also, if there is only a single service of a type (e.g. postgresql), you can refer to that service only by type instead of specifically by name, as exemplified below:

db.default.driver=${?cloud.services.postgresql.connection.driver}
db.default.url=${?cloud.services.postgresql.connection.url}
db.default.password=${?cloud.services.postgresql.connection.password}
db.default.user=${?cloud.services.postgresql.connection.username}

We recommend keeping these properties in a separate file (for example “cloud.conf”) and then including them only when building a distribution for Cloud Foundry. You can specify an alternative config file to “play dist” by using “-Dconfig.file”.

Opting Out of Auto-Reconfiguration

There may be situations in which you would like to opt out of auto-reconfiguration. For example, you may have an in-memory database that should not be bound to a Cloud Foundry service. If you use the properties referenced above, you will automatically be opted-out. To explicitly opt out, include a file named “cloudfoundry.properties” in your application’s conf directory, and add the entry “autoconfig=false“.

Debugging Your Play Application

If you are using a local Cloud Foundry setup, you can remotely debug your Play applications. Simply use the flag “--debug” when doing a “vmc push” or “vmc start“. You can then run “vmc instances” to get the debug host and port information:

zentasks$: vmc instances
+-------+---------+--------------------+-----------------+------------+
| Index | State   | Start Time         | Debug IP        | Debug Port |
+-------+---------+--------------------+-----------------+------------+
| 0     | RUNNING | 05/15/2012 05:50PM | 192.168.193.193 | 59845      |
+-------+---------+--------------------+-----------------+------------+

Just use the displayed debug IP and port in the remote debugger in your favorite IDE and start debugging!

Conclusion

We look forward to seeing your Play applications on Cloud Foundry. Please feel free to send us feedback or submit a pull request to help us improve our support for the Play Framework. Now get started building those apps!

- Jennifer Hickey
The Cloud Foundry Team

Don’t have a Cloud Foundry account yet?  Sign up for free today

Update: Recent Changes in Node.js Modules Support

We are pleased to announce support for npm (Node Package Manager) which manages Node.js application module dependencies on CloudFoundry.com. The popularity of Node.js can be partially attributed to its strong ecosystem that has created modules for practically any programming task–from database access to payment processing. At present, there are over 10,000 node modules listed on search.nodejs.org. Any cloud that aspires to provide good support for Node.js needs to simplify the task of using node modules. With the addition of npm support, Cloud Foundry now makes it easier for you to manage modules for node applications.

The normal process of creating a Node.js application requires local installation of node modules (typically in the node_modules folder inside the application), essentially making the application self-contained. You can deploy this application locally or push all its contents, including the node modules, to CloudFoundry.com. This works fine as long as the app didn’t need a node module with native dependencies, which must be compiled specifically for the target platform. The npm support described in this blog obviates the need to package module dependencies with the app and makes it possible to use modules with native dependencies.

Requirements and Limitations

In order to use the npm feature, you would need to follow a few simple steps:

• The application must provide an npm-shrinkwrap.json file. This file can be generated with the npm shrinkwrap command and reflects the whole tree of dependencies with fixed versions. This file is a snapshot of application dependencies in the same way that Gemfile.lock serves Ruby applications. This guarantees that Cloud Foundry will provide the exact same node module versions, which avoids incompatibility issues and follows the same dependencies hierarchy.
• By default, Cloud Foundry uses node modules if the application includes them. More concretely, if an application has a node_modules folder in its base folder, then Cloud Foundry will simply use the modules in that folder. To overwrite the existing modules in the node_modules folder, you would provide a configuration file, cloudfoundry.json, with the “ignoreNodeModules” option set to true.

If the above conditions are met, Cloud Foundry will install node modules to the application during staging based on the module versions, application runtime version and npm version. If a required node module does not work with the node engine that the application is running on, the module will not be installed. Currently, in order to push the application with the node engine version 0.6.x, it needs to be explicitly specified during application push.

$ vmc push app-name --runtime=node06

If a module installation fails for some reason, Cloud Foundry will use the node module provided by the user. Besides the compatibility requirement outlined above, there may be other possible reasons for installation failures. For example, when a node module of a given version is not found in the npm registry. When an error occurs, information about the installation process along with any npm error messages can be found in the application logs.

$ vmc logs app-name
...
Installing dependencies. Node version 0.6.8
Failed getting the requested package: bcrypt@0.4.5

Note that although npm supports git URLs specified manually after npm-shrinkwrap.json was generated, Cloud Foundry currently does not support git URLs.

Native node modules

Cloud Foundry npm support also allows deployment of Node.js applications with native module dependencies. Many popular node modules such as bcrypt, fibers and nowjs have native code that depends on the platform. So locally installed node modules that were pushed along with the application would raise platform incompatibility errors often manifested as “invalid ELF header” errors during execution.

Now, if an application meets the above requirements for npm support, compiled native dependencies will be provided by Cloud Foundry to the application during an application push.

Example of npm support in action

Let’s see how npm support works. Here we have an application with the main file app.js:

var app = require("express").createServer();
var bcrypt = require("bcrypt");

app.get("/", function(req, res) {
  var salt = bcrypt.genSaltSync(10);
  var hash = bcrypt.hashSync("B4c0/\/", salt);
  if (bcrypt.compareSync("B4c0/\/", hash))
    res.send("World is safe!");
  else
    res.send("World is in trouble!");
});

var port = process.env.VCAP_APP_PORT || 3000;
app.listen(port);

And package.json that specifies our dependencies. In this example we use express, which depends on other node modules and native dependency, bcrypt.

{
  "name" : "node-dependencies-example",
  "version" : "0.1.0",
  "dependencies" : {
    "express" : "2.5.x",
    "bcrypt" : "0.5.x"
  }
}

We first verified that the application is working locally with installed module versions. We can then run the ”npm shrinkwrap” command in the application’s base directory to generate the npm-shrinkwrap.json file:

{
  "name": "node-dependencies-example",
  "version": "0.1.0",
  "dependencies": {
    "express": {
      "version": "2.5.9",
      "dependencies": {
        "connect": {
          "version": "1.8.7",
          "dependencies": {
            "formidable": {
              "version": "1.0.9"
            }
          }
        },
        "mime": {
          "version": "1.2.4"
        },
        "qs": {
          "version": "0.4.2"
        },
        "mkdirp": {
          "version": "0.3.0"
        }
      }
    },
    "bcrypt": {
      "version": "0.5.0"
    }
  }
}

We can now push the application without the node_modules folder, or we can provide a cloudfoundry.json file in the application’s base directory, which sets ignoreNodeModules to true to bypass the existing node modules.

{ "ignoreNodeModules" : true }

If we push our application now, Cloud Foundry will install node modules into the application that were compiled on Cloud Foundry’s platform.

$ vmc push node-dependencies-example --runtime=node06

Note that bcrypt has different APIs for different node engines, so we have to explicitly specify the required runtime.

Finally, if we go to a browser we would see the display, “World is safe!”.

To summarize, npm support is a long-awaited feature that allows you to use the full variety of node modules available today, greatly enhancing your application.

- Maria Shaldibina

The Cloud Foundry Team

Don’t have a Cloud Foundry account yet?  Sign up for free today