Deploying vert.x Applications to Cloud Foundry

August 6, 2012 Thomas Risberg

featured-cf-genericNOTE: Modified to use 0.8.2 version of cloudfoundry-runtime dependency together with the version of vert.x (Jan 2, 2013) Developers can now use vert.x, a framework for highly scalable web applications, with Cloud Foundry has been a leader in providing an open Platform as a Service (PaaS), which allows for polyglot programming with a choice of multiple languages and frameworks. With recent releases of standalone application feature and Java 7 on, developers now have a perfect environment to create vert.x applications, which can be written in any language that can run on the Java Virtual Machine (JVM), and deploy them to run on the JVM at

About vert.x

vert.x is a framework that builds on event-driven architecture and asynchronous I/O, similar to

Node.js, but utilizes JVM’s internal capabilities to handle multiple processes and inter-process communications. Using Java threads, vert.x applications can easily scale over available cores making better use of available resources. This is ideal for applications with a large number of concurrent users, such as client applications running on mobile devices. Furthermore, running on the JVM means that it can work seamlessly with code written in other languages that run on the JVM, such as Java, Groovy, Ruby, JavaScript, Coffeescript, Python and others, in the same application. Since vert.x requires Java 7, the addition of Java 7 as a runtime to has enabled developers to use this highly flexible, polyglot framework.

  • vert.x is a community project sponsored by VMware.
  • vert.x includes a distributed event bus that spans the client and server side so your applications components can communicate incredibly easily. The event bus even penetrates into in-browser JavaScript allowing you to create effortless so-called real-time web applications.
  • vert.x also includes Web Sockets and SockJS support plus a MongoDB persistor so you can write real applications from the get-go.

Running vert.x Applications on

vert.x ships with a number of example applications, so let’s take one of the applications–

vToons Groovy example app–and adapt it to run on This is a simple shopping cart app for an online music store. It mostly consists of client side Javascript, but the server side is written in Groovy and the data is persisted in MongoDB. We have to make some modifications to deploy this application to The resulting modified application source code can be found under the cloudfoundry-samples GitHub account at We will use the most recent stable release of vert.x (, which can be downloaded from here: The modifications we have to make are the following:

  • Access system properties when app is running on CloudFoundry
  • Configure host and port setting for HTTP server
  • Configure database settings
  • Package the application for deployment including a vert.x runtime and any dependent jars Let’s start with the application changes. You can read about the changes below and see all of source modifications in this commit in the repository. environment properties:

When your app is running on, there are some environment properties that are available for your app to inspect. This allows you to find the information regarding the services that are bound to the app, such as host and port. We will use the Java cloudfoundry-runtime support library (version 0.8.2) for this task.

import org.cloudfoundry.runtime.env.CloudEnvironment
import org.cloudfoundry.runtime.env.MongoServiceInfo
def cloudEnv = new CloudEnvironment()

We add the import and create a new instance of the general CloudEnvironment class. Additionally, we added an import for the MongoServiceInfo class since we know that we will be binding a MongoDB service to the application.

Web server:

In order to run on, the application must know the host name and port of the provisioned instance on The following code reads the host name and port from the

CloudEnvironment object that we created above, but default to localhost:8080 if a Cloud Foundry environment is not detected:

port: (cloudEnv.getValue('VCAP_APP_PORT') ?: '8080') as int,
host: cloudEnv.getValue('VCAP_APP_HOST') ?: 'localhost', /* ssl: true, */

Note: In order to simplify this example, the SSL support was removed from the application.

Mongo Persistor:

When we push the application to, we will bind it to a MongoDB. The connection parameters for the MongoDB service can be read from the

CloudEnvironment object. Here we use the MongoServiceInfo to access the service settings:

// Configuration for MongoDb
def mongoConf = [:]
if (cloudEnv.isCloudFoundry()) {
  mongoSvcInfo = cloudEnv.getServiceInfo("mongodb-vtoons", MongoServiceInfo.class) = mongoSvcInfo.getHost()
  mongoConf.port = mongoSvcInfo.getPort() as int
  mongoConf.db_name = mongoSvcInfo.getDatabase()
  mongoConf.username = mongoSvcInfo.getUserName()
  mongoConf.password = mongoSvcInfo.getPassword()

We then modified the mongo-persistor deployment to use these configuration settings:

deployVerticle('mongo-persistor', mongoConf, 1) { // And when it's deployed run a script to load it with some reference // data for the demo deployVerticle('StaticData.groovy') }

At this point we are done with the code changes and can move on to packaging the app.

Package and deploy to CloudFoundry:

To simplify the build and deployment we will move the application code to a vert.x module – you can see this change in this

commit in the repository. While we could package the application by copying a few directories from vert.x distribution and then using ‘vmc push’ as usual, let’s simplify by creating a Gradle build script as seen here. This build script provides the following:
1. Defines repository locations for Maven Central, Spring milestone releases and vert.x release distributions
2. Defines two configurations, one for runtime and one for dependent jars, as well as their dependencies
3. Provides a “runtime” task that downloads and packages the vert/x runtime
4. Provides a “build” task that packages the app source into a module directory
5. Provides an “assemble” task packages the application as a zip file to be deployed
6. Provides a “clean” task to clean up the build directory
7. Configures the Gradle CloudFoundry plugin so we can use the build script to deploy the app With everything in place, let’s just build and deploy the app:

$ ./gradlew assemble


Total time: 18.586 secs

$ ./gradlew cf-add-service -PcfPasswd=secret
CloudFoundry - Connecting to '' with user ''
CloudFoundry - Provisioning mongodb service 'mongodb-vtoons'


Total time: 7.435 secs

$ ./gradlew cf-push -PcfPasswd=secret
CloudFoundry - Connecting to '' with user ''
GET request for "" resulted in 404 (Not Found); invoking error handler
CloudFoundry - Creating standalone application 'vtoons' with runtime java7
CloudFoundry - Deploying '/Users/trisberg/Projects/github/cloudfoundry-samples/vertx-vtoons/build/'
CloudFoundry - Starting 'vtoons'


Total time: 21.358 secs

We can now open a browser and enter to see the vert.x vToons application come to life and order some tunes. vToons

Try vert.x on

Cloud Foundry continues its goal of creating the best open PaaS for developers to run applications based on a choice of languages and frameworks. In this blog, we detailed the few simple steps required to deploy a vert.x app, an exciting new Javascript framework for the JVM, to Feel free to experiment with and deploy the numerous other sample apps that are part of the vert.x download on Peter Ledbrook (@pledbrook) took the open source Collide collaborative IDE project and deployed it to, take a look at it here:

Thanks to Tim Fox (@timfox), who created vert.x, and to Scott Frederick and Peter Ledbrook, who also contributed to this blog post.

– Thomas Risberg, The Cloud Foundry Team

About the Author


More Content by Thomas Risberg
Tracker on the Agile Continuum
Tracker on the Agile Continuum

In Tracker support, I take delight in answering support requests we get from people on teams who are think...

The OpenNews Fellowship Calls Data Scientists to Help Build the Newsroom of the Future
The OpenNews Fellowship Calls Data Scientists to Help Build the Newsroom of the Future

Whatever the future of journalism may be, data will play a key role. In recent years, the data journalist h...

Enter curious. Exit smarter.

Register Now