Deploys

The HM Platform has a powerful deployment process built for our requirements.

Deploys are triggered from Vantage by clicking the Deploy button (natch). This starts the deployment processes on the master server for the region (i.e. eu-west-1.aws.hmn.md), which are then pushed out to the stack’s app servers once the deploy is ready.

Deployment is composed of a few steps. The first step is for the master server to pull down the repository from the specified branch for the project, typically master. This branch is configured when the stack is created, and is typically not changed after creation, so master should always be deployable. The master then runs build scripts if any exist, packages the site, and uses AWS CodeDeploy to push changes out to the app servers.

Running a Deploy

Deployment is handled via Vantage, our servers dashboard. To access Vantage, you need to be proxied, otherwise Vantage won’t load any sites in.

Once proxied, select the stack you’re deploying to; this is the project/client name, followed by the environment, such as nomadbase-production or humanmade-staging. You should then see the deployment details view:

The deployment details view shows a reverse-chronological list of the latest deploys and the associated commits, in addition to the deployment source (git remote URL and branch).

To deploy the code from the source, simply hit the “Deploy Now!” button. It will then kick off the deploy process. Keep your browser open to monitor this status. If the process succeeds, the new deploy will be added to the list; if it fails, Vantage will alert you to the error.

Builds

After pulling the code down, the master server runs a build on the repository using the .build-script file in the repository. This is a shell script that can contain anything you want.

The master servers already include Node (inc. npm) and PHP. These versions may vary by region; this may be switched to containerised builds in the future.

For a typical site with a Grunt-based theme build, a script like the following would work:

#!/bin/bash

# Fail on any errors.
set -e

npm install -g grunt
cd content/themes/projecttheme/
npm install
grunt

When hitting the deploy button, the build will be run synchronously, and if the build script fails, the deploy will fail. It is therefore important that the build script must fail if the project does not build. Shell scripts do not typically fail if a command in them fails, however this can be fixed by using set -e, which will cause the script to fail immediately upon error. Specific lines can be ignored by running them as your_cmd || true.

Platform Constants

As part of the build process, Vantage creates a wp-config-production.php in the project’s directory. This file includes a number of constants that should be used in your project, including S3 configuration, database constants, and other stack configuration.

There are a few constants which are available for convenience, and can be used within your project’s code.

HM_DEPLOYMENT_REVISION

The HM_DEPLOYMENT_REVISION constant contains the git hash of the currently deployed revision. As the .git directory is not included with deploys, this is the easiest way to get the current version of the site.

This can be used to display the deploy version on the site, to take actions when the site is deployed, or to automatically bust asset caches (such as in wp_enqueue_script versions) on deploy.

HM_ENV and HM_ENV_REGION

HM_ENV contains the name of the stack, such as clientname-production. This can be used to automatically configure production, staging, and development keys based on the stack you’re hosted on.

Likewise, HM_ENV_REGION contains the name of the region the stack is running in, such as us-east-1. For sites or plugins used in multiple regions, this can be used to vary behaviour based on where the code is running.

HM_STACK_API_URL, HM_STACK_API_USER and HM_STACK_API_PASSWORD

The HM_STACK_* constants can be used to access the master (deployment) server for the region. HM_STACK_API_URL is the full URL to a REST endpoint for the current application.

This endpoint includes information about the git repository, the server AMI version, EC2 instance type, and domains active for the site. It also links to endpoints for information about the servers included in the stack, PHP logs, and historical deployments for the stack.