The cf CLI command cf push
pushes apps to TAS for VMs. There are two main ways to run the cf push
command:
Run cf push APP-NAME
to push an app using default settings. For more information, see Push with defaults.
Run the cf push
command with flags and helper files to customize:
For more information about custom settings, see Push with custom settings.
For an explanation of what TAS for VMs does when you run cf push
, see How Apps are Staged.
For information about the life cycle of an app, see Application container life cycle.
Before you push your app to TAS for VMs, ensure that:
Your app is “cloud-ready.” TAS for VMs behaviors related to file storage, HTTP sessions, and port usage might require modifications to your app. To prepare an app to be pushed to TAS for VMs, see:
Your TAS for VMs 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:
You are logged into your app’s target org and space.
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.
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 TAS for VMs deployment.
Run:
cf push APP-NAME
Where APP-NAME
is the name of the app.
An app’s route is the URL at which it runs. TAS for VMs assembles the route for a pushed app from a host name and a domain.
By default, TAS for VMs sets the host name and domain as follows:
Hostname: The name of the app name, as specified in the cf push
command. If the app name contains underscores, TAS for VMs converts them to hyphens when creating the app’s route.
Domain: The default apps domain for your TAS for VMs deployment.
For example, an app named example-app
running on TAS for VMs with an apps domain apps.example.com
runs 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 TAS for VMs assigns default values to an app you push:
Creating app example-app in org example-org / space development as [email protected]... 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 [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 example-app in org example-org / space development as [email protected]... 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
Pushing an app with custom settings typically proceeds as follows:
The following sections detail these steps.
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, VMware 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, TAS for VMs restarts the instance. If an app instance exceeds its memory limit repeatedly in a short period of time, TAS for VMs 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, TAS for VMs restarts the instance. If an app instance exceeds its disk space limit repeatedly in a short period of time, TAS for VMs 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, TAS for VMs drops the excess logs and reports doing so.
Start command: This is the command that TAS for VMs uses to start each instance of your app. This start command differs by app framework.
By default, TAS for VMs uploads all app files except version control files and directories with names such as .svn
, .git
, and _darcs
.
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:
Create a .cfignore
file that lists the files to exclude.
Save the .cfignore
file to the directory where you run the cf push
command.
For more information, see Ignore Unnecessary Files When Pushing in Considerations for Designing and Running an App in the Cloud.
You can configure the cf push
command to run custom initialization tasks for an app.
These tasks run after TAS for VMs loads the app droplet but before it starts the app to allow the initialization script to 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.
.profile
script's contents. This means that any app staged using the affected buildpack versions can leak credentials placed in the .profile
script. To run initialization tasks:
Create a .profile
script that contains the initialization tasks.
Save the .profile
script to the directory where you run the cf push
command.
The following example .profile
file uses bash
to set a value for the environment variable LANG
:
# 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 find out 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 Buildpacks.
Initialization tasks as described here are also called pre-runtime hooks and .profile
tasks.
To specify custom options when pushing an app with cf push
, you can include them in one or both of the following:
The cf push
command itself.
A manifest file.
manifest.yml
and reside in the directory where you run cf push
.cf push
with no arguments.services
block that lists service instances for the app to bind. For more information, see Services in App Manifest Attribute Reference.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.
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.
The CF CLI includes composible push sub-step commands that empower you to build your own push. These are useful if the default behavior of cf push
does not match your needs, or if you want to implement more complicated app build, promotion, and run workflows.
By default, 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 see a 404 Not Found
message while cf push
runs.
When old and new versions of your app can run simultaneously, you can avoid app downtime by using Rolling deployments. Alternatively, you can use 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.
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.
If your app does not start on TAS for VMs, 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.