This is your guide to building production-ready apps on cloud.gov. Read this early and often, especially when you’re starting to consider a future project. It explains things you can do for reliable and responsive applications deployed on cloud.gov.
Core best practices
To build consistent, healthy, production-ready applications on cloud.gov, incorporate the following practices into your development workflow from the beginning.
Configuration as code
To ensure consistency and reproducibility, capture your application configuration in version control.
- Write an application manifest that defines your application configuration, such as the application name and the previously-created services to use.
More than one instance
It is critical that your production application has more than one instance. Then if there are any issues with one of the platform runners where your app instances are assigned, or we upgrade platform components underneath an instance, your app will continue to function correctly (with less risk of downtime).
- See multiple instances.
Protect access to sensitive credentials
Environment variables defined with
cf set-env are ephemeral to the specific deployment of each application. Use user-provided services to store sensitive information such as credentials or API keys, and use your
manifest.yml for non-sensitive variables.
- Create user-provided services with
cf cupsand bind them with
cf bs. Once you have updated your application to read your stored credentials from the service, update your
manifest.ymlto make it part of your configuration. For non-sensitive information, use an env: block in your
- Protect access to platform provided variables such as
VCAP_SERVICESfor managed services and
DATABASE_URLfor the database service.
- Minimize your number of users with the
SpaceDeveloperrole, as they can access all environment variables using
- Educate users who require the
SpaceDeveloperrole to protect access to environment variables.
- Minimize your number of users with the
Prefer dedicated over shared services
Shared services do not have the same constraints as a dedicated service and can be affected by other customers that are performing CPU or memory intensive tasks against that service.
cf marketplaceto consider your options and sizes for each service, and choose appropriately for the resources your application will need.
Space per environment
When running an application for development or testing, it is best to have a separate space from your production instance in which to run the application. Ideally, each space will look identical to each other, with the exception of routes or number of instances.
- As an Org Manager for your organization, use the
cf create-spacecommand to create new spaces for each environment.
Prevent non-auditable changes to production apps
All changes made to running production applications should be logged for auditing, which means that those changes should be made using commands in the cloud.gov dashboard, command line interface, or CF API (or automated commands in deployment scripts). By default, cloud.gov also allows SSH access, which allows making changes that are harder to audit. This means you should disable SSH access to production applications.
You may need to document your restrictions for remote access to your applications for control AC-17 in your System Security Plan, and this is a restriction that you can document.
cf disallow-space-ssh PRODUCTION-SPACE-NAMEfor your production space or
cf disable-ssh PRODUCTION-APP-NAMEto disable SSH access for individual running application instances. Use event auditing to audit deployments and further access.
You want to receive alerts about application errors, downtime, and throughput issues.
- There are many external services that provide alerting. For example, New Relic provides application availability monitoring with “Synthetics”.
The following practices are very helpful to incorporate into most cloud.gov apps. Evaluate which ones you need for your team and users.
Your application should be able to be deployed without any downtime. Be aware there are known issues if your application automatically does database migrations when deploying.
- Use the native Rolling App Deployments. This is preferable to the unmaintained autopilot Cloud Foundry CLI plugin.
To reduce the risk associated with manual deployments, consider automating the process to make it repeatable.
The best way to prevent performance issues is to enable caching on your application.
- You can use S3 file storage for caches.
It’s best not to serve static files from cloud.gov directly.
- You can store your files in S3 or point CloudFront to an assets folder so you serve your assets with a CDN.
Custom domain name
When launching your application to production, you should deploy it to production using a custom domain name (a
.mil TLD). When you are ready to launch to production, DNS delegation for the domain is the easiest path to getting the domain up and running.
- See custom domains.
Your application should respond to shutdown events by closing connections and cleaning up resources.
- Listen to
SIGTERMand complete the shutdown within 10 seconds.
- Refuse any new connections and complete any in-flight requests.
- Flush and close any open connections.