Getting Started Deploying Ruby on Rails Apps

Page last updated:

This guide walks you through deploying a Ruby on Rails app to Pivotal Web Services (PWS).


Before you deploy your app to PWS, ensure you have the following:

If you want to follow this tutorial using a sample app and a managed PostgreSQL service, clone the rails-sample app from GitHub by running the following command:

$ git clone

Step 1: Log in to Cloud Foundry

To log in to your Cloud Foundry instance and target its API endpoint, do the following:

  1. Run the cf login -a API-URL command, where API-URL is the API endpoint for the instance. Use as your API endpoint.

  2. Enter your credentials to log in and to select a Space and Org.

Step 2: (Optional) Create Service Instances

Note: If you use the sample Ruby on Rails app to go through this tutorial, Step 2 is not optional.

An app that uses services, such as a database, messaging, or email server, is not fully functional until you provision the services and, if required, bind the services to the app. You can use either the CLI or Apps Manager to perform this task.

You can provision service instances for an app that has already been pushed to Cloud Foundry. For more information about creating and using service instances, refer to the Services Overview topic.

Create a Service Instance

To create a service instance:

  1. Confirm service availability in the Marketplace:

    $ cf marketplace
  2. Run the cf create-service SERVICE-NAME PLAN-NAME SERVICE-INSTANCE-NAME command. See the following example for the sample Ruby on Rails app:

    $ cf create-service elephantsql turtle rails-postgres
    Creating service rails-postgres in org my-org / space development as

    In the command above, elephantsql is the name of the service, turtle is the name of the service plan, and rails-postgres is the unique name you gave your service instance.

Bind a Service Instance

When you bind a service instance to an app, Cloud Foundry writes information about the service instance to the VCAP_SERVICES 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 whether they support this functionality. To bind a service instance to your app, you can do one of the following:

  • Specify your service instance in the services sub-block of the app manifest file, which enables Cloud Foundry to bind the service instance to the app during deployment. See the following excerpt from the manifest file of the sample Ruby on Rails app:

        - rails-postgres
  • Bind a service instance after pushing your app to Cloud Foundry:

    $ cf bind-service APP-NAME SERVICE-INSTANCE-NAME

    Note: You must restart or in some cases re-push your app for changes to be applied to the VCAP_SERVICESenvironment variable and for the app to recognize these changes.

Step 3: Define Deployment Options

You can define deployment options on the command line, in a manifest file, or both together.

(Optional) Configure the Deployment Manifest

You can specify app deployment options in a manifest that the cf push command uses. See the manifest file for the sample Ruby on Rails app:

- name: rails-sample
  memory: 256M
  instances: 1
  path: .
  command: bundle exec rake db:migrate && bundle exec rails s -p $PORT
    - rails-postgres

For more information about app manifests and supported attributes, refer to the Deploying with Application Manifests topic.

(Optional) Configure a Production Server

For Ruby and Ruby on Rails apps, PWS uses WEBrick, the default standard Ruby web server library. 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 with configuring a server other than WEBrick.

Step 4: Deploy a Ruby on Rails App

To deploy your app, run cf push APP-NAME from the root directory of the app.

The cf push APP-NAME command creates a URL route to your app in the HOST.DOMAIN format, where HOST is your APP-NAME and DOMAIN is specified by your administrator. For example, for the domain, running cf push APP-NAME creates the URL.

If the URL for your app is not unique, the deployment fails. For more information about creating unique URLs, see the Configure Domains section of the Deploy an Application topic.

See the following example for a sample Ruby on Rails app:

$ cf push rails-sample
Using manifest file ~/workspace/rails_sample_app/manifest.yml

Updating app rails-sample in org Cloud-Apps / space development as

Using route
Uploading rails-sample...
Uploading app files from: ~/workspace/rails_sample_app
Uploading 445.7K, 217 files
Binding service rails-postgres to app rails-sample in org Cloud-Apps / space development as

Starting app rails-sample 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 rails-sample 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-08-25 03:32:10 PM   0.0%   68.4M of 256M   73.4M of 1G

The example above shows that the cf push command 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 rails-postgres service and starts one instance of the app with 256 MB of RAM. After the app starts, the output displays the health and status of the app.

Note: If you want to view log activity while the app is deployed, launch a new terminal window and run cf logs APP-NAME.

You can verify that your app is running by browsing to the URL generated in the output of the cf push command.

Step 5: (Optional) Configure Service Connections

For Ruby on Rails versions 4.0.0 and earlier, the Ruby buildpack overwrites the config/database.yml file using the contents of the DATABASE_URL environment variable. This variable can be set by the user, or it will be automatically set based on bound service instances.

For Ruby on Rails versions 4.1.0 and later, the Ruby buildpack does not modify the config/database.yml file.

When the app starts, the standard Ruby on Rails behavior for DATABASE_URL and config/database.yml applies.

What to Do Next

You have deployed an app to PWS. Consult the sections below for information about what to do next.

Test a Deployed App

Use the cf CLI or Apps Manager to review information and administer your app and your PWS account. For example, you could edit the manifest.yml file to increase the number of app instances from 1 to 3 or redeploy the app with a new app name.

Manage Your App with the cf CLI

Run cf help to view a complete list of commands and run cf help COMMAND for detailed information about a specific command. For more information about using the cf CLI, refer to the cf CLI topics, especially the Getting Started with cf CLI topic.


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

Create a pull request or raise an issue on the source for this page in GitHub