Skip to content

Environment Variables

Note that you should place environment variables (if you override the default, for example), in:

./bin/env/VARIABLE_NAME.sh

Where VARIABLE_NAME is the name of your environment variable. environmentAddFile does this for you if you want.

These are the known environment variables in Zesk Build - to see the default behavior look at in ./bin/build/env.

You can document your environment variables automatically using Type: and a description using comments and the standard Zesk Build bash comment syntax of # Name: value

So an example environment file is:

#!/usr/bin/env bash
# Type: String
# Category: Documentation
# ID of CloudFront provider for web site, for invalidation
export DOCUMENTATION_CLOUDFRONT_ID
DOCUMENTATION_CLOUDFRONT_ID="${DOCUMENTATION_CLOUDFRONT_ID-}"

The values for Type: match standard types. The Category: simply places it that documentation category. The behavior here is to set the environment variable to blank unless it is set already. Most project environment variables will follow this pattern unless they are derived from other environment variables and the idea is that this value should come from, you know, the environment.

The exception to this is derived values (based on another environment variable, for example but can be specified) or values which can be computed easily.

It's important to avoid logic in the environment loader file unless you are strict about access to the environment variable solely through the buildEnvironmentLoad and buildEnvironmentGet calls as it is NOT a requirement to accessing environment variables, rather a convenience.

As well, note that variables documented in this manner can generate their own documentation, and the type can be used to validate environment variables.

Note that most environment variables will simply inherit the already-set value (as shown in the example above), except in cases where it more of a project configuration such as APPLICATION_NAME or APPLICATION_JSON, for example.

Project configuration variables:

  • APPLICATION_NAME, APPLICATION_JSON, APPLICATION_JSON_PREFIX, BUILD_HOOK_EXTENSIONS, APPLICATION_CODE_EXTENSIONS, APPLICATION_CODE

See also

Categories of Environment Variables

Amazon Web Services

  • AWS_ACCESS_KEY_DATE Date. Date of key expiration which can be checked in pipelines. Not part of the Amazon specification but a good idea to track expiration of keys.
  • AWS_ACCESS_KEY_ID String. Amazon Web Services IAM Identity
  • AWS_PROFILE String. Default profile for Amazon Web Services
  • AWS_REGION String. Region for Amazon Web Services
  • AWS_SECRET_ACCESS_KEY Secret. Private Secret Password for AWS

Application

  • APPLICATION_CODE String. This is the unique code name of the application. Use a domain name suffix to ensure global uniqueness.
  • APPLICATION_CODE_EXTENSIONS ColonDelimitedList. List of extensions for code in the application. Required.
  • APPLICATION_CODE_IGNORE ColonDelimitedList. List of extensions for code in the application. Required.
  • APPLICATION_JSON ApplicationFile. Path to the application configuration JSON
  • APPLICATION_JSON_PREFIX String. Prefix to place we can store things in the JSON file (e.g. to set the fingerprint)
  • APPLICATION_NAME String. This is the display name of the application
  • BUILD_COMPANY String. Legal copyright holder for this codebase
  • BUILD_COMPANY_LINK URL. Legal copyright holder website for this codebase
  • BUILD_HOOK_EXTENSIONS ColonDelimitedList. List of extensions to run when looking for hooks
  • BUILD_MAINTENANCE_CREATED_FILE Boolean. When true, means the .env.local file was created by the maintenance hook and should be deleted when maintenance is no longer enabled.
  • BUILD_MAINTENANCE_MESSAGE_VARIABLE EnvironmentVariable. Name of the environment variable (if any) which reflects the current maintenance message. notes
  • BUILD_MAINTENANCE_VARIABLE EnvironmentVariable. The variable notes
  • BUILD_PROJECT_DEACTIVATE Function. Set this to a function which cleans up the project context and will be run on project-deactivate hook which is sourced.

Bash

  • DISPLAY String.
  • EDITOR Callable. Binary for editing files
  • HOME Directory. Centralizing access to environment variables in code has the added benefit we can add debugging here if needed
  • LC_TERMINAL String. LC_TERMINAL typically identifies the terminal application
  • MANPATH DirectoryList. A colon : separated list of paths to search for manual pages. See manPathConfigure
  • PATH DirectoryList. A colon : separated list of paths to search for executables in bash. See pathConfigure
  • PRODUCTION Boolean. Is this a production system? e.g. remove unnecessary runtime checks.
  • PROMPT_COMMAND Callable. Command is run prior to displaying the prompt, receives exit status from prior command
  • PS1 String. Bash Prompt for terminals
  • TERM String.
  • VISUAL Executable. Binary for viewing files

Bash Prompt

  • __BASH_PROMPT_MARKERS Array. List of markers to identify to the terminal location of the prompt
  • __BASH_PROMPT_MODULES Array. List of modules to run each prompt command
  • __BASH_PROMPT_PREVIOUS Array. Previous result code

