To make this more concrete, let’s look at an example. I’ll assume that you already have a Cloud Foundry account, and that you’ve added your username and password to $HOME/.grails/settings.groovy (the file isn’t created for you, so create a new empty file if you haven’t already done so) to avoid having your password in source control, e.g.

grails.plugin.cloudfoundry.username = 'your_username'
grails.plugin.cloudfoundry.password = 'your_password'

Add a dependency on the cloud-foundry plugin to your application’s BuildConfig.groovy in the plugins section:

plugins {
   runtime ":hibernate:$grailsVersion"
   runtime ':jquery:1.7.1'
   runtime ':resources:1.1.6'
   build ":tomcat:$grailsVersion"

   compile ':cloud-foundry:1.2.1'
}

and run grails compile to let the plugins resolve. If you want to use a MySQL database, add a dependency for its driver in the dependencies section:

dependencies {
   runtime 'mysql:mysql-connector-java:5.1.16'
}

otherwise add a dependency for the PostgreSQL driver:

dependencies {
   runtime 'postgresql:postgresql:8.4-702.jdbc3'
}

Create a simple domain class so we can test the database persistence:

$ grails create-domain-class cloud.foundry.test.Person

and add some fields so it looks something like this:

package cloud.foundry.test

class Person {
   String firstName
   String lastName
}

Generate a static scaffolded UI:

$ grails generate-all cloud.foundry.test.Person

Enable the database console with the grails.dbconsole.enabled attribute in the production section in Config.groovy so we can take a look at the database and run some queries once the application is deployed:

environments {
   ...
   production {
      ...
      grails.dbconsole.enabled = true
   }
}

Also add some logging code in BootStrap.groovy to display the database connection information so we can use it to connect with the database console UI:

import grails.converters.JSON

class BootStrap {

   def init = { servletContext ->
      String VCAP_SERVICES = System.getenv('VCAP_SERVICES')
      println "VCAP_SERVICES: ${System.getenv('VCAP_SERVICES')}\n"

      def service = JSON.parse(VCAP_SERVICES).find { it.key.startsWith('mysql') }.value[0]
      println """
MySQL url:      jdbc:mysql://$service.credentials.hostname:$service.credentials.port/$service.credentials.name
      user:     $service.credentials.user
      password: $service.credentials.password"""
   }
}

And that’s it - we’ll leave the settings in DataSource.groovy alone since the connection settings will be reconfigured for us when deploying. You can add some extra JDBC URL parameters to a placeholder URL to configure the database if you want, for example to enable Unicode and UTF-8:

environments {
   ...
   production {
      dataSource {
         ...
         url = 'jdbc:mysql://localhost/db?useUnicode=true&characterEncoding=utf8'
      }
   }
}

Run the cf-push command to deploy the application. You should see output similar to this if you don’t already have a MySQL service configured and you let the script add and bind it for you:

$ grails prod cf-push
| Environment set to production.....
Building war file
| Done creating WAR target/cf-temp-1331686075902.war
>
Application Deployed URL: 'testing-testing-testing-1-2-3.cloudfoundry.com'? y
>
Would you like to create and bind a mysql service?[y,n] y
Service 'mysql-84fba3d' provisioned.
>
Would you like to create and bind a postgresql service?[y,n] n

Creating application testing-testing-testing-1-2-3 at testing-testing-testing-1-2-3.cloudfoundry.com with 512MB and services [mysql-84fba3d]:
 OK
Uploading Application:
  Checking for available resources:
 OK
  Processing resources:
 OK
  Packing application:
 OK
  Uploading (452K):
 OK

Trying to start Application: 'testing-testing-testing-1-2-3'.
.....

Application 'testing-testing-testing-1-2-3' started at http://testing-testing-testing-1-2-3.cloudfoundry.com

View the contents of the stdout.log file from the server with the cf-get-file script and it should look something like this:

$ grails cf-get-file logs/stdout.log
| Environment set to development.....

VCAP_SERVICES: {"mysql-5.1":[{"name":"mysql-84fba3d","label":"mysql-5.1",
"plan":"free","tags":["mysql","mysql-5.1","relational"],
"credentials"{"name":"d2df723ab1f14440a9dcbd37af9c1a4d1",
"hostname":"172.30.48.22","host":"172.30.48.22","port":3306,
"user":"umASXSmfZneBu","username":"umASXSmfZneBu","password":"pMKFw9EqZNuOS"}}]}

MySQL url:      jdbc:mysql://172.30.48.22:3306/d2df723ab1f14440a9dcbd37af9c1a4d1
      user:     umASXSmfZneBu
      password: pMKFw9EqZNuOS

If you navigate to the root url of your application it should display the start page with a link to the scaffolded controller you created as shown in Figure 10.1, “Home page of the test application”.

Figure 10.1. Home page of the test application

and you can open up the database console by navigating to /dbconsole/; choose "Generic MySQL" from the "Saved Settings" dropdown and enter the URL, username, and password that was in the server log file to login. Figure 10.2, “Database console UI” shows the console after connecting.

