Pipeline Functions

Application Configuration

`dotEnvConfigure`

Load .env and optional .env.local into bash context

Usage

environmentFileLoad .env --optional .env.local where

Loads .env which is the current project configuration file Also loads .env.local if it exists Generally speaking - these are NAME=value files and should be parsable by bash and other languages.

Requires the file .env to exist and is loaded via bash source and all variables are exported in the current shell context.

If .env.local exists, it is also loaded in a similar manner.

Return Code: 1 - if .env does not exist; outputs an error Return Code: 0 - if files are loaded successfully

Arguments

where - Optional. Directory. Where to load the .env files.

Return codes

0 - Success
1 - Environment error
2 - Argument error

Environment

Loads .env and .env.local, use with caution on trusted content only

Build Utilities

`buildFailed`

Output debugging information when the build fails

Usage

buildFailed logFile

Outputs debugging information after build fails:

last 50 lines in build log
Failed message
last 3 lines in build log

Return Code: 1 - Always fails

Arguments

logFile - File. Required. The most recent log from the current script.
message - String. Optional. Any additional message to output.

Examples

quietLog="$(buildQuietLog "$me")"
if ! ./bin/deploy.sh >>"$quietLog"; then
    decorate error "Deploy failed"
    buildFailed "$quietLog"
fi

Sample Output

stdout

Return codes

0 - Success
1 - Environment error
2 - Argument error

`versionSort`

Sort versions in the format v0.0.0

Usage

versionSort [ -r | --reverse ] [ --help ]

Sorts semantic versions prefixed with a v character; intended to be used as a pipe.

vXXX.XXX.XXX

for sort - -k 1.c,1 - the c is the 1-based character index, so 2 means skip the 1st character

Odd you can't globally flip sort order with -r - that only works with non-keyed entries I assume

Arguments

-r |- --reverse - Reverse the sort order (optional) - --help - Optional. Flag. Display this help.

Examples

git tag | grep -e '^v[0-9.]*$' | versionSort

Return codes

0 - Success
1 - Environment error
2 - Argument error

Requires

throwArgument sort usageDocument

`ipLookup`

Get the current IP address of a host

Usage

ipLookup [ --help ]

Get the current IP address of a host

Arguments

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

Return codes

0 - Success
1 - Environment error
2 - Argument error

Environment

IP_URL - URL. URL to look up IP my address remotely
IP_URL_FILTER - String. jq filter to parse IP_URL result (assuming JSON) if blank, no filter is used and raw result is returned

`isUpToDate`

Test whether the key needs to be updated

Usage

isUpToDate [ --name name ] keyDate upToDateDays

For security one should update keys every N days

This value would be better encrypted and tied to the key itself so developers can not just update the value to avoid the security issue.

This tool checks the value and checks if it is upToDateDays of today; if not this fails.

It will also fail if:

upToDateDays is less than zero or greater than 366
keyDate is empty or has an invalid value

Otherwise, the tool may output a message to the console warning of pending days, and returns exit code 0 if the keyDate has not exceeded the number of days.

Arguments

keyDate - Required. Date. Formatted like YYYY-MM-DD. Truncated at 10 characters as well.
--name name - Optional. Name of the expiring item for error messages.
upToDateDays - Required. Integer. Days that key expires after keyDate.

Examples

if !isUpToDate "$AWS_ACCESS_KEY_DATE" 90; then
  bigText Failed, update key and reset date
  exit 99
fi

Return codes

0 - Success
1 - Environment error
2 - Argument error

Application Environment

`environmentFileApplicationMake`

Create environment file .env for build.

Usage

environmentFileApplicationMake [ requiredEnvironment ... ] [ -- optionalEnvironment ...] "

Create environment file .env for build.

Note that this does NOT change or modify the current environment.

Arguments

--help - Optional. Flag. Display this help.
requiredVariable ... - Optional. One or more environment variables which should be non-blank and included in the .env file.
-- - Optional. Divider. Divides the requiredEnvironment values from the optionalEnvironment. Should appear once and only once.
optionalVariable ... - Optional. One or more environment variables which are included if blank or not

Return codes

0 - Success
1 - Environment error
2 - Argument error

Environment

APPLICATION_VERSION - String. This is the version number which can be displayed
reserved and set to hookRun version-current if not set already
APPLICATION_BUILD_DATE - Date. Time when a build was initiated, set upon first invocation if not already
reserved and set to current date; format like SQL.
APPLICATION_TAG - String. This is the full version number including debugging or release identifiers
reserved and set to hookRun application-id
APPLICATION_ID - String. This is the unique hash which represents the source code state (typically a git hash)
reserved and set to hookRun application-tag

`environmentFileShow`

Display and validate application variables.

Usage

environmentFileShow [ environmentName ] [ -- ] [ optionalEnvironmentName ]

Display and validate application variables. Return Code: 1 - If any required application variables are blank, the function fails with an environment error Return Code: 0 - All required application variables are non-blank

Arguments

environmentName - EnvironmentVariable. Optional. A required environment variable name
-- - Separator. Optional. Separates requires from optional environment variables
optionalEnvironmentName - EnvironmentVariable. Optional. An optional environment variable name.

Return codes

0 - Success
1 - Environment error
2 - Argument error

`environmentApplicationLoad`

Loads application environment variables, set them to their default values

Usage

environmentApplicationLoad

Loads application environment variables, set them to their default values if needed, and outputs the list of variables and values.

Arguments

none

Return codes

0 - Success
1 - Environment error
2 - Argument error

Environment

BUILD_TIMESTAMP - Integer. Time when a build was initiated, set upon first invocation if not already
APPLICATION_BUILD_DATE - Date. Time when a build was initiated, set upon first invocation if not already
APPLICATION_VERSION - String. This is the version number which can be displayed
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

Deployment tools

`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

`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

`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

`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

`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