Fetching contributors…
Cannot retrieve contributors at this time
280 lines (195 sloc) 15.3 KB
title: Getting Started Deploying Spring Apps
owner: Java
<strong><%= modified_date %></strong>
This guide is intended to walk you through deploying a Spring app to <%=vars.product_full%>. You can choose whether to push a sample app, your own app, or both.
If you experience a problem following the steps below, see the <%=vars.known_issues%> topic, or refer to the [Troubleshooting Application Deployment and Health](./../../../devguide/deploy-apps/troubleshoot-app-health.html) topic.
<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_spring</code> app from GitHub, and follow the instructions in the Sample App Step sections.</p>
<p class="note"><strong>Note</strong>: Ensure that your Spring app runs locally before continuing with this procedure.</p>
## <a id='deploy-yourapp'></a>Deploy a Spring Application ##
This section describes how to deploy your Spring application to <%=vars.product_short%>.
### Prerequisites ###
* A Spring app that runs locally on your workstation
* Intermediate to advanced Spring knowledge
* The [Cloud Foundry Command Line Interface (cf CLI)](../../../cf-cli/install-go-cli.html)
* JDK 1.6, 1.7, or 1.8 for Java 6, 7, or 8 configured on your workstation
<p class="note"><strong>Note</strong>: The Cloud Foundry Java buildpack uses JDK 1.8, but you can modify the buildpack and the manifest for your app to compile to an earlier version. For more information, refer to the <a href="../../custom.html">Custom Buildpacks</a> topic.</p>
### Step 1: Declare App Dependencies ###
Be sure to declare all the dependency tasks for your app in the build script of your chosen build tool.
The [Spring Getting Started Guides]( demonstrate features and functionality you can add to your app, such as consuming RESTful services or integrating data. These guides contain Gradle and Maven build script examples with dependencies. You can copy the code for the dependencies into your build script.
The table lists build script information for Gradle 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><a href="">Gradle User Guide</a></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>pom.xml</code> file contains the dependencies for the <code>pong_matcher_spring</code> sample app, as the example below shows.
<%= yield_for_code_snippet from: 'cloudfoundry-samples/pong_matcher_spring', at: 'gsg-spring-s3' %>
<p class="note"><strong>Note</strong>: Make sure you are not building <a href="">fully executable jars</a> because application push may fail.</p>
### Step 2: Allocate Sufficient Memory ###
Use the `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. The Cloud Foundry Java buildpack uses settings declared in the sample app to allocate 1 GB of memory 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. In the <code>pong_matcher_spring</code> sample app, the <code>src/main/resources/application.yml</code> file declares the JDBC driver, and the <code>pom.xml</code> file includes the JDBC driver as a dependency.</p>
### Step 4: Configure Service Connections for a Spring App ###
<%=vars.product_short%> provides extensive support for creating and binding a Spring application to services such as MySQL, PostgreSQL, MongoDB, Redis, and RabbitMQ. For more information about creating and binding a service connection for your app, refer to the [Configure Service Connections for Spring](../configuring-service-connections/spring-service-bindings.html) topic.
<p class="tip"><strong>Sample App Step: Create a Service Instance</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
<p class="tip"><strong>Sample App Step: Bind a Service Instance</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 5: Configure the Deployment Manifest ###
You can specify deployment options in a manifest file `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_spring</code> sample app does not require any additional configuration to deploy the app.</p>
### Step 6: 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 7: Deploy Your 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>: Most Spring apps include an artifact, such as a <code>.jar</code>, <code>.war</code>, or <code>.zip</code> file. You must include the path to this 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. The example shows how to specify a path to the <code>.war</code> file for a Spring app. Refer to the <a href="../java-tips.html">Tips for Java Developers</a> topic for CLI examples for specific build tools, frameworks, and languages that create an app with an artifact.</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. Run <code>brew install maven</code>.
<br />
2. Change to the <code>app</code>directory, and run <code>mvn package</code> to build the app.
<br />
3. Run <code>cf push pong_matcher_spring -n HOSTNAME</code> to push the app.
<br /><br />
Example: <code>cf push pong_matcher_spring -n my-spring-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\_spring</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 starts one instance of the app with 1 GB of memory. After the app starts, the output displays the health and status of the app.
<pre class="terminal">
$ cf push pong_matcher_spring -n spring1119
Using manifest file /Users/example/workspace/pong_matcher_spring/manifest.yml
Creating app pong_matcher_spring in org Cloud-Apps / space development as
Creating route
Binding to pong_matcher_spring...
Uploading pong_matcher_spring...
Uploading app files from: /Users/example/workspace/pong_matcher_spring/target/pong-matcher-spring-1.0.0.BUILD-SNAPSHOT.jar
Uploading 797.5K, 116 files
Binding service mysql to app pong_matcher_spring in org Cloud-Apps / space development as
Starting app pong_matcher_spring in org Cloud-Apps / space development as
-----> Downloaded app package (25M)
-----> Downloading Open Jdk JRE 1.8.0_25 from (1.2s)
Expanding Open Jdk JRE to .java-buildpack/open_jdk_jre (1.1s)
-----> Downloading Spring Auto Reconfiguration 1.5.0_RELEASE from (0.1s)
-----> Uploading droplet (63M)
0 of 1 instances running, 1 starting
1 of 1 instances running
App started
Showing health and status for app pong_matcher_spring in org Cloud-Apps / space development as
requested state: started
instances: 1/1
usage: 1G x 1 instances
state since cpu memory disk
#0 running 2014-11-19 12:29:27 PM 0.0% 553.6M of 1G 127.4M of 1G
### Step 8: 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 App 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 Content-Type ###
If you specify a `Content-Encoding` header of `gzip` but do not specify a `Content-Type` within your application, <%=vars.product_short%> might send a `Content-Type` of `application/x-gzip` to the browser. This scenario might cause the deploy to fail if it conflicts with the actual encoded content of your app. To avoid this issue, be sure to explicitly set `Content-Type` within your app.
### 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.