Skip to content

Deploy Functions

Deployment is the upgrading of an application from one version to another. These functions handle this on a file-level with various hooks and ways of backing out of a failed upgrade.

Versions of the application are kept in a local deployment repository which contains information about each deployment, and switching between deployments is intended to be easy and straightforward to accomplish.

Applications are served via a link aliased to a directory which then changes based on the current deployment; this minimizes moving parts to change deployment code bases.

⬅ Parent

Deploy Information

Usage

deployApplicationVersion applicationHome

Extracts version from an application either from .deploy files or from the the .env if that does not exist. Checks APPLICATION_ID and APPLICATION_TAG and uses first non-blank value.

Arguments

  • applicationHome - Directory. Required. Application home to get the version from.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Usage

deployPackageName deployHome

Outputs the build target name which is based on the environment BUILD_TARGET. If this is called on a non-deployment system, use the application root instead of deployHome for compatibility.

Arguments

  • deployHome - Directory. Required. Deployment database home.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Environment

  • BUILD_TARGET - String. The file to generate when generating builds

Usage

deployHasVersion deployHome versionName

Does a deploy version exist? versionName is the version identifier for deployments

Arguments

  • deployHome - Directory. Required. Deployment database home.
  • versionName - String. Required. Application ID to look for

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Usage

deployPreviousVersion deployHome versionName

Get the previous version of the supplied version

Arguments

  • deployHome - Directory. Required. Deployment database home.
  • versionName - String. Required. Application ID to look for

Return codes

  • 1 - No version exists
  • 2 - Argument error

Usage

deployNextVersion deployHome versionName

Get the next version of the supplied version

Arguments

  • deployHome - Directory. Required. Deployment database home.
  • versionName - String. Required. Application ID to look for

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Deploy

Usage

deployApplication [ --help ] [ --first ] [ --revert ] --home deployHome --id applicationId --application applicationPath [ --target targetPackage ] [ --message message ]

This acts on the local file system only but used in tandem with deployment functions.

Arguments

  • --help - Flag. Optional. This help.
  • --first - Flag. Optional. The first deployment has no prior version and can not be reverted.
  • --revert - Flag. Optional. Means this is part of the undo process of a deployment.
  • --home deployHome - Directory. Required. Path where the deployments database is on system.
  • --id applicationId - String. Required. Should match APPLICATION_ID or APPLICATION_TAG in .env or .deploy/
  • --application applicationPath - FileDirectory. Required. Path on the system where the application is live
  • --target targetPackage - Filename. Optional. Package name, defaults to BUILD_TARGET
  • --message message - String. Optional. Message to display in the maintenance message on systems while upgrade is occurring.

Examples

deployApplication --home /var/www/DEPLOY --id 10c2fab1 --application /var/www/apps/cool-app

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Environment

  • BUILD_TARGET - String. The file to generate when generating builds APPLICATION_ID - String. This is the unique hash which represents the source code state (typically a git hash) APPLICATION_TAG - String. This is the full version number including debugging or release identifiers

Utilities

Usage

deployMove applicationPath

Safe application deployment by moving Deploy current application to target path

Arguments

  • applicationPath - Directory. Required. Application target path.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Usage

deployMigrateDirectoryToLink deployHome applicationPath

Automatically convert application deployments using non-links to links.

Arguments

  • deployHome - Directory. Required. Deployment database home.
  • applicationPath - Directory. Required. Application target path.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Usage

deployLink applicationLinkPath [ applicationPath ]

Link new version of application. When called, current directory is the new application and the applicationLinkPath which is passed as an argument is the place where the new application should be linked to in order to activate it.

Arguments

  • applicationLinkPath - Path. Required. Path where the link is created.
  • applicationPath - Path. Optional. Path where the link will point to. If not supplied uses current working directory.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Environment

  • PWD

Usage

deployRemoteFinish [ --debug ] [ --deploy ] [ --revert ] [ --cleanup ] --home deployPath --id applicationId --application applicationPath [ --target targetPackage ]

This is run on the remote system after deployment; environment files are correct. It is run inside the deployment home directory in the new application folder. Current working directory on deploy is deployHome/applicationId/app. Current working directory on cleanup is applicationHome/ Current working directory on undo is applicationHome/ Note that these MAY be the same or different directories depending on how the application is linked to the deployment

