Deploy an Application

Page last updated: December 11, 2015

This page assumes that you are using cf CLI v6.

Note: See the buildpacks documentation for complete deployment guides specific to your application language or framework, such as the Getting Started Deploying Ruby on Rails Apps guide.

Overview of Deployment Process

You deploy an application to Cloud Foundry by running a push command from a Cloud Foundry command line interface (CLI). Refer to the Install cf CLI v6 topic for more information. Between the time that you run push and the time that the application is available, Cloud Foundry performs the following tasks:

Uploads and stores application files
Examines and stores application metadata
Creates a “droplet” (the Cloud Foundry unit of execution) for the application
Selects an appropriate droplet execution agent (DEA) to run the droplet
Starts the application

An application that uses services, such as a database, messaging, or email server, is not fully functional until you provision the service and, if required, bind the service to the application. For more information about services, see the Services Overview topic.

Step 1: Prepare to Deploy

Before you deploy your application to Cloud Foundry, make sure that:

Your application is cloud-ready. Cloud Foundry behaviors related to file storage, HTTP sessions, and port usage may require modifications to your application.
All required application resources are uploaded. For example, you may need to include a database driver.
Extraneous files and artifacts are excluded from upload. You should explicitly exclude extraneous files that reside within your application directory structure, particularly if your application is large.
An instance of every service that your application needs has been created.
Your Cloud Foundry instance supports the type of application you are going to deploy, or you have the URL of an externally available buildpack that can stage the application.

For help preparing to deploy your application, see:

Step 2: Know Your Credentials and Target

Before you can push your application to Cloud Foundry you need to know:

The API endpoint for your Cloud Foundry instance. Also known as the target URL, this is the URL of the Cloud Controller in your Cloud Foundry instance.
Your username and password for your Cloud Foundry instance.
The organization and space where you want to deploy your application. A Cloud Foundry workspace is organized into organizations, and within them, spaces. As a Cloud Foundry user, you have access to one or more organizations and spaces.

Step 3: (Optional) Configure Domains

Cloud Foundry directs requests to an application using a route, which is a URL made up of a host and a domain.

The name of an application is the default host for that application, unless you specify the host name with the -n flag.
Every application is deployed to an application space that belongs to a domain. Every Cloud Foundry instance has a default domain defined. You can specify a non-default, or custom, domain when deploying, provided that the domain is registered and is mapped to the organization which contains the target application space.

Note: CF allows app names, but not app URLs, to include underscores. CF converts underscores to hyphens when setting a default app URL from an app name.

The URL for your app must be unique from other apps hosted by Cloud Foundry. Use the following options with the cf CLI 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

Note: Use cf help push to view other options for this command.

For more information about domains, see Routes and Domains.

Step 4: Determine Deployment Options

Before you deploy, you need to decide on the following:

Name: You can use any series of alpha-numeric characters, without spaces, as the name of your application.
Instances: Generally speaking, the more instances you run, the less downtime your application will experience. If your application is still in development, running a single instance can simplify troubleshooting. For any production application, we recommend a minimum of two instances.
Memory Limit: The maximum amount of memory that each instance of your application can consume. If an instance exceeds this limit, Cloud Foundry restarts the instance.
Note: Initially, Cloud Foundry immediately restarts any instances that exceed the memory limit. If an instance repeatedly exceeds the memory limit in a short period of time, Cloud Foundry delays restarting the instance.
Start Command: This is the command that Cloud Foundry uses to start each instance of your application. This start command varies by application framework.
Subdomain (host) and Domain: The route, which is the combination of subdomain and domain, must be globally unique. This is true whether you specify a portion of the route or allow Cloud Foundry to use defaults.
Services: Applications can bind to services such as databases, messaging, and key-value stores. Applications are deployed into application spaces. An application can only bind to a service that has an existing instance in the target application space.

Define Deployment Options

