Getting Started Deploying Ruby Apps

Page last updated:

Welcome to Pivotal Web Services, powered by Cloud Foundry!

This guide is intended to walk you through deploying a Ruby app to Pivotal Web Services (PWS). If you experience a problem following the steps below, check the Known Issues topic, or refer to the Troubleshooting Application Deployment and Health topic.

Sample App Step
If you want to go through this tutorial using the sample app, run git clone https://github.com/cloudfoundry-samples/pong_matcher_ruby.git to clone the pong_matcher_ruby app from GitHub, and follow the instructions in the Sample App Step sections.

Note: Ensure that your Ruby app runs locally before continuing with this procedure.

Deploy a Ruby Application

This section describes how to deploy a Ruby application to PWS, and uses output from a sample app to show specific steps of the deployment process.

Prerequisites

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. You can use either the CLI or the Apps Manager to perform this task.

PWS supports two types of service instances:

  • Managed services integrate with PWS through service brokers that offer services and plans and manage the service calls between PWS 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 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 Service.

$  cf marketplace
Getting services from marketplace in org Cloud-Apps / space development as clouduser@example.com...
OK

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 SERVICE_INSTANCE.

Sample App Step
Run cf create-service rediscloud 30mb redis. This creates a service instance named redis that uses the rediscloud service and the 30mb plan, as the example below shows.

$ cf create-service rediscloud 30mb redis
Creating service redis in org Cloud-Apps / space development as clouduser@example.com....
OK

Bind a Service Instance

When you bind an app to a service instance, PWS 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 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.

You can also bind a service using the Apps Manager.

Sample App Step
You can skip this step. The manifest for the sample app contains a services sub-block in the applications block, as the example below shows. This binds the redis service instance that you created in the previous step.

services:
      - redis

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 topic.

Configure a Production Server

PWS uses the default standard Ruby web server library, WEBrick, for Ruby and RoR apps. However, PWS 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 topic for help configuring a server other than WEBrick.

Sample App Step
You can skip this step. The manifest.yml file for pong_matcher_ruby does not require any additional configuration to deploy the app.

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 api.run.pivotal.io.

For more information about determining the API endpoint, refer to the Getting Started with Pivotal Web Services topic.

Sample App Step
You must do this step to run the sample app.

Step 4: Deploy an App

Note: You must use the cf CLI to deploy apps.

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 administrator. Your DOMAIN iscfapps.. For example: cf push my-app creates the URL my-app.cfapps..

The URL for your app must be unique from other apps that PWS 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.

Sample App Step
Run cf push pong_matcher_ruby -n HOST_NAME.

Example: cf push pong_matcher_ruby -n pongmatch-ex12

The example below shows the terminal output of deploying the pong_matcher_ruby app. cf push 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 redis 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.

Note: The pong_matcher_ruby app does not include a web interface. To interact with the pong_matcher_ruby app, see the interaction instructions on GitHub: https://github.com/cloudfoundry-samples/pong_matcher_ruby.

$ 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 clouduser@example.com...
OK

Creating route pongmatch-ex12.cfapps.
        Binding pongmatch-ex12.cfapps. to pong_matcher_ruby...
OK

Uploading pong_matcher_ruby...
Uploading app files from: /Users/clouduserl/workspace/pong_matcher_ruby
Uploading 8.8K, 12 files
OK
Binding service redis to app pong_matcher_ruby in org Cloud-Apps / space development as clouduser@example.com...
OK

Starting app pong_matcher_ruby in org Cloud-Apps / space development as clouduser@example.com...
OK
...

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 clouduser@example.com...
OK

requested state: started
instances: 1/1
usage: 256M x 1 instances
urls: pongmatch-ex12.cfapps.io

     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 PWS!

Use the cf CLI or the Apps Manager to review information and administer your app and your PWS 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 section for more information. See also Using the Apps Manager.

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 Getting Started with cf CLI topic.

Note: You cannot perform certain tasks in the CLI or the Apps Manager because these are commands that only a PWS administrator can run. If you are not a PWS administrator, the following message displays for these types of commands: error code: 10003, message: You are not authorized to perform the requested action For more information about specific Admin commands you can perform with the Apps Manager, depending on your user role, refer to the Getting Started with the Apps Manager topic.

Troubleshooting

If your application fails to start, verify that the application starts in your local environment. Refer to the Troubleshooting Application Deployment and Health topic to learn more about troubleshooting.

App Deploy Fails

Even when deploying an app fails, the app might exist on PWS. Run cf apps to review the apps in the currently targeted org and space. You might be able to correct the issue using the CLI or the Apps Manager, 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 App Requires Unique URL.

App Requires Unique URL

PWS requires that each app that you deploy has a unique URL. Otherwise, the new app URL collides with an existing app URL and PWS 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.
Was this helpful?
What can we do to improve?
View the source for this page in GitHub