Arguments

  • --debug - Enable debugging. Defaults to BUILD_DEBUG
  • --deploy - Flag. Optional. default setting - handles the remote deploy.
  • --revert - Flag. Optional. Revert changes just made.
  • --cleanup - Flag. Optional. Cleanup after success.
  • --home deployPath - Directory. Required. Path where the deployments database is on remote system.
  • --id applicationId - String. Required. Should match APPLICATION_ID in .env
  • --application applicationPath - String. Required. Path on the remote system where the application is live
  • --target targetPackage - Filename. Optional. Package name, defaults to app.tar.gz

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Deployment Hooks

Deployment occurs as follows:

  • application-environment - Optional. Run on deployment system. Create environment file for remote system.
  • deploy-start - Optional. Run on each remote system.
  • deploy-activate - Optional. Run on each remote system.
  • deploy-finish - Optional. Run on each remote system.
  • deploy-confirm - Optional. Run on deployment system.
  • deploy-revert - Optional. Run on each remote system.

Ordering of Hooks

Hooks are run, in this order:

Deployment deployApplication

Most deploy-foo hooks should handle failure and return application state to a stable state.

  1. maintenance on - On each deployed system
    • Fail: Nothing
  2. deploy-shutdown - On each deployed system
    • Fail: maintenance off
  3. deploy-start - On each deployed system
    • Fail: maintenance off
  4. deploy-activate - On each deployed system
    • Fail: maintenance off
  5. deploy-finish - On each deployed system
    • Fail: maintenance off
  6. maintenance off - On each deployed system
    • Fail: Nothing

Deployment deployRemoteFinish

Most deploy-foo hooks should handle failure and return application state to a stable state.

  1. deploy-cleanup - On each deployed system
    • Fail: Nothing

Hook documentation

hookRun application-environment

application-environment hook default implementation

Usage

hookRun application-environment

Hook to customize the application environment file

Arguments

  • none

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

hookRun application-id

application-id hook default implementation

Usage

hookRun application-id [ --help ]

Generate a unique ID for the state of the application files The default hook uses the short git sha: git rev-parse --short HEAD

Arguments

  • --help - Flag. Optional. Display this help.

Examples

885acc3

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

hookRun application-tag

application-tag hook default implementation

Usage

hookRun application-tag

Get the "tag" (or current display version) for an application The default hook uses most recent tag associated in git or v0.0.1 if no tags exist.

Arguments

  • none

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Usage

hookRun maintenance maintenanceSetting [ --message maintenanceMessage ]

Toggle maintenance on or off. The default version of this modifies the environment files for the application by modifying the .env.local file and dynamically adding or removing any line which matches the MAINTENANCE variable. Note that applications SHOULD load this configuration file dynamically (and monitor it for changes) to enable maintenance at any time.

Arguments

  • maintenanceSetting - String. Required. Maintenance setting: on | 1 | true | enable | off | 0 | false | disable
  • --message maintenanceMessage - String. Optional. Message to display to the use as to why maintenance is enabled.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Environment

  • BUILD_MAINTENANCE_VARIABLE - EnvironmentVariable. The variable
  • If you want to use a different environment variable than MAINTENANCE, set this environment variable to the variable you want to use.

Arguments

  • none

Examples

  • Move directories to make deployment final

Return codes

  • 0 - This SHOULD exit successfully always

Arguments

  • applicationPath - Directory. Required. This is the target for the current application

Return codes

  • 0 - This is called to replace the running application in-place

Arguments

  • none

Examples

  • Enable a health endpoint which returns version number and ensure all servers return the same version number (which was just updated)
  • Check the home page for a version number
  • Check for a known artifact (build sha) in the server somehow
  • etc.

Return codes

  • 0 - Continue with deployment
  • Non-zero - Any non-zero exit code will run deploy-revert hook on all systems and cancel deployment

Arguments

  • none

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Arguments

  • none

Examples

  • Move directories to make deployment final

Return codes

  • 0 - This SHOULD exit successfully always

Arguments

  • none

Return codes

  • 0 - This SHOULD exit successfully always