You can define deployment options on the command line, in a manifest file, or both together. See Deploying with Application Manifests to learn how application settings change from push to push, and how command-line options, manifests, and commands like cf scale interact.

When you deploy an application while it is running, Cloud Foundry stops all instances of that application and then deploys. Users who try to run the application get a “404 not found” message while cf push runs. Stopping all instances is necessary to prevent two versions of your code from running at the same time. A worst-case example would be deploying an update that involved a database schema migration, because instances running the old code would not work and users could lose data.

Cloud Foundry uploads all application files except version control files with file extensions .svn, .git, and .darcs. To exclude other files from upload, specify them in a .cfignore file in the directory where you run the push command. This technique is similar to using a .gitignore file. For more information, see the Ignore Unnecessary Files When Pushing section of the Considerations for Designing and Running an Application in the Cloud topic.

For more information about the manifest file, see the Deploying with Application Manifests topic.

Set Environment Variables

Environment variables are key-value pairs defined at the operating system level. These key-value pairs provide a way to configure the applications running on a system. For example, any application can access the LANG environment variable to determine which language to use for error messages and instructions, collating sequences, and date formats.

To set an environment variable, add a bash script to the .profile.d directory in the source code of your application. Cloud Foundry runs this script when deploying each instance of your application.

Note: You must give your shell scripts a .sh extension.

Example .profile.d/setenv.sh script:

# Set the Java environment path for your applications
export JAVA_HOME=/usr/lib/jvm/jdk1.7.0
export PATH=$PATH:$JAVA_HOME/bin

# Set the default LANG for your applications
export LANG=en_US.UTF-8

Step 5: Push the Application

Run the following command to deploy an application without a manifest:

cf push APP-NAME

If you provide the application name in a manifest, you can reduce the command to cf push. See Deploying with Application Manifests.

Since all you have provided is the name of your application, cf push sets the number of instances, amount of memory, and other attributes of your application to the default values. You can also use command-line options to specify these and additional attributes.

The following transcript illustrates how Cloud Foundry assigns default values to application when given a cf push command.

Note: When deploying your own apps, avoid generic names like my-app. Cloud Foundry uses the app name to compose the route to the app, and deployment fails unless the app has a globally unique route.

    $ cf push my-app
    Creating app my-app in org example-org / space development as [email protected]...
    OK

    Creating route my-app.shared-domain.com...
    OK

    Binding my-app.shared-domain.com to my-app...
    OK

    Uploading my-app...
    Uploading app: 560.1K, 9 files
    OK

    Starting app my-app in org example-org / space development as [email protected]...
    -----> Downloaded app package (552K)
    OK
    -----> Using Ruby version: ruby-1.9.3
    -----> Installing dependencies using Bundler version 1.3.2
           Running: bundle install --without development:test --path
             vendor/bundle --binstubs vendor/bundle/bin --deployment
           Installing rack (1.5.1)
           Installing rack-protection (1.3.2)
           Installing tilt (1.3.3)
           Installing sinatra (1.3.4)
           Using bundler (1.3.2)
           Updating files in vendor/cache
           Your bundle is complete! It was installed into ./vendor/bundle
           Cleaning up the bundler cache.
    -----> Uploading droplet (23M)

    1 of 1 instances running

    App started

    Showing health and status for app my-app in org example-org / space development as [email protected]...
    OK

    requested state: started
    instances: 1/1
    usage: 1G x 1 instances
    urls: my-app.shared-domain.com

         state     since                    cpu    memory        disk
    #0   running   2014-01-24 05:07:18 PM   0.0%   18.5M of 1G   52.5M of 1G

Step 6: (Optional) Configure Service Connections

If you bound a service to the application that you deployed, you might need to configure your application with the service URL and credentials. For more information, see the specific documentation for your application framework:

Step 7: Troubleshoot Deployment Problems

If your application does not start on Cloud Foundry, first ensure that your application can run locally.

You can troubleshoot your application in the cloud using the cf CLI. See Troubleshoot Application Deployment and Health.