Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
263 lines (183 sloc) 12 KB
title: Getting Started Deploying Ruby Apps
owner: Buildpacks
<strong><%= modified_date %></strong>
This guide is intended to walk you through deploying a Ruby app to
If you experience a problem following the steps below, check the
<%=vars.known_issues%> topic, or refer to the [Troubleshooting Application Deployment and Health](./../../devguide/deploy-apps/troubleshoot-app-health.html)
<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_ruby</code> app from GitHub, and follow the instructions in the Sample App Step sections.</p>
<p class="note"><strong>Note</strong>: Ensure that your Ruby app runs locally before continuing with this procedure.</p>
## <a id="deploy"></a>Deploy a Ruby Application ##
This section describes how to deploy a Ruby application to
<%=vars.product_short%>, and uses output from a sample app to show specific
steps of the deployment process.
### Prerequisites ###
* A Ruby 2.x application that runs locally on your workstation
* [Bundler]( configured on your workstation
* Basic to intermediate Ruby knowledge
* The [Cloud Foundry Command Line Interface (cf CLI)](../../cf-cli/install-go-cli.html) installed on your
###<a id="create-bind"></a> Step 1: Create and Bind a Service Instance for a Ruby Application ###
This section describes using the cf CLI to configure a Redis Cloud 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 `cf marketplace` to view managed and user-provided services and plans
that are available to you.
The example shows three of the available managed database-as-a-service providers
and the plans that they offer: `cleardb` MySQL and `elephantsql` PostgreSQL as a
<pre class="terminal">
$ cf marketplace
Getting services from marketplace in org Cloud-Apps / space development as
service plans description
cleardb spark, boost, amp, shock Highly available MySQL for your Apps
elephantsql turtle, panda, hippo, 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
<p class="tip"><strong>Sample App Step</strong><br />Run <code>cf create-service rediscloud 30mb redis</code>. This creates a service instance named <code>redis</code> that uses the <code>rediscloud</code> service and the <code>30mb</code> plan, as the example below shows.</p>
<pre class="terminal">
$ cf create-service rediscloud 30mb redis
Creating service redis 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
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
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` block to the `applications` block and specifying the service
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. The manifest for the sample app contains a <code>services</code> sub-block in the <code>applications</code> block, as the example below shows. This binds the <code>redis</code> service instance that you created in the previous step.</p>
<%= yield_for_code_snippet from: 'cloudfoundry-samples/pong_matcher_ruby', at: 'ruby-2b' %>
### <a id="deployment-options"></a> Step 2: Configure Deployment Options ###
#### Configure the Deployment Manifest ####
You can specify app deployment options in a manifest that the `cf push` command uses. For more information about application manifests and supported attributes, refer to the [Deploying with Application Manifests](./../../devguide/deploy-apps/manifest.html) topic.
#### Configure a Production Server ####
<%=vars.product_short%> uses the default standard Ruby web server library, WEBrick, for Ruby and RoR apps. However, <%=vars.product_short%> can support a more robust production web server, such as Phusion Passenger, Puma, Thin, or Unicorn. If your app requires a more robust web server, refer to the [Configuring a Production Server](../prod-server.html) topic for help configuring a server other than WEBrick.
<p class="tip"><strong>Sample App Step</strong><br />You can skip this step. The <code>manifest.yml</code> file for <code>pong_matcher_ruby</code> does not require any additional configuration to deploy the app.</p>
### Step 3: 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 4: Deploy an App ###
<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` to deploy
your application.
`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
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 />Run <code>cf push pong_matcher_ruby -n HOST_NAME</code>.<br /><br />Example: <code>cf push pong_matcher_ruby -n pongmatch-ex12</code> <br /><br />The example below shows the terminal output of deploying the <code>pong_matcher_ruby</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>redis</code> service and follows the instructions in the manifest to start one instance of the app with 256M. After the app starts, the output displays the health and status of the app.</p>
<p class="note"><strong>Note</strong>: The <code>pong_matcher_ruby</code> app does not include a web interface. To interact with the <code>pong_matcher_ruby</code> app, see the interaction instructions on GitHub: <a href=""></a>.</p>
<pre class="terminal">
$ cf push pong_matcher_ruby -n pongmatch-ex12
Using manifest file /Users/clouduser/workspace/pong_matcher_ruby/manifest.yml
Creating app pong_matcher_ruby in org Cloud-Apps / space development as
Creating route pongmatch-ex12.<%=vars.app_domain%>
Binding pongmatch-ex12.<%=vars.app_domain%> to pong_matcher_ruby...
Uploading pong_matcher_ruby...
Uploading app files from: /Users/clouduser/workspace/pong_matcher_ruby
Uploading 8.8K, 12 files
Binding service redis to app pong_matcher_ruby in org Cloud-Apps / space development as
Starting app pong_matcher_ruby in org Cloud-Apps / space development as
0 of 1 instances running, 1 starting
1 of 1 instances running
App started
Showing health and status for app pong_matcher_ruby in org Cloud-Apps / space development as
requested state: started
instances: 1/1
usage: 256M x 1 instances
state since cpu memory disk
#0 running 2014-12-09 10:04:40 AM 0.0% 35.2M of 256M 45.8M of 1G
### Step 5: Test a 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 could 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%>
## <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 deploying an app fails, the app might exist on
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.
Common reasons deploying an app fails include:
* You did not successfully create and bind a needed service instance to the app,
such as a PostgreSQL service instance.
Refer to Step 2: Create and Bind a Service Instance for a Ruby Application.
* You did not successfully create a unique URL for the app.
Refer to the troubleshooting tip <strong>App Requires Unique URL</strong>.
### App Requires Unique URL ###
<%=vars.product_short%> requires that each app that you deploy has a unique
Otherwise, the new app URL collides with an existing app URL and
<%=vars.product_short%> cannot successfully deploy the app.
You can resolve 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.