The cf CLI command
cf push pushes apps to TAS for VMs. There are two main ways to run the
cf push command:
cf push APP-NAMEto push an app the easiest way, using default settings.
cf pushcommand with flags and helper files to customize:
The Push with Defaults and Push with Custom Settings sections below detail both of these options.
For an explanation of what TAS for VMs does when you run
cf push, see How Apps are Staged.
For information about the lifecycle of an app, see App Container Lifecycle
Before you push your app to TAS for VMs, make sure that:
Your app is cloud-ready. TAS for VMs 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 TAS for VMs, see:
Your TAS for VMs 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.
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.
To push an app with default settings, do the following:
Choose a name for the app.
Run the following command:
cf push APP-NAME
APP-NAME is the name of the app.
An app’s route is the URL that it runs at. TAS for VMs assembles the route for a pushed app from a hostname and a domain.
By default, TAS for VMs sets the hostname and domain as follows:
Hostname: The name of the app, as specified in the
cf push command.
Domain: The default apps domain for the TAS for VMs installation.
For example, an app named
my-app-1234 running on TAS for VMs with an apps domain
apps.example.com would, by default, run at the URL
For more information about routes and domains, see Routes and Domains.
The following session illustrates how TAS for VMs 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 email@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 firstname.lastname@example.org... -----> 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 email@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
Pushing an app with with custom settings typically proceeds as follows:
The sections below detail these steps.
Basic settings to customize when pushing an app include:
To customize an app’s route, do the following:
(Optional) Customize the Hostname
cf pushwith the
(Optional) Customize the Domain
cf pushwith the
-dflag. The custom domain must be registered, and mapped to the org that contains the app’s target space
Ensure Route Uniqueness
--random-routecreates a route that includes the app name and random words
By default, TAS for VMs uploads all app files except version control files and folders with names such as
VMware 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:
.cfignore file that lists the files to exclude.
.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.
You can configure
cf push to run custom initialization tasks for an app.
These tasks run after TAS for VMs 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.
.profilescript's contents. This means that any app staged using the affected buildpack versions can leak credentials placed in the
To run initialization tasks:
.profile script that contains the initialization tasks.
.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.
Initialization tasks as described here are also called “pre-runtime hooks” and “
To specify custom options when pushing an app with
cf push, you can:
cf push APP-NAMEcommand itself.
manifest.ymland reside in the directory where you run
cf pushwith no arguments.
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.
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:
Bind the services to the app. For more information about services, see the Services Overview topic.
(Optional) Configure the app with the service URL and credentials, if needed. For more information, see Configuring Service Connections.
When you push an app that is already running, TAS for VMs 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.
If your app does not start on TAS for VMs, 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.