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:
- A Ruby on Rails app that runs locally
- Bundler installed on your machine
- Your username and password for the targeted Cloud Foundry instance that have Space Developer permissions
- The Cloud Foundry Command Line Interface (cf CLI)
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 https://github.com/cloudfoundry-samples/rails_sample_app
To log in to your Cloud Foundry instance and target its API endpoint, do the following:
cf login -a API-URLcommand, where
API-URLis the API endpoint for the instance. Use
api.run.pivotal.ioas your API endpoint.
Enter your credentials to log in and to select a Space and Org.
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:
Confirm service availability in the Marketplace:
$ cf marketplace
cf create-service SERVICE-NAME PLAN-NAME SERVICE-INSTANCE-NAMEcommand. 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 email@example.com.... OK
In the command above,
elephantsqlis the name of the service,
turtleis the name of the service plan, and
rails-postgresis 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
servicessub-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:
services: - 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.
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:
--- applications: - name: rails-sample memory: 256M instances: 1 path: . command: bundle exec rake db:migrate && bundle exec rails s -p $PORT services: - 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.
To deploy your app, run
cf push APP-NAME from the root directory of the app.
cf push APP-NAME command creates a URL route to your app in the
HOST.DOMAIN format, where
HOST is your
DOMAIN is specified by your administrator. For example, for the
cfapps.io domain, running
cf push APP-NAME creates the
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 firstname.lastname@example.org... OK Using route rails-sample.cfapps.io Uploading rails-sample... Uploading app files from: ~/workspace/rails_sample_app Uploading 445.7K, 217 files OK Binding service rails-postgres to app rails-sample in org Cloud-Apps / space development as email@example.com... OK Starting app rails-sample in org Cloud-Apps / space development as firstname.lastname@example.org... OK ... 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 email@example.com... OK requested state: started instances: 1/1 usage: 256M x 1 instances urls: rails-sample.cfapps.io 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.
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
When the app starts, the standard Ruby on Rails behavior for
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
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.