Build Configuration

  • BUILD_CACHE_HOME Directory. Location for the build system cache files. Defaults to $HOME/.build and if $HOME is not a directory then $(buildHome)/.build Cache MAY be deleted at any time. If you need your files to be preserved, store them elsewhere.
  • BUILD_DEBUG CommaDelimitedList. Constant for turning debugging on during build to find errors in the build scripts. Enable debugging globally in the build scripts. Set to a comma (,) delimited list string to enable specific debugging, or true for ALL debugging, false (or blank) for NO debugging.
  • BUILD_DEBUG_LINES PositiveInteger. Number of lines of debugging output to send to stderr before stopping
  • BUILD_ENVIRONMENT_DIRS DirectoryList. Search directory for environment definition files. : separated. notes
  • BUILD_HOME Directory. BUILD_HOME is . when this code is installed - at ./bin/build. Usually an absolute path and does NOT end with a trailing slash. This is computed from the current source file using ${BASH_SOURCE[0]}.
  • BUILD_HOOK_DIRS ApplicationDirectoryList. List of directories to search for hooks. Defaults to bin/hooks:bin/build/hooks. Colon (:) separated list.
  • BUILD_INSTALL_URL URL. BUILD_INSTALL_URL for installInstallBuild - source URL for a raw installer.
  • BUILD_INTERACTIVE_REFRESH PositiveInteger. When displaying content interactively, how many seconds should elapse before refreshing content?
  • BUILD_MAXIMUM_TAGS_PER_VERSION PositiveInteger. Number of versions tags (d0, d1, d2, etc.) to look for before giving up in gitTagVersion
  • BUILD_NOTIFY_SOUND String. Sound for notifications. Set to - for no sound. Defaults to zesk-build-notification.
  • BUILD_PRECOMMIT_EXTENSIONS List. List of extensions for which build hooks may be written and run notes
  • BUILD_RELEASE_NOTES ApplicationDirectory. Constant for the release notes path. Defaults to ./docs/release.
  • BUILD_VERSION_NO_OPEN Boolean. Constant for whether to open release notes when a version is requested (see version-already)
  • BUILD_VERSION_SUFFIX String. Default suffix used in gitTagVersion
  • 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
  • XDG_CACHE_HOME Directory. Base directory for user-specific cache data to be stored
  • XDG_CONFIG_DIRS DirectoryList. Search directory for user-specific configuration files to be stored. : separated.
  • XDG_CONFIG_HOME Directory. Location for configuration files
  • XDG_DATA_DIRS DirectoryList. Search directory for user-specific data files to be stored. : separated.
  • XDG_DATA_HOME Directory. Base directory for user-specific data to be stored
  • XDG_STATE_HOME Directory. Base directory for user-specific state files to be stored

Continuous Integration

  • BITBUCKET_CLONE_DIR Directory. Defined in BITBUCKET Pipelines Typically should match BUILD_HOME
  • BITBUCKET_REPO_SLUG String. Defined in BITBUCKET Pipelines, represents the project code name.
  • BITBUCKET_WORKSPACE String. Defined in BITBUCKET Pipelines. represents the project workspace.
  • BUILD_DOCKER_BITBUCKET_IMAGE String.
  • BUILD_DOCKER_BITBUCKET_PATH RemoteDirectory.
  • CI String. If this value is non-blank, then console statusMessages are just output normally. notes

Decoration

  • BUILD_COLORS Boolean. If true then colors are shown, blank means guess the value, false means no colors
  • BUILD_COLORS_MODE String. light or dark
  • BUILD_PAIR_WIDTH PositiveInteger. Width for pairs. Defaults to 40.
  • BUILD_PROMPT_COLORS ColonDelimitedList. Colon-separated list of colors for the prompt notes
  • BUILD_TEXT_BINARY Callable. Binary used to generate bigText
  • BUILD_URL_BINARY Callable. Binary used in __urlOpen
  • COLORFGBG String. Standard way to express the foreground and background colors notes

Deployment

  • APPLICATION_BUILD_DATE Date. Time when a build was initiated, set upon first invocation if not already
  • APPLICATION_ID String. This is the unique hash which represents the source code state (typically a git hash)
  • APPLICATION_REMOTE_HOME RemoteDirectory. Path on the remote server where the application is served
  • APPLICATION_TAG String. This is the full version number including debugging or release identifiers
  • APPLICATION_VERSION String. This is the version number which can be displayed
  • BUILD_TARGET String. The file to generate when generating builds
  • BUILD_TIMESTAMP Integer. Time when a build was initiated, set upon first invocation if not already
  • DEPLOYMENT String. Target deployment for this code
  • DEPLOY_REMOTE_HOME RemoteDirectory. Path on the remote server where the application deployment home is (per application)
  • DEPLOY_USER_HOSTS String. A list of one ore more user@host for installation of the application
  • GITHUB_REPOSITORY_OWNER String. Repository owner for release

Development

  • BUILD_DEVELOPMENT_HOME String. Directory where Zesk Build is being developed in the file system (for other projects to test against a changed version)
  • GITHUB_ACCESS_TOKEN String. Access token used for release
  • GITHUB_ACCESS_TOKEN_EXPIRE Date. GitHub Access token expiration date. Invalid AFTER this date.
  • GITHUB_REPOSITORY_NAME String. Repository name for release
  • GIT_BRANCH_FORMAT String.
  • GIT_OPEN_LINKS Boolean. Open links from git remotes in gitCommit
  • GIT_REMOTE String.

