Pushing your app with Cloud Foundry CLI (cf push)
- Push with defaults
- Push with custom settings
- App updates and downtime
- Troubleshoot app push problems
Page last updated:
The cf CLI command
cf push pushes apps to Cloud Foundry. There are two main ways to run the
cf push command:
cf push APP-NAMEto push an app the easiest way, using default settings. For more information, see Push with Defaults.
cf pushcommand with flags and helper files to customize:
- How the pushed app runs, including its route, instance count, disk size limits, memory limits, and log rate 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.
For more information about custom settings, see Push with Custom Settings.
For an explanation of what Cloud Foundry does when you run
cf push, see How Apps are
For information about the lifecycle of an app, see App Container Lifecycle.
Before you push your app to Cloud Foundry, ensure the following:
Your app is cloud-ready. Cloud Foundry behaviors related to file storage, HTTP sessions, and port usage might require modifications to your app. To prepare an app to be pushed to Cloud Foundry, see:
- Considerations for Designing and Running an App in the Cloud
- Any Buildpacks guides specific to your app language or framework, such as Getting Started Deploying Ruby on Rails Apps
Your Cloud Foundry deployment 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 might need to include a database driver.
You have your target and credentials:
- The API endpoint for your Cloud Foundry deployment. 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 deployment.
You are logged into your app’s target org and space.
- Decide the org and space where you want to push your app. You might have access to one or more org and space.
- Log into this target org and space with
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.
- For information about sharing service instances across spaces, see Sharing Service Instances.
- Typical services that cloud apps use include databases, message queues, and key-value stores.
Push with defaults
To push an app with default settings:
Choose a name for the app. The app name must consist of alphanumeric characters and be unique to your Cloud Foundry deployment.
- To use an app name that is not unique, customize the app’s route as described in Customize the Route.
- Apps running at their default routes require unique names because default routes are based on app names, and all routes must be globally unique.
cf push APP-NAME
APP-NAMEis the name of the app.
An app’s route is the URL at which it runs. 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 name, as specified in the
cf pushcommand. If the app name contains underscores, Cloud Foundry converts them to hyphens when creating the app’s route.
Domain: The default apps domain for your Cloud Foundry deployment.
For example, an app named
example-app running on Cloud Foundry with an apps domain
apps.example.com would run at the URL
https://example-app.apps.example.com by default.
For more information about routes and domains, see Routes and Domains.
The following example output for
cf push example-app demonstrates how Cloud Foundry assigns default values to an app you push:
Creating app example-app in org example-org / space development as email@example.com... OK Creating route example-app.shared-domain.example.com... OK Binding example-app.shared-domain.example.com to example-app... OK Uploading example-app... Uploading app: 560.1K, 9 files OK Starting app example-app 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 example-app in org example-org / space development as email@example.com... OK requested state: started instances: 1/1 usage: 1G x 1 instances urls: example-app.shared-domain.example.com state since cpu memory disk logging #0 running 2022-09-14 05:07:18 PM 0.0% 18.5M of 1G 52.5M of 1G 3B/s of 1M/s
Push with custom settings
Pushing an app with custom settings typically proceeds as follows:
The following sections detail these steps.
Customize basic app settings (optional)
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 experiences. 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 app instance exceeds this limit, Cloud Foundry restarts the instance. If an app instance exceeds its memory limit repeatedly in a short period of time, Cloud Foundry delays restarting the app instance.
Disk space limit: The maximum amount of disk space that each instance of your app can consume. If an app instance exceeds this limit, Cloud Foundry restarts the instance. If an app instance exceeds its disk space limit repeatedly in a short period of time, Cloud Foundry delays restarting the app instance.
Log rate limit: The maximum number of logs that each instance of your app can send to Loggregator. If an app instance exceeds this limit, Cloud Foundry drops the excess logs and reports doing so.
Start command: This is the command that Cloud Foundry uses to start each instance of your app. This start command differs by app framework.
Customize the route (optional)
To customize an app’s route:
(Optional) Customize the hostname by including the
-nflag followed by a custom hostname in your
(Optional) Customize the domain by including the
-dflag followed by a custom domain in your
cf pushcommand. The custom domain must be registered, and mapped to the org that contains the app’s target space.
Ensure that the route is unique. The app’s route must be globally unique, whether you customize its host or domain, or let it use the default route described in Default Route above. To help ensure route uniqueness, include the
--random-routeflag in your
cf pushcommand. This creates a route that includes the app name and random words.
Limit the upload files (optional)
By default, Cloud Foundry uploads all app files except version control files and folders with names such as
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:
.cfignorefile that lists the files to exclude.
.cfignorefile to the directory where you run the
For more information, see Ignore Unnecessary Files When Pushing in Considerations for Designing and Running an App in the Cloud.
Configure app initialization (optional)
You can configure the
cf push command 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
- Java: Initialization scripts for the Java buildpack require additional configuration.For more information, see How to Modify the Application Container Environment prior to Application Execution in the VMware Tanzu Knowledge Base.
- PHP: Cloud Foundry does not support initialization scripts for the PHP buildpack versions prior to v4.3.18. If you use
one of these buildpack versions, your app hosts the
.profilescript’s contents. This means that any app staged using the affected buildpack versions can leak credentials placed in the
To run initialization tasks:
.profilescript that contains the initialization tasks.
.profilescript to the directory where you run the
The following example
.profile file uses
bash to set a value for the environment variable
# Set the default LANG for your apps export LANG=en_US.UTF-8
Setting this value at the operating system level allows the app to determine which language to use for error messages and instructions, collating sequences, and date formats.
Your app root directory might also include a
.profile.d directory that contains bash scripts that perform initialization tasks for the buildpack. Developers
must not edit these scripts unless they are using a custom buildpack. For more information about custom buildpacks, see Custom
Initialization tasks as described here are also called pre-runtime hooks and
Custom push the app
To specify custom options when pushing an app with
cf push, you can include them in one or both of the following:
cf pushcommand itself.
A manifest file.
- The manifest file must be named
manifest.ymland reside in the directory where you run
- The manifest can include the app name, which lets you run
cf pushwith no arguments.
- The manifest can also include a
servicesblock that lists service instances for the app to bind. For more information, see Services in App Manifest Attribute Reference.
- The manifest file must be named
For information about how app settings change from push to push, including how command-line options, manifests, and commands like
cf scale interact, see
Deploying with App Manifests.
For a full list of
cf push options, see the Cloud Foundry CLI Reference Guide.
Configure app services (optional)
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:
Bind the services to the app. For more information about services, see Services Overview.
(Optional) Configure the app with the service URL and credentials, if needed. For more information, see Configuring Service Connections.
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 see a
404 Not Found message while
cf push runs.
With some app updates, old and new versions of your code must 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 must 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 deployment method to swap routes between app versions running in parallel. For more information, see Using Blue-Green Deployment to Reduce Downtime and Risk.
Troubleshoot app push problems
If your app does not start on Cloud Foundry, first ensure that the app can run locally.
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