Skip to content

Deploy Functions

⬅ Parent

Deploy Information

deployApplicationVersion

Extracts version from an application either from .deploy files or

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 - Required. Directory. Application home to get the version from.

Return codes

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

deployPackageName

Outputs the build target name which is based on the

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

  • none

Return codes

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

Environment

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

deployHasVersion

Does a deploy version exist? versionName is the version identifier

Usage

deployHasVersion deployHome versionName [ targetPackage ]

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

Arguments

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

Return codes

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

deployPreviousVersion

Get the previous version of the supplied version

Usage

deployPreviousVersion deployHome versionName

Get the previous version of the supplied version Return Code: 1 - No version exists Return Code: 2 - Argument error

Arguments

  • none

Return codes

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

deployNextVersion

Get the next version of the supplied version

Usage

deployNextVersion deployHome versionName

Get the next version of the supplied version

Arguments

  • none

Return codes

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

Deploy

deployApplication

Deploy an application from a deployment repository

Usage

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

Deploy an application from a deployment repository This acts on the local file system only but used in tandem with deployment.sh functions.

Use-Hook: maintenance Use-Hook: deploy-shutdown Use-Hook: deploy-activate deploy-start deploy-finish

Arguments

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

deployMove

Safe application deployment by moving

Usage

deployMove applicationPath

Safe application deployment by moving

Deploy current application to target path

Arguments

  • none

Return codes

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

Automatically convert application deployments using non-links to links.

Usage

deployMigrateDirectoryToLink deployHome applicationPath

Automatically convert application deployments using non-links to links.

Arguments

  • none

Return codes

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

Link deployment to new version of the application

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.

Return Code: 0 - Success Return Code: 1 - Environment error Return Code: 2 - Argument error

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

deployRemoteFinish

This is run on the remote system after deployment; environment

Usage

deployRemoteFinish [ --revert | --cleanup ] [ --debug ] deployPath applicationId applicationPath

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

Return codes

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

Deployment Hooks

Deployment occurs as follows:

  • make-env - 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

Arguments

  • none

Return codes

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

Usage

__hookApplicationID

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

  • none

Examples

885acc3

Return codes

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

Arguments

  • none

Return codes

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

hookRun maintenance

Toggle maintenance on or off. The default version of this

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 - Required. String. Maintenance setting: on | 1 | true | enable | off | 0 | false | disable
  • --message maintenanceMessage - Optional. String. 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 - Success
  • 1 - Environment error
  • 2 - Argument error

Usage

hookRun deploy-activate applicationPath

This is called where the current working directory at the time of running is the new application and the applicationPath which is passed as an argument is the place where the new application should be moved to in order to activate it.

Return Code: 0 - This is called to replace the running application in-place

Arguments

  • applicationPath - This is the target for the current application

Return codes

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

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 - Success
  • 1 - Environment error
  • 2 - Argument error

Arguments

  • none

Return codes

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

Arguments

  • none

Examples

  • Move directories to make deployment final

Return codes

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

Arguments

  • none

Return codes

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