Docker

  • BUILD_DOCKER_IMAGE String. Default docker image to use when launching dockerLocalContainer
  • BUILD_DOCKER_PATH RemoteDirectory. Default path for the shell to map the current directory to when launching dockerLocalContainer
  • BUILD_DOCKER_PLATFORM String. notes

Documentation

  • BUILD_DOCUMENTATION_SOURCE_LINK_PATTERN String. Links in documentation

Installation

  • BUILD_COMPOSER_VERSION String. Version of composer to use for building vendor directory
  • BUILD_NPM_VERSION String. Version of npm to install using native npm binary.
  • BUILD_PACKAGE_MANAGER Executable. The default package manager on systems which have more than one package manager available.

Internal

  • __BUILD_HAS_TTY Boolean. Cached value of the availability of /dev/tty notes

PHP

  • XDEBUG_ENABLED Boolean. Is xdebug enabled? Calling application can honor this environment variable to automatically connect to the debugger.

Testing

  • BUILD_TEST_FLAGS String. Test flags affect controls and how tests are run.
  • TEST_TRACK_ASSERTIONS Boolean. Turn on or off tracking of function assertions within the testing core If blank, the default behavior is to track; disable it with setting the value to false

Vendor

  • APACHE_HOME Directory. Constant for the Apache configuration home directory
  • BUILD_YARN_VERSION String. Version of yarn to install using corepack
  • DAEMONTOOLS_HOME Directory. Constant for the directory where services are monitored by daemontools
  • MARIADB_BINARY_CONNECT Executable. MariaDB binary for database connections
  • MARIADB_BINARY_DUMP Executable. MariaDB binary for dump
  • NODE_PACKAGE_MANAGER Executable. The package manager used for node operations. Usually yarn or npm. Default is yarn.

Additional Details on Environment Variables

BUILD_DOCKER_PLATFORM

Type: String • Category: Docker

The platform for dockerLocalContainer

Contacts of this can be found via docker buildx ls

Valid values are:

  • linux/arm64
  • linux/amd64
  • linux/amd64/v2
  • linux/riscv64
  • linux/ppc64le
  • linux/s390x
  • linux/386
  • linux/mips64le
  • linux/mips64
  • linux/arm/v7
  • linux/arm/v6

If not specified, uses the default for the current platform.

BUILD_ENVIRONMENT_DIRS

Type: DirectoryList • Category: Build Configuration

Search directory for environment definition files. : separated. Note these should be in addition to the default environment variables ALWAYS located at $(buildHome)/bin/build/env THe default is $(buildHome)/bin/env. Make sure to append to this as a :-list.

BUILD_MAINTENANCE_MESSAGE_VARIABLE

Type: EnvironmentVariable • Category: Application

Name of the environment variable (if any) which reflects the current maintenance message. Default is MAINTENANCE_MESSAGE and this is typically added to the .env.local to a live application. Your application should monitor these files for changes if they are cached and reload as needed to ensure these messages are displayed immediately.

BUILD_MAINTENANCE_VARIABLE

Type: EnvironmentVariable • Category: Application

The variable The maintenance variable which enables (or disabled) maintenance mode. This value is set to true or false

BUILD_PRECOMMIT_EXTENSIONS

Type: List • Category: Build Configuration

List of extensions for which build hooks may be written and run Presence in this list simply means it may run, not that it is written or runs; add your own bin/hooks/pre-commit-XXX.sh to handle a specific file type in your application.

Currently: - sh - Bash - PHP - PHP - js - JavaScript - json - JSON - md - Markdown - yml - Yet Another Markup Language - txt - Text files - py - Python - go - Golang - rs - Rust - css - CSS - less, sass, scss - Compiled stylesheets

BUILD_PROMPT_COLORS

Type: ColonDelimitedList • Category: Decoration

Colon-separated list of colors for the prompt

Colors are escape codes. Last entry is a reset simply to make environment output less messy.

  1. Success color
  2. Failure color
  3. User
  4. Host
  5. Path

CI

Type: String • Category: Continuous Integration

If this value is non-blank, then console statusMessages are just output normally. Continuous Integration - this is set to a non-blank value in:

  • Bitbucket pipelines

COLORFGBG

Type: String • Category: Decoration

Standard way to express the foreground and background colors

  • Format is: foregroundColor ; backgroundColor
  • foregroundColor - UnsignedInteger. 0 to 16
  • backgroundColor - UnsignedInteger. 0 to 16

Not referenced in this product; referenced via rxvt and may be honored at some point.

__BUILD_HAS_TTY

Type: Boolean • Category: Internal

Cached value of the availability of /dev/tty Possible values are true or false or blank. - true - /dev/tty appears to be operating without errors - false - /dev/tty appears to be disconnected and can not be used This value is set automatically by isTTYAvailable and caches the value using this environment variable to avoid testing again.