Figure 10.2. Database console UI

There’s not much to see yet since the application just started, but you can open up the Person CRUD pages and add some data so you can run some queries. You can also run show create table person to see the DDL that was used to create the table; it should show that it’s an InnoDB table (since the plugin configures the appropriate Hibernate Dialect for you) and that it uses UTF-8 charset (from the JDBC URL settings that you added to DataSource.groovy).

Cloud Foundry uses sticky sessions between your instances, so functionality that depends on a consistent HTTP session will work well for the most part since all requests will go to a single server. Sessions aren’t replicated however, so if the server that a user is on crashes, the HTTP session will be lost and after getting redirected to another server, the session will have to be reinitialized. If authentication credentials are stored in the session, the user will no longer be authenticated and have to login again.

Server crashes are rare, but you might consider using an alternative approach to session management. There are three plugins that you can use to change how sessions and session data are stored; database-session (which stores sessions in a relational database), mongodb-session (which stores sessions in a MongoDB datastore), and cookie-session (which stores sessions in a cookie, limiting you to a total of 4K of session storage).

You can get a lot of information by using the commandline scripts, but they can be tedious and impractical to work with. There is an addon plugin for the cloud-foundry plugin, the cloud-foundry-ui plugin which creates a simple but very useful monitoring front end for your application. To use it, install it just like you did the cloud-foundry plugin, i.e. add it to BuildConfig.groovy (or use install-plugin):

plugins {
   runtime ":hibernate:$grailsVersion"
   runtime ':jquery:1.7.1'
   runtime ':resources:1.1.6'
   build ":tomcat:$grailsVersion"

   compile ':cloud-foundry:1.2.1'

   compile ':cloud-foundry-ui:1.1.1'
}

There isn’t much configuration required for this plugin, but you will need to add some controller mappings in UrlMappings.groovy. You have flexibility in the prefix of the URLs, but the other values must be the same as these:

class UrlMappings {

   static mappings = {
      "/$controller/$action?/$id?"{
         constraints {
            // apply constraints here
         }
      }

      "/admin/cfDashboard/$action?"(controller: 'cloudFoundryDashboard')

      "/admin/cfDashboard/application/$appName"(
              controller: 'cloudFoundryDashboard', action: 'application')

      "/admin/cfDashboard/service/$serviceName"(
              controller: 'cloudFoundryDashboard', action: 'service')

      "/admin/cfDashboard/files/$appName/$instanceIndex?"(
              controller: 'cloudFoundryDashboard', action: 'files')

      "/"(view:"/index")
      "500"(view:'/error')
   }
}

In this example I’ve used the "/admin" prefix to differentiate the URLs from the main site, and to make it easier to guard the pages with security since I can most likely use a wildcard pattern for "/admin/**". Once you’ve installed the plugin and deployed the application with cf-push or updated an existing application with cf-update, you can navigate to the root URL that you defined in UrlMappings.groovy, for example http://appname.cloudfoundry.com/admin/cfDashboard

If you set your Cloud Foundry username and password in Config.groovy then you’ll immediately see the UI screens. If you set the values in $HOME/.grails/settings.groovy however, they’re not available at runtime so you’ll be prompted with a login screen as shown in Figure 10.3, “Login screen” to enter your credentials so the plugin can make API calls on your behalf:

Figure 10.3. Login screen

Once you’ve logged in, click the toolbar button with your application name and you’ll see the statistics dashboard as shown in Figure 10.4, “Statistics page”:

Figure 10.4. Statistics page

The gauges update themselves every five seconds unless you click the "Disable auto-refresh" link. If you click the "View" link on the left under "Files" you’ll see the file viewer pages like the example in Figure 10.5, “File viewer” that lets you see the entire directory tree (as much as you’re allowed to see anyway) and view any file:

Figure 10.5. File viewer

You can also right-click on any file to download it to your local machine.

Let’s look at an example of deploying to Heroku. I’ll assume that you already have a Heroku account and that you’ve installed the heroku and git clients and have authenticated at Heroku.

Add a dependency on the heroku plugin to your application’s BuildConfig.groovy in the plugins section:

plugins {
   runtime ":hibernate:$grailsVersion"
   runtime ':jquery:1.7.1'
   runtime ':resources:1.1.6'
   build ":tomcat:$grailsVersion"

   compile ':heroku:1.0.1'
}

and run grails compile to let the plugins resolve. Add a dependency for the PostgreSQL driver:

dependencies {
   runtime 'postgresql:postgresql:8.4-702.jdbc3'
}

Create a simple domain class so we can test the database persistence:

$ grails create-domain-class heroku.test.Person

and add some fields so it looks something like this:

package heroku.test

class Person {
   String firstName
   String lastName
}

Generate a static scaffolded UI:

$ grails generate-all heroku.test.Person

