anchor.diff:  owner: CAPI
   ---
   
  -This topic describes some considerations you should keep in mind when designing and running an app through <%= vars.product_name %>.
  +This topic describes some considerations you should keep in mind when designing and
  +running an app through <%= vars.platform_name %>.
   
   
   ## <a id="app-design"></a> App Design for the Cloud
   
  -Apps written in supported frameworks often run unmodified on <%= vars.product_name %> if the app design follows a few simple guidelines. Following these guidelines facilitates app deployment to <%= vars.product_name %> and other cloud platforms.
  +Apps written in supported frameworks often run unmodified on <%= vars.platform_name %>
  +if the app design follows a few simple guidelines.
  +Following these guidelines facilitates app deployment to <%= vars.platform_name %> and other cloud platforms.
   
   The following guidelines represent best practices for developing modern apps for cloud platforms. For more detailed reading about good app design for the cloud, see [The Twelve-Factor App](http://www.12factor.net).
   
  -For more information about the features of HTTP routing handled by the Gorouter in <%= vars.product_name %>, see [HTTP Routing](../../concepts/http-routing.html). For more information about the lifecycle of app containers, see [App Container Lifecycle](app-lifecycle.html).
  +For more information about the features of HTTP routing handled by the Gorouter in <%= vars.platform_name %>,
  +see [HTTP Routing](../../concepts/http-routing.html).
  +For more information about the lifecycle of app containers,
  +see [App Container Lifecycle](app-lifecycle.html).
   
   ### <a id="filesystem"></a> Avoid Writing to the Local File System
   
  -Apps running on <%= vars.product_name %> should not write files to the local file system for the following reasons:
  +Apps running on <%= vars.platform_name %> should not write files to the local file system
  +for the following reasons:
   
   * **Local file system storage is short-lived.** When an app instance crashes or stops, the resources assigned to that instance are reclaimed by the platform, including any local disk changes made since the app started. When the instance is restarted, the app starts with a new disk image. Although your app can write local files while it is running, the files disappear after the app restarts.
   
  -* **Instances of the same app do not share a local file system.** Each app instance runs in its own isolated container. Therefore, a file written by one instance is not visible to other instances of the same app. If the files are temporary, this should not be a problem. However, if your app needs the data in the files to persist across app restarts, or the data needs to be shared across all running instances of the app, the local file system should not be used. <%= vars.recommended_by %> recommends using a shared data service like a database or blobstore for this purpose.
  +* **Instances of the same app do not share a local file system.** Each app instance runs
  +  in its own isolated container.
  +  Therefore, a file written by one instance is not visible to other instances of the same app.
  +  If the files are temporary, this should not be a problem.
  +  However, if your app needs the data in the files to persist across app restarts,
  +  or the data needs to be shared across all running instances of the app,
  +  the local file system should not be used. <%= vars.company_name %> recommends
  +  using a shared data service like a database or blobstore for this purpose.
   
  -For example, instead of using the local file system, you can use a <%= vars.product_name %> service such as the MongoDB document database or a relational database like MySQL or Postgres. Another option is to use cloud storage providers such as [Amazon S3](http://aws.amazon.com/s3/), [Google Cloud Storage](https://cloud.google.com/products/cloud-storage), [Dropbox](https://www.dropbox.com/developers), or [Box](http://developers.box.com/). If your app needs to communicate across different instances of itself, consider a cache like Redis or a messaging-based architecture with RabbitMQ.
  +For example, instead of using the local file system, you can use a <%= vars.platform_name %> service
  +such as the MongoDB document database or a relational database like MySQL or PostgreSQL.
  +Another option is to use cloud storage providers such as [Amazon S3](http://aws.amazon.com/s3/),
  +[Google Cloud Storage](https://cloud.google.com/products/cloud-storage),
  +[Dropbox](https://www.dropbox.com/developers), or [Box](http://developers.box.com/).
  +If your app needs to communicate across different instances of itself,
  +consider a cache like Redis or a messaging-based architecture with RabbitMQ.
   
  -If you must use a file system for your app because for example, your app interacts with other apps through a network attached file system, or because your app is based on legacy code that you cannot rewrite, consider using volume services to bind a network attached file system to your app. For more information, see [Using an External File System (Volume Services)](../services/using-vol-services.html)
  +If you must use a file system for your app because, for example, your app interacts
  +with other apps through a network attached file system or because your app is based on legacy code
  +that you cannot rewrite, consider using volume services to bind a network attached file system to your app.
  +For more information, see [Using an External File System (Volume Services)](../services/using-vol-services.html).
   
   ### <a id="shared-cookies"></a> Cookies Accessible Across Apps
   
  
positive.code: 
  ### <a id="ports"></a> Port Considerations
  
  Clients connect to apps running on <%= vars.product_name %> by making requests to URLs associated with the app. <%= vars.product_name %> allows HTTP requests to apps on ports 80 and 443. For more information, see [Routes and Domains](routes-domains.html).
  
  <%= vars.product_name %> also supports WebSocket handshake requests over HTTP containing the `Upgrade` header. The <%= vars.product_name %> router handles the upgrade and initiates a TCP connection to the app to form a WebSocket connection.
  
  <%= vars.port_limitations %>
  
  ### <a id="moving-apps"></a> <%= vars.product_name %> Updates and Your App
  
  For app management purposes, <%= vars.product_name %> may need to stop and restart your app instances. If this occurs, <%= vars.product_name %> performs the following steps:
  
  1. <%= vars.product_name %> sends a single `termination signal` to the root process that your start command invokes.
  
  1. <%= vars.product_name %> waits 10 seconds to allow your app to cleanly shut down any child processes and handle any open connections.
  
  1. After 10 seconds, <%= vars.product_name %> forcibly shuts down your app.
  
  Your app should accept and handle the termination signal to ensure that it shuts down gracefully. To achieve this, the app is expected to follow the steps below when shutting down:
  
  
negative.code: 
  Singleton apps may become temporarily unavailable for reasons that include:
  
  * During an upgrade, <%= vars.platform_name %> gracefully shuts down the apps running on each Diego Cell
  and restarts them on another Diego Cell.
  Single app instances may become temporarily unavailable if the replacement instance does not become healthy
  within the Diego Cell's evacuation timeout, which defaults to 10 minutes.
  
  * Unexpected faults in <%= vars.platform_name %> system components or underlying infrastructure,
  such as container-host VMs or IaaS availability zones, might cause lone app instances to disappear
  or become unroutable for a minute or two.
  
  To avoid the risk of an app becoming temporarily unavailable, developers can run more than one instance of the app.
  
  
  ## <a id="buildpacks"></a> Using Buildpacks
  
  A buildpack consists of bundles of detection and configuration scripts that provide framework
  and runtime support for your apps.
  When you deploy an app that needs a buildpack, <%= vars.platform_name %> installs the buildpack
  on the Diego Cell where the app runs.
  
  For more information, see [Buildpacks](../../buildpacks/).
  