Fetching contributors…
Cannot retrieve contributors at this time
326 lines (224 sloc) 17.9 KB
title: Getting Started Deploying Grails Apps
owner: Java
<strong><%= modified_date %></strong>
This guide is intended to walk you through deploying a Grails app to <%=vars.product_full%>.
If you experience a problem following the steps below, refer to the <%=vars.known_issues%> or [Troubleshooting Application Deployment and Health](./../../../devguide/deploy-apps/troubleshoot-app-health.html) topics for more information.
<p class="tip"><strong>Sample App Step</strong><br />If you want to go through this tutorial using the sample app, run <code>git clone</code> to clone the <code>pong_matcher_grails</code> app from GitHub, and follow the instructions in the Sample App Step sections.</p>
<p class="note"><strong>Note</strong>: Ensure that your Grails app runs locally before continuing with this procedure.</p>
##<a id='deploy-yourapp'></a>Deploy a Grails Application ##
This section describes how to deploy a Grails application to <%=vars.product_short%>.
### Prerequisites ###
* A Grails app that runs locally on your workstation
* Intermediate to advanced Grails knowledge
* The [Cloud Foundry Command Line Interface (cf CLI)](../../../cf-cli/install-go-cli.html)
* JDK 1.7 or 1.8 for Java 7 or 8 configured on your workstation
<p class="note"><strong>Note</strong>: You can develop Grails applications in Groovy, Java 7 or 8, or any JVM language. The Cloud Foundry Java buildpack uses JDK 1.8, but you can modify the buildpack and the manifest for your app to compile to JDK 1.7 as described in <em>Step 8: Configure the Deployment Manifest</em> of this topic.</p>
### Step 1: Declare App Dependencies ###
Declare all the dependency tasks for your app in the build script of your chosen build tool. The table lists build script information for Gradle, Grails, and Maven, and provides documentation links for each build tool.
<table border="1" class="nice">
<th><strong>Build Tool</strong></th>
<th><strong>Build Script</strong></th>
<td>Gradle</td><td><code>build.gradle</code></td><td><a href="">Gradle User Guide</a></td>
<td>Grails</td><td><code>BuildConfig.groovy</code></td><td><a href="">Grails: Configuration - Reference Documentation</a></td>
<td>Maven</td><td><code>pom.xml</code></td><td><a href="">Apache Maven Project Documentation</a></td>
<p class="tip"><strong>Sample App Step</strong><br />You can skip this step. The <code>pong_matcher_grails/app/grails-app/conf/BuildConfig.groovy</code> file contains the dependencies for the <code>pong_matcher_grails</code> sample app, as the example below shows.
<%= yield_for_code_snippet from: 'cloudfoundry-samples/pong_matcher_grails', at: 'gsg-grails-s3' %>
### Step 2: Allocate Sufficient Memory ###
Run the Cloud Foundry Command Line Interface (cf CLI) `cf push -m` command to specify the amount of memory that should be allocated to the application. Memory allocated this way is done in preset amounts of `64M`, `128M`, `256M`, `512M`, `1G`, or `2G`. For example:
<pre class="terminal">
$ cf push -m 128M
When your app is running, you can use the `cf app APP-NAME` command to see memory utilization.
<p class="tip"><strong>Sample App Step</strong><br />You can skip this step. In the <code>manifest.yml</code> of the <code>pong_matcher_grails</code> sample app, the <code>memory</code> sub-block of the <code>applications</code> block allocates 1 GB to the app.</p>
### Step 3: Provide a JDBC Driver ###
The Java buildpack does not bundle a JDBC driver with your application. If your application accesses a SQL RDBMS, you must do the following:
* Include the appropriate driver in your application.
* Create a dependency task for the driver in the build script for your build tool or IDE.
<p class="tip"><strong>Sample App Step</strong><br />You can skip this step. The <code>pong_matcher_grails</code> sample app declares a MySQL JDBC driver in the <code>pong_matcher_grails/app/grails-app/conf/DataSource.groovy</code> file because the app uses ClearDB, which is a database-as-service for MySQL-powered apps. The example below shows this declaration.</p>
<%= yield_for_code_snippet from: 'cloudfoundry-samples/pong_matcher_grails', at: 'gsg-grails-s5' %>
### Step 4: (Optional) Configure a Procfile
Use a Procfile to declare required runtime processes for your web app and to specify your web server. For more information, see the [Configuring a Production Server](../../prod-server.html) topic.
<p class="tip"><strong>Sample App Step</strong><br />You can skip this step. The <code>pong_matcher_grails</code> app does not require a Procfile.</p>
### Step 5: Create and Bind a Service Instance for a Grails Application ###
This section describes using the cf CLI to configure a ClearDB managed service instance for an app. <%=vars.dev_console_1%>
<%=vars.product_short%> supports two types of service instances:
* Managed services integrate with <%=vars.product_short%> through service brokers that offer services and plans and manage the service calls between <%=vars.product_short%> and a service provider.
* User-provided service instances enable you to connect your application to pre-provisioned external service instances.
For more information about creating and using service instances, refer to the [Services Overview](./../../../devguide/services/index.html) topic.
#### Create a Service Instance ####
Run the cf CLI `cf marketplace` command to view managed and user-provided services and plans available to you.
The example shows two of the available managed database-as-a-service providers and their offered plans: `cleardb` database-as-a-service for MySQL-powered apps and `elephantsql` PostgreSQL as a Service.
<pre class="terminal">
$ cf marketplace
Getting services from marketplace in org Cloud-Apps / space development as
service plans description
cleardb spark, boost, amp Highly available MySQL for your apps
elephantsql turtle, panda, elephant PostgreSQL as a Service
Run `cf create-service SERVICE PLAN SERVICE-INSTANCE` to create a service instance for your app. Choose a SERVICE and PLAN from the list, and provide a unique name for the SERVICE-INSTANCE.
<p class="tip"><strong>Sample App Step</strong><br />Run <code>cf create-service cleardb spark mysql</code>. This creates a service instance named <code>mysql</code> that uses the <code>cleardb</code> service and the <code>spark</code> plan, as the example below shows.
<pre class="terminal">
$ cf create-service cleardb spark mysql
Creating service mysql in org Cloud-Apps / space development as
#### Bind a Service Instance ####
When you bind an app to a service instance, <%=vars.product_short%> writes information about the service instance to the VCAP_SERVICES app environment variable. The app can use this information to integrate with the service instance.
Most services support bindable service instances. Refer to your service provider's documentation to confirm if they support this functionality.
You can bind a service to an application with the command `cf bind-service APPLICATION SERVICE-INSTANCE`.
Alternately, you can configure the deployment manifest file by adding a `services` sub-block to the `applications` block and specifying the service instance. For more information and an example on service binding using a manifest, see the Sample App step.
<p class="tip"><strong>Sample App Step</strong><br />You can skip this step because the service instance is already bound. Open the <code>manifest.yml</code> file in a text editor to view the bound service instance information. Locate the file in the app root directory and search for the <code>services</code> sub-block in the <code>applications</code> block, as the example below shows.
<pre class="code">
- mysql
### Step 6: Configure the Deployment Manifest ###
You can specify deployment options in the `manifest.yml` that the `cf push` command uses when deploying your app.
Refer to the [Deploying with Application Manifests](../../../devguide/deploy-apps/manifest.html) topic for more information.
<p class="tip"><strong>Sample App Step</strong><br />You can skip this step. The <code>manifest.yml</code> file for the <code>pong_matcher_grails</code> sample app does not require any additional configuration to deploy the app.</p>
### Step 7: Log in and Target the API Endpoint ###
Run `cf login -a API-ENDPOINT`, enter your login credentials, and select a space and org. The API endpoint is <%=vars.api_endpoint%>.
<p class="tip"><strong>Sample App Step</strong><br />You must do this step to run the sample app.</p>
### Step 8: Deploy the Application ###
<p class="note"><strong>Note</strong>: You must use the cf CLI to deploy apps.</p>
From the root directory of your application, run `cf push APP-NAME -p PATH-TO-FILE.war` to deploy your application.
<p class="note"><strong>Note</strong>: You must deploy the <code>.war</code> artifact for a Grails app, and you must include the path to the <code>.war</code> file in the <code>cf push</code> command using the <code>-p</code> option if you do not declare the path in the <code>applications</code> block of the manifest file. For more information, refer to the <a href="../java-tips.html#grails">Grails section</a> in the Tips for Java Developers topic.</p>
`cf push APP-NAME` creates a URL route to your application in the form HOST.DOMAIN, where HOST is your APP-NAME and DOMAIN is specified by your administrator. Your DOMAIN is`<%=vars.app_domain%>`. For example: `cf push my-app` creates the URL `my-app.<%=vars.app_domain%>`.
The URL for your app must be unique from other apps that <%=vars.product_short%> hosts or the push will fail. Use the following options to help create a unique URL:
* `-n` to assign a different HOST name for the app
* `--random-route` to create a URL that includes the app name and random words
* `cf help push` to view other options for this command
If you want to view log activity while the app deploys, launch a new terminal window and run `cf logs APP-NAME`.
Once your app deploys, browse to your app URL. Search for the `urls` field in the `App started` block in the output of the `cf push` command. Use the URL to access your app online.
<p class="tip"><strong>Sample App Step</strong><br />
1. Change to the <code>app</code>directory, and run <code>./grailsw war</code> to build the app.
<br />
2. Run <code>cf push pong_matcher_grails -n HOST-NAME</code> to push the app.
<br /><br />
Example: <code>cf push pong_matcher_grails -n my-grails-app</code>
<p class="note"><strong>Note</strong>: You do not have to include the <code>-p</code> flag when you deploy the sample app. The sample app manifest declares the path to the archive that <code>cf push</code> uses to upload the app files.
The example below shows the terminal output of deploying the <code>pong\_matcher\_grails</code> app. <code>cf push</code> uses the instructions in the manifest file to create the app, create and bind the route, and upload the app. It then binds the app to the <code>mysql</code> service and follows the instructions in the manifest to start two instances of the app, allocating 1 GB of memory between the instances. After the instances start, the output displays their health and status.
<pre class="terminal">
$ cf push pong_matcher_grails -n my-grails-app
Using manifest file /Users/example/workspace/pong_matcher_grails/app/manifest.yml
Creating app pong_matcher_grails in org Cloud-Apps / space development as
Creating route
Binding to pong_matcher_grails...
Uploading pong_matcher_grails...
Uploading app files from: /Users/example/workspace/pong_matcher_grails/app/target/pong_matcher_grails-0.1.war
Uploading 4.8M, 704 files
Binding service mysql to app pong_matcher_grails in org Cloud-Apps / space development as
Starting app pong_matcher_grails in org Cloud-Apps / space development as
-----> Downloaded app package (38M)
-----> Java Buildpack Version: v2.5 |
-----> Downloading Open Jdk JRE 1.8.0_25 from (1.5s)
Expanding Open Jdk JRE to .java-buildpack/open_jdk_jre (1.1s)
-----> Downloading Spring Auto Reconfiguration 1.5.0_RELEASE from (0.0s)
Modifying /WEB-INF/web.xml for Auto Reconfiguration
-----> Downloading Tomcat Instance 8.0.14 from (0.4s)
Expanding Tomcat to .java-buildpack/tomcat (0.1s)
-----> Downloading Tomcat Lifecycle Support 2.4.0_RELEASE from (0.0s)
-----> Downloading Tomcat Logging Support 2.4.0_RELEASE from (0.0s)
-----> Downloading Tomcat Access Logging Support 2.4.0_RELEASE from (0.0s)
-----> Uploading droplet (83M)
0 of 2 instances running, 2 starting
0 of 2 instances running, 2 starting
0 of 2 instances running, 2 starting
2 of 2 instances running
App started
Showing health and status for app pong_matcher_grails in org Cloud-Apps / space development as
requested state: started
instances: 2/2
usage: 1G x 2 instances
state since cpu memory disk
#0 running 2014-11-10 05:07:33 PM 0.0% 686.4M of 1G 153.6M of 1G
#1 running 2014-11-10 05:07:36 PM 0.0% 677.2M of 1G 153.6M of 1G
### Step 9: Test Your Deployed App ###
You’ve deployed an app to <%=vars.product_short%>!
Use the cf <%=vars.dev_console_2%> to review information and administer your app and your <%=vars.product_short%> account. For example, you can edit the `manifest.yml` to increase the number of app instances from 1 to 3, and redeploy the app with a new app name and host name.
See the [Manage Your Application with the cf CLI](#cli-manage) section for more information. <%=vars.dev_console_4%>
<p class="tip"><strong>Sample App Step</strong><br />
To test the sample app, do the following:
<br /><br />
1. To export the test host, run <code>export HOST=SAMPLE-APP-URL</code>, substituting the URL for your app for <code>SAMPLE-APP-URL</code>.
<br /><br />
2. To clear the database from any previous tests, run:
<br />
<code>curl -v -X DELETE $HOST/all</code>
<br />
You should get a response of <code:>200</code>.
<br /><br />
3. To request a match as "andrew", run:
<br />
<code>curl -v -H "Content-Type: application/json" -X PUT $HOST/match_requests/firstrequest -d '{"player": "andrew"}'</code>
<br />
You should again get a response of <code>200</code>.
<br /><br />
4. To request a match as a different player, run:
<br />
<code>curl -v -H "Content-Type: application/json" -X PUT $HOST/match_requests/secondrequest -d '{"player": "navratilova"}'</code>
<br /><br />
5. To check the status of the first match request, run:
<br />
<code>curl -v -X GET $HOST/match_requests/firstrequest</code>
<br />
The last line of the output shows the <code>match_id</code>.
<br /><br />
6. Replace <code>MATCH_ID</code> with the <code>match_id</code> value from the previous step in the following command:
<br />
<code>curl -v -H "Content-Type: application/json" -X POST $HOST/results -d '
<br />
You should receive a <code>201 Created</code> response.
##<a id='cli-manage'></a>Manage Your Application with the cf CLI ##
Run `cf help` to view a complete list of commands, grouped by task categories, and run `cf help COMMAND` for detailed information about a specific command. For more information about using the cf CLI, refer to the Cloud Foundry Command Line Interface (cf CLI) topics, especially the <%=vars.cli_v6%> topic.
<p class="note"><strong>Note</strong>: You cannot perform certain tasks in the <%=vars.dev_console_2%> because these are commands that only a <%=vars.product_short%> administrator can run. If you are not a <%=vars.product_short%> administrator, the following message displays for these types of commands:
<code>error code: 10003, message: You are not authorized to perform the requested action</code>
##<a id='troubleshoot'></a>Troubleshooting ##
If your application fails to start, verify that the application starts in your local environment. Refer to the [Troubleshooting Application Deployment and Health](./../../../devguide/deploy-apps/troubleshoot-app-health.html) topic to learn more about troubleshooting.
### App Deploy Fails ###
Even when the deploy fails, the app might exist on <%=vars.product_short%>. Run `cf apps` to review the apps in the currently targeted org and space. You might be able to correct the issue using the <%=vars.dev_console_2%>, or you might have to delete the app and redeploy.
### App Requires a Unique URL ###
<%=vars.product_short%> requires that each app that you deploy have a unique URL. Otherwise, the new app URL collides with an existing app URL and <%=vars.product_short%> cannot successfully deploy the app. You can fix this issue by running `cf push` with either of the following flags to create a unique URL:
* `-n` to assign a different HOST name for the app.
* `--random-route` to create a URL that includes the app name and random words. Using this option might create a long URL, depending on the number of words that the app name includes.