Fetching contributors…
Cannot retrieve contributors at this time
266 lines (195 sloc) 12.1 KB
title: Deploy an Application
owner: CAPI
<strong><%= modified_date %></strong>
<p class="note"><strong>Note</strong>: See the <a href="../../buildpacks/">buildpacks</a> documentation for deployment guides specific to your app language or framework, such as the <a href="../../buildpacks/ruby/gsg-ror.html">Getting Started Deploying Ruby on Rails Apps</a> guide.</p>
## <a id='intro'></a>Overview of Deployment Process ##
You deploy an app to Cloud Foundry by running a `cf push` command from the Cloud Foundry Command Line Interface (cf CLI).
Refer to the [Installing the cf CLI](../../cf-cli/install-go-cli.html) topic for more information.
Between the time that you run `cf push` and the time that the app is available, Cloud Foundry performs the following tasks:
* Uploads and stores app files
* Examines and stores app metadata
* Creates a "droplet" (the Cloud Foundry unit of execution) for the app
* Selects an appropriate Diego [cell](../../concepts/architecture/index.html#diego-cell) to run the droplet
* Starts the app
For more information about the lifecycle of an app, see the <a href="app-lifecycle.html">Application Container Lifecycle</a> topic.
An app 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 app.
For more information about services, see the [Services Overview](../services/index.html) topic.
## <a id='prepare'></a>Step 1: Prepare to Deploy ##
Before you deploy 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.
* All required app 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
app directory structure, particularly if your app is large.
* An instance of every service that your app needs has been created.
* Your Cloud Foundry instance supports the type of app you are going to
deploy, or you have the URL of an externally available buildpack that can stage
the app.
For help preparing to deploy your app, see:
* [Considerations for Designing and Running an Application in the Cloud](./prepare-to-deploy.html)
* [Buildpacks](../../buildpacks/index.html)
## <a id='logon-target'></a>Step 2: Know Your Credentials and Target ##
Before you can push your app to Cloud Foundry you need to know:
* The API endpoint for your Cloud Foundry instance. Also known as the target
URL, this is <%=vars.api_endpoint%>.
* Your username and password for your Cloud Foundry instance.
* The organization and space where you want to deploy your app.
A Cloud Foundry workspace is organized into organizations, and within them,
As a Cloud Foundry user, you have access to one or more organizations and
## <a id='domain'></a>Step 3: (Optional) Configure Domains ##
Cloud Foundry directs requests to an app using a route, which is a URL
made up of a host and a domain.
* The name of an app is the default host for that app, unless you specify the host name with the <code>-n</code> flag.
* Every app is deployed to an app space that belongs to a
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 app space.
<p class='note'><strong>Note</strong>:
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 <%=vars.product_short%>. Use the following options with the [cf CLI](../../cf-cli/index.html) 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
<p class='note'><strong>Note</strong>: Use <code>cf help push</code> to view other options for this command.</p>
For more information about domains, see [Routes and Domains](./routes-domains.html).
## <a id='options'></a>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 as the name of your app.
* **Instances**: Generally speaking, the more 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, we recommend 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.
<p class='note'><strong>Note</strong>: 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.</p>
* **Start Command**: This is the command that Cloud Foundry uses to start each
instance of your app.
This start command varies by app framework.
* **Subdomain (host) and Domain**:
The route, which is the combination of subdomain and domain, must be globally
This is true whether you specify a portion of the route or allow Cloud Foundry
to use defaults.
* **Services**: Apps can bind to services such as databases, messaging,
and key-value stores.
Apps are deployed into app spaces.
An app can only bind to a service that has an existing instance in the
target app space.
### <a id='defining-options'></a>Define Deployment Options ###
You can define deployment options on the command line, in a manifest file, or
both together.
See [Deploying with Application Manifests](./manifest.html) to learn how
app settings change from push to push, and how command-line options,
manifests, and commands like `cf scale` interact.
When you deploy an app while it is running, Cloud Foundry stops all instances of that app and then deploys.
Users who try to run the app 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 app files except version control files and
folders with names such as `.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.
For more information, see the [Ignore Unnecessary Files When Pushing](./prepare-to-deploy.html#exclude) section of the [Considerations for Designing and Running an Application in the Cloud](./prepare-to-deploy.html) topic.
For more information about the manifest file, see the [Deploying with Application Manifests](./manifest.html) topic.
### <a id='profile'></a>Configure Pre-Runtime Hooks ###
<p class="note"><strong>Note</strong>: The Java buildpack does not support pre-runtime hooks.</p>
To configure pre-runtime hooks, create a file named `.profile` and place it in the root of your app directory.
If the directory includes a `.profile` script, then Cloud Foundry executes it immediately before each instance of your app starts.
Because the `.profile` script executes after the buildpack, the script has access to the language runtime environment created by the buildpack.
<p class="note"><strong>Note</strong>: Your app root directory may also include a <code>.profile.d</code> directory that contains bash scripts that perform initialization tasks for the buildpack.
Developers should not edit these scripts unless they are using a <a href="../../buildpacks/custom.html">custom buildpack</a>.</p>
You can use the `.profile` script to perform app-specific initialization tasks, such as setting custom environment variables.
Environment variables are key-value pairs defined at the operating system level.
These key-value pairs provide a way to configure the apps running on a system.
For example, any app 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 the appropriate bash commands to your `.profile` file. See the example below.
# Set the default LANG for your apps
export LANG=en_US.UTF-8
<p class="note"><strong>Note</strong>: If you are using a PHP buildpack version prior to v4.3.18, the buildpack does not execute your PHP app's <code>.profile</code> script. Your PHP app will host the <code>.profile</code> script's contents.
This means that any PHP app staged using the affected PHP buildpack versions can leak credentials placed in the <code>.profile</code> script.</p>
## <a id='push'></a>Step 5: Push the App ##
Run the following command to deploy an app without a manifest:
`cf push APP-NAME`
If you provide the app name in a manifest, you can reduce the command to
`cf push`.
See [Deploying with Application Manifests](./manifest.html).
Because all you have provided is the name of your app, `cf push` sets the
number of instances, amount of memory, and other attributes of your app
to the default values.
You can also use command-line options to specify these and additional
The following transcript illustrates how Cloud Foundry assigns default values
to app when given a `cf push` command.
<p class ="note"><strong>Note</strong>: When deploying your own apps, avoid generic names like <code>my-app</code>. Cloud Foundry uses the app name to compose the route to the app, and deployment fails unless the app has a globally unique route.</p>
<pre class="terminal">
$ cf push my-app
Creating app my-app in org example-org / space development as a.user@<%=vars.app_domain%>...
Creating route my-app.<%=vars.app_domain%>...
Binding my-app.<%=vars.app_domain%> to my-app...
Uploading my-app...
Uploading app: 560.1K, 9 files
Starting app my-app in org example-org / space development as a.user@<%= vars.app_domain %>...
-----> Downloaded app package (552K)
-----> 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 a.user@<%=vars.app_domain%>...
requested state: started
instances: 1/1
usage: 1G x 1 instances
urls: my-app.<%=vars.app_domain%>
state since cpu memory disk
#0 running 2014-01-24 05:07:18 PM 0.0% 18.5M of 1G 52.5M of 1G
## <a id='service-connection'></a>Step 6: (Optional) Configure Service Connections ##
If you bound a service to the app that you deployed, you might need to
configure your app with the service URL and credentials.
For more information, see the specific documentation for your app
* [Ruby](../../buildpacks/ruby/ruby-service-bindings.html)
* [Node.js](../../buildpacks/node/node-service-bindings.html)
* [Spring](../../buildpacks/java/configuring-service-connections/spring-service-bindings.html)
* [Grails](../../buildpacks/java/configuring-service-connections/grails-service-bindings.html)
## <a id='troubleshoot-push'></a>Step 7: Troubleshoot Deployment Problems ##
If your app does not start on Cloud Foundry, first ensure that your
app can run locally.
You can troubleshoot your app in the cloud using the cf CLI.
See [Troubleshoot Application Deployment and Health](./troubleshoot-app-health.html).