Enable the database console with the grails.dbconsole.enabled attribute in the production section in Config.groovy so we can take a look at the database and run some queries once the application is deployed:

environments {
   ...
   production {
      ...
      grails.dbconsole.enabled = true
   }
}

Also add some logging code in BootStrap.groovy to display the database connection information so we can use it to connect with the database console UI:

import grails.plugin.heroku.PostgresqlServiceInfo

class BootStrap {

   def init = { servletContext ->
      String DATABASE_URL = System.getenv('DATABASE_URL')
      if (DATABASE_URL) {
         try {
            PostgresqlServiceInfo info = new PostgresqlServiceInfo()
            println "\nPostgreSQL service ($DATABASE_URL): url='$info.url', " +
                    "user='$info.username', password='$info.password'\n"
         }
         catch (e) {
            println "Error occurred parsing DATABASE_URL: $e.message"
         }
      }
   }
}

Leave the settings in DataSource.groovy alone since the connection settings will be reconfigured for us when deploying.

Now we just need to initialize the Git repo and configure the Heroku project. Run git init:

$ git init
Initialized empty Git repository in /home/burt/workspace/heroku_grails/.git/

Run grails integrate-with --git to create a .gitignore file, and add the files and commit them:

$ grails integrate-with --git
| Created Git project files..
$ git add .
$ git commit -m "initial commit"
[master (root-commit) 78181a3] initial commit
 69 files changed, 4487 insertions(+), 0 deletions(-)
 create mode 100644 .classpath
 create mode 100644 .gitignore
 create mode 100644 .project
 create mode 100644 application.properties
...

Create the application using heroku create:

$ heroku create --stack cedar

This command creates the application at Heroku’s server (but doesn’t deploy anything yet). You can verify this by going to https://api.heroku.com/myapps where it will be listed along with any other application you may have created. The command also registers a Git remote to Heroku, which you can see by running git remote -v.

And we’re now ready to deploy. It’s as simple as pushing the commited application files to the Heroku remote added by heroku create, so run git push heroku master and watch the output. You’ll see that your application jar and plugin dependencies are resolved at the server, and a war file will be created and deployed to a Jetty server instance. If there’s an error during deployment, the Git push will fail and you can fix the issue, commit the changes, and push again to try deploying with the fixes applied.

If the deployment is sucessful, you can run heroku logs to see the server log output, and run heroku logs -t to "tail" the log and continuously display updated lines of output. The PostgreSQL connection information in the logs should look something like this:

PostgreSQL service (
postgres://syrmypn:Dp_RHcV@ec2-23-21-182-175.compute-1.amazonaws.com/syrmypn):
url='jdbc:postgresql://ec2-23-21-182-175.compute-1.amazonaws.com:5432/syrmypn',
user='syrmypn', password='Dp_RHcV'

If you navigate to the root url of your application it should display the start page with a link to the scaffolded controller you created. Figure 10.6, “Home page of the test application” shows an example.

Figure 10.6. Home page of the test application

and you can open up the database console by navigating to /dbconsole/; choose "Generic PostgreSQL" from the "Saved Settings" dropdown and enter the URL, username, and password that was in the server log file to login. Figure 10.7, “Database console UI” shows the console after connecting.

Figure 10.7. Database console UI

There’s not much to see yet since the application just started, but you can open up the Person CRUD pages and add some data so you can run some queries.

Heroku does not offer session affinity, sticky sessions, or session clustering options. This means that functionality that depends on a consistent HTTP session will not work on Heroku. The includes basic HTTP session storage, but also Grails flash scope since that is implemented by storing the flash-scope data in the session until the next request. It also means that plugins like spring-security-core which store authentication details in your session will not work; you can authenticate but since your requests will be randomly assigned to different servers, you’ll appear logged in only on one instance but not the others. Whereas alternative approaches to session management are an option for Cloud Foundry, they’re more necessary for Heroku.

The heroku plugin depends on the database-session plugin, so by default your users will continue to split requests across multiple servers, but the session data will be stored in the PostgreSQL database and shared across all servers. If you prefer to use the MongoDB version of the plugin, add an exclusion for the database-session plugin in BuildConfig.groovy and add a dependency for the mongodb-session plugin:

plugins {
   runtime ":hibernate:$grailsVersion"
   runtime ':jquery:1.7.1'
   runtime ':resources:1.1.6'
   build ":tomcat:$grailsVersion"

   compile(':heroku:1.0.1') {
      excludes 'database-session'
   }

   compile ':mongodb-session:0.1'
}

Or if you prefer to use cookie-based storage (and you’re confident that user sessions won’t go beyond the 4K limit), use the cookie-session plugin instead:

plugins {
   runtime ":hibernate:$grailsVersion"
   runtime ':jquery:1.7.1'
   runtime ':resources:1.1.6'
   build ":tomcat:$grailsVersion"

   compile(':heroku:1.0.1') {
      excludes 'database-session'
   }

   compile ':cookie-session:0.1.2'
}

TBD