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.

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.

Location: bin/build/tools/deploy.sh

Arguments

  • applicationHome - Directory. Required. 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.

Location: bin/build/tools/deploy.sh

Arguments

  • deployHome - Directory. Required. Deployment database home.

Return codes

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

Environment

deployHasVersion

Does a deploy version exist? versionName is the version identifier

Usage

deployHasVersion deployHome versionName

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

Location: bin/build/tools/deploy.sh

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

deployPreviousVersion

Get the previous version of the supplied version

Usage

deployPreviousVersion deployHome versionName

Get the previous version of the supplied version

Location: bin/build/tools/deploy.sh

Arguments

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

Return codes

  • 1 - No version exists
  • 2 - Argument error

deployNextVersion

Get the next version of the supplied version

Usage

deployNextVersion deployHome versionName

Get the next version of the supplied version

Location: bin/build/tools/deploy.sh

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

deployApplication

Deploy an application from a deployment repository

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.

Location: bin/build/tools/deploy.sh

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

See Also

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

Utilities

deployMove

Safe application deployment by moving

Usage

deployMove applicationPath

Safe application deployment by moving

Deploy current application to target path

Location: bin/build/tools/deploy.sh

Arguments

  • applicationPath - Directory. Required. Application target path.

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.

Location: bin/build/tools/deploy.sh

Arguments

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

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.

Location: bin/build/tools/deploy.sh

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 [ --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

Location: bin/build/tools/deployment.sh

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

Hook documentation

{__hookApplicationEnvironment}

{__hookApplicationID}

{__hookApplicationTag}

{__hookMaintenance}

{__hookDeployStart}

{__hookDeployMove}

{__hookDeployConfirm}

{__hookDeployCleanup}

{__hookDeployFinish}

{__hookDeployRevert}

🛠️ Tools · ⬅ Top