Pushing an App

This topic describes how to use the Cloud Foundry Command Line Interface (cf CLI) to push an app to Cloud Foundry.

Overview

The cf CLI command cf push pushes apps to Cloud Foundry. There are two main ways to run the cf push command:

  • Run cf push APP-NAME to push an app the easiest way, using default settings.
  • Run the cf push command with flags and helper files to customize:
    • How the pushed app runs, including its route (URL), instance count, and memory limits.
    • How the push process works: whether it’s configured with a manifest, runs a startup script, or limits files uploaded to the Cloud Controller.

The Push with Defaults and Push with Custom Settings sections below detail both of these options.

For an explanation of what Cloud Foundry does when you run cf push, see How Apps are Staged.

For information about the lifecycle of an app, see App Container Lifecycle

Prerequisites

Before you push your app to Cloud Foundry, make sure that:

  • Your app is cloud-ready. Cloud Foundry behaviors related to file storage, HTTP sessions, and port usage may require modifications to your app. For help preparing your app to be pushed to Cloud Foundry, see:

  • Your Cloud Foundry installation supports the type of app you are going to push, or you have the URL of an externally-available buildpack that can stage the app.

  • All required app resources are uploaded. For example, you may need to include a database driver.

  • You have your target and credentials:

  • You are logged into your app’s target org and space.

    1. Decide the org and space where you want to push your app. You may have access to one or more org and space.
    2. Log into this target org and space with cf login.
  • Your app can access every service that it uses, because an instance of the service runs in, or is shared with, the app’s space.

    • See Sharing Service Instances for how to share service instances across spaces.
    • Typical services that cloud apps use include databases, message queues, and key-value stores.

Push with Defaults

To push an app with default settings, do the following:

  1. Choose a name for the app.

    • The app name must consist of alphanumeric characters.
    • The app name must be unique to your Cloud Foundry installation.
      • To use an app name that is not unique, customize the app’s route as described in Customize the Route below.
      • Apps running at their default routes require unique names because default routes are based on app names, and all routes must be globally unique.
  2. Run the following command:

    cf push APP-NAME
    

    Where APP-NAME is the name of the app.

Default Route

An app’s route is the URL that it runs at. Cloud Foundry assembles the route for a pushed app from a hostname and a domain.

By default, Cloud Foundry sets the hostname and domain as follows:

  • Hostname: The name of the app, as specified in the cf push command.

    • If the app name contains underscores, Cloud Foundry converts them to hyphens when creating the app’s route.
  • Domain: The default apps domain for the Cloud Foundry installation.

For example, an app named my-app-1234 running on Cloud Foundry with an apps domain apps.example.com would, by default, run at the URL https://my-app-1234.apps.example.com.

For more information about routes and domains, see Routes and Domains.

Example Session

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

    $ cf push my-app-1234
    Creating app my-app-1234 in org example-org / space development as a.user@shared-domain.example.com...
    OK

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

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

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

    Starting app my-app-1234 in org example-org / space development as a.user@shared-domain.example.com...
    -----> 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-1234 in org example-org / space development as a.user@shared-domain.example.com...
    OK

    requested state: started
    instances: 1/1
    usage: 1G x 1 instances
    urls: my-app-1234.shared-domain.example.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

Push with Custom Settings

Pushing an app with with custom settings typically proceeds as follows:

  1. (Optional) Customize Basic App Settings
  2. (Optional) Customize the Route
  3. (Optional) Limit the Upload Files
  4. (Optional) Configure App Initialization
  5. Custom Push the App
  6. (Optional) Configure App Services

The sections below detail these steps.

(Optional) Customize Basic App Settings

Basic settings to customize when pushing an app include:

  • Name: You can use any series of alphanumeric characters as the name of your app.
  • Instances: Generally speaking, the more app instances you run, the less downtime your app will experience. If your app is still in development, running a single instance can simplify troubleshooting. For any production app, Cloud Foundry recommends a minimum of two instances.
  • Memory Limit: The maximum amount of memory that each instance of your app can consume. If an instance exceeds this limit, Cloud Foundry restarts the instance. If an instance exceeds its memory limit repeatedly 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 app. This start command differs by app framework.

