Software Management

Deployment Best Practices

Deployment is an optional stage in software management where the software is hosted as an application and accessible to others in a runtime state. Hosting software as an application is not required, but is a common activity to support customer needs and audiences of USGS information. In contrast, development (Refer to Develop) is a required stage concerned with hosting of uncompiled source code in a code repository so that it can be distributed (Refer to Distribute) for re-use or as a USGS product.

How to deploy an application varies widely within the Bureau, and there is no one way that will suit every situation. However, there are a number of best practices that should be followed whether the software will be deployed to local on-premise infrastructure, shared infrastructure, or a cloud hosting environment. The best practices below represent the fundamental concepts of code deployment, for more advanced information many educational resources are available on the web for industry standard techniques and technologies that assist in the deployment process. Your deployment environment may dictate which of these tools and techniques is most useful to your project.

Deployment in the Cloud

In 2016, the USGS put in place a memorandum for Governance of Cloud Solution to comply with its responsibility to provide assurance to the Department of Interior’s Chief Information Officer regarding management of USGS Information Management and Technology under the Federal Information Technology Acquisition and Reform Act. The USGS Cloud Hosting Solutions makes available an Amazon cloud hosting solution as the primary cloud option for all USGS staff. For more information, contact CHS (cloudservices@usgs.gov). Requests to use other cloud solutions must be approved by the USGS Associate Chief Information Officer in the Office of Enterprise Information.

Best Practices

A principle best practice is to fully understand your deployment workflow to encourage efficient application deployment and updates. The best practices below help achieve reliable and repeatable code deployment.

Deployment Checklist

Write down every step required to deploy code to your various environments to create a checklist. This list will ensure that nothing is forgotten and also serves as an excellent starting point to identify opportunities for improvement in your deployment process. The checklist should reference locations and helper scripts, commands and steps needed to deploy the application, sign-offs for release, and collaborators who need to be notified of updated releases. Along with the deployment checklist should be a rollback checklist of what to do if things do not go as planned. The checklist should provide the steps to return the application to a previous working state.

Automate

When people manually perform repeated tasks, errors are often introduced by mistake. Automation is a best practice to reduce error. Automation can be achieved by simple or sophisticated tooling depending on your requirements. The variety of automation options and best practices can be an intimidating subject, the most important thing to keep in mind is to understand your own process and improve it with automation over time.

Any project could benefit from an automated solution like a script that encapsulates the deployment checklist and may include prompts for deploying an application to a server. Additional automated tools and solutions are available as well. For example, enterprise Development and Operations (DevOps) teams may use a number of enterprise tools including but not limited to: configuration management (e.g., Chef, Ansible), dependency management (e.g., Maven, NPM), task runners (e.g., Jenkins, GitLab Runners), and automated infrastructure provisioning (e.g., CloudFormation, Terraform).

Continuous Integration (CI)

While not a deployment requirement, using continuous integration will result in higher quality and more reliable code through risk mitigation, code confidence, team communication, and consistency of process. Code is automatically pulled from the repository and built on a server of a known and consistent configuration. Code artifacts like jars, exe’s, libs, etc., become independent objects. They are stored in an object store like GitLab, Artifactory, or AWS S3 storage. When code is deployed to a runtime environment, it is always pulled from the object store. This ensures consistent versions of applications and libraries are deployed to each system appropriately.

Separate Configuration Details

If you are connecting to resources such as databases, you should store the configuration information, such as the specific database connection information, separate from the application. The application should bind with configuration information at runtime. The goal is to build the application code without having to include configuration information in the code itself. You will probably need to work with infrastructure or operations staff as there are many ways to accomplish this best practice.

Testing Deployment

The best practices above help avoid application deployment from becoming a stressful, high-stakes activity. To ensure deployment is a routine and uneventful activity, practice your deployments. Use the same checklist and techniques to deploy your application to a development or test environment as you will use to deploy to production. If at all possible, insist that your non-production environments are as identical to production as possible. By using CI and automated deployment, code may be deployed multiple times a day. This allows you to iron out the rough spots and build confidence and reliability into your deployments in small, low-risk increments. By the time you are ready to push a new feature to production, the deployment process should be routine and uneventful, but remember to review your rollback steps in case something goes wrong.