(Optional) Customize the Route

To customize an app’s route, do the following:

  1. (Optional) Customize the Hostname

    • Pass the custom hostname into cf push with the -n flag.
  2. (Optional) Customize the Domain

    • Pass the custom domain into cf push with the -d flag. The custom domain must be registered, and mapped to the org that contains the app’s target space
  3. Ensure Route Uniqueness

    • The app’s route must be globally unique, whether you customize its host or domain, or let it use the Default Route described above.
    • To help ensure route uniqueness, pass the --random-route option into cf push. --random-route creates a route that includes the app name and random words

(Optional) Limit the Upload Files

By default, Cloud Foundry uploads all app files except version control files and folders with names such as .svn, .git, and _darcs.

Cloud Foundry recommends that you explicitly exclude extraneous files residing within your app directory, particularly if your app is large. For example, if you build your app locally and push it as a binary, you can save resources by not uploading any of the app’s source code.

To exclude files from upload:

  1. Create a .cfignore file that lists the files to exclude.

  2. Save the .cfignore file to the directory where you run the cf push command.

For more information, see the Ignore Unnecessary Files When Pushing section of the Considerations for Designing and Running an App in the Cloud topic.

(Optional) Configure App Initialization

Note: The Java buildpack does not support an initialization script.

You can configure cf push to run custom initialization tasks for an app.

These tasks run after Cloud Foundry loads the app droplet but before it launches the app itself to let the initialization script access the app language runtime environment. For example, your script can map values from $VCAP_SERVICES into other environment variables or a config file that the app uses.

To run initialization tasks:

  1. Create a .profile script that contains the initialization tasks.

  2. Save the .profile script to the directory where you run the cf push command.

As an example, the following .profile file uses bash to set a value for the environment variable LANG. Setting this value at the operating system level lets the app determine which language to use for error messages and instructions, collating sequences, and date formats:

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

Your app root directory may also include a .profile.d directory that contains bash scripts that perform initialization tasks for the buildpack. Developers should not edit these scripts unless they are using a custom buildpack.

Note: If you are using a PHP buildpack version prior to v4.3.18, the buildpack does not execute your PHP app’s .profile script. Your PHP app will host the .profile script’s contents. This means that any PHP app staged using the affected PHP buildpack versions can leak credentials placed in the .profile script.

Initialization tasks as described here are also called “pre-runtime hooks” and “.profile tasks”.

Custom Push the App

To specify custom options when pushing an app with cf push, you can:

  • Include them in the cf push APP-NAME command itself.
  • Include them in a manifest file.
    • The manifest file must be named manifest.yml and reside in the directory where you run cf push.
    • The manifest can include the app name, which lets you run cf push with no arguments.
    • The manifest can also include a Services block that lists service instances for the app to bind to automatically.
  • Both of the above, command-line options and a manifest.

See Deploying with App Manifests to learn how app settings change from push to push, and how command-line options, manifests, and commands like cf scale interact.

See the Cloud Foundry CLI Reference Guide for a full list of cf push options.

(Optional) Configure App Services

If a newly-pushed app has the same name and route as an older app version, the new app retains the service bindings and service configuration of the previously-pushed version.

For apps that are not already set up for the services that they use, you need to:

  1. Bind the services to the app. For more information about services, see the Services Overview topic.

  2. (Optional) Configure the app with the service URL and credentials, if needed. For more information, see the specific documentation for your app framework, such as:

App Updates and Downtime

When you push an app that is already running, Cloud Foundry stops all existing instances of that app. Users who try to access the app get a “404 Not Found” message while cf push runs.

With some app updates, old and new versions of your code should never run at the same time. A worst-case example is if your app update migrates a database schema, causing old app instances to fail and lose user data. To prevent this, you need to stop all running instances of your app before you push the new version.

When old and new versions of your app can run simultaneously, you can avoid app downtime by using the blue-green method to swap routes between app versions running in parallel.

Troubleshoot App Push Problems

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

For how to troubleshoot your app in the cloud using the cf CLI, see Troubleshoot App Deployment and Health.

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