Hide Sidebar

Appsody Environment Variables

Stack creators configure Appsody environment variables to specify the behavior they expect from the stack throughout the application development lifecycle. The stack creators define these variables for the stack image in the Dockerfile-stack. The Appsody CLI and Appsody controller inspect these environment variables and then drive the expected behavior for the developer.

If a stack image is built upon another stack's image, it inherits all the Appsody variables from the base stack. You can override the variables that you want to change. This capability allows you to create stacks with slightly different behavior while still getting updates from the base stack.

Note that environment variables must be declared by using the ENV instruction, as described in the Dockerfile reference.

If the environment variable defines a command that is long or complex, you can encapsulate the command into a script.

Environment variables can be Mandatory, Recommended, or Optional. If you do not set Mandatory or Recommended variables, the Appsody CLI generates an error or warning message respectively when you validate your stack.

The following Appsody environment variables are supported:

Common Environment Variables

The environment variables that are used to set up the development workspace for the stack, as such they apply across all of the commands used for Appsody local development (run, test and debug).

Environment Variable Description Example
APPSODY_PROJECT_DIR=<directory> Recommended. Defines the local directory to extract the full application (the stack and your Appsody project) into, from the container when running appsody extract, appsody build or appsody deploy.

The default is /project.
APPSODY_PROJECT_DIR=/my-project

Your application is extracted into the /my-project directory on your local machine.
APPSODY_MOUNTS=<list of directories> Mandatory. List of directories (separated by ;) to be mounted in the Appsody container. Each mount is specified with source path:destination path syntax, where the first field is the path to the directory on the host machine (source), and the second field is the path where the directory is mounted in the container (destination). You can specify only directories in volume mounts, not single files. The use of symlinks within these directories might result in undefined behaviour. APPSODY_MOUNTS=/src:/project/user-app/src;/lib:/project/user-app/lib

The local /src and /lib directories are mounted to the corresponding /project/user-app/src and /project/user-app/lib directories in the container.
APPSODY_DEPS=<directory> Recommended. List of directories (separated by ;) in the Appsody container onto which persistent Docker volumes are mounted. Used to cache the combined dependencies of the stack components and the user application. APPSODY_DEPS=/project/deps

The /project/deps directory is mounted into a Docker volume.
APPSODY_USER_RUN_AS_LOCAL=[true|false] Optional. Sets the user identity within the container to match the host user’s UID. If a stack mounts a host directory, it ensures that files written to the host directory are using the host user’s UID, to avoid container-created files being owned by root.

The default is false.
APPSODY_USER_RUN_AS_LOCAL=true

The container's user identity is set to the host user's UID.
APPSODY_PREP=<command> Optional. This command is executed before the local development Appsody commands are run. This command should only be used to perform prerequisite checks or preparation steps prior to starting the app server.

If this command fails, the Appsody container terminates. It is not recommended to perform code compilation tasks in APPSODY_PREP because compilation errors can typically be fixed and recovered while the container is running with the local development Appsody commands. Unlike those commands, APPSODY_PREP is only run once, on starting the container.

Note: APPSODY_PREP has replaced APPSODY_INSTALL, which is now deprecated.
APPSODY_PREP="npm install --prefix user-app"

Runs npm install --prefix user-app prior to running all local development Appsody commands.
APPSODY_WATCH_DIR=<list of directories> Optional. List of directories (separated by ;) that the controller monitors for file changes. The controller will recursively monitor the subdirectories in these directories. The appsody stack lint command will error if you do not define at least one of the Appsody local development ON_CHANGE variables, when using the controller for file watching.

The default is APPSODY_MOUNTS
APPSODY_WATCH_DIR=/project/user-app/src;/project/user-app/tests

The controller watches for changes in the /project/user-app/src and /project/user-app/tests directories.
APPSODY_WATCH_INTERVAL=<integer> Optional. Frequency (in seconds) at which the controller checks for any file changes.

The default is 2.
APPSODY_WATCH_INTERVAL=3

Controller performs the watch check every 3 seconds.
APPSODY_WATCH_IGNORE_DIR=<list of directories> Optional. List of directories (separated by ;) that the controller does not monitor for file changes, typically used for excluding subdirectories of paths specified in APPSODY_WATCH_DIR. APPSODY_WATCH_IGNORE_DIR=/project/user-app/node_modules;/project/user-app/package.lock

Controller ignores changes in the /project/user-app/node_modules directory and the /project/user-app/package.lock file.
APPSODY_WATCH_REGEX=<regex> Optional. Regex expression that specifies the files that are monitored for changes. It is used to match the filename or the leaf directory, not the full path. The controller uses the Go regexp package, which does not support negative look ahead matching (e.g. ignore patterns).

The default is "(^.*.java$)|(^.*.js$)|(^.*.go$)".
APPSODY_WATCH_REGEX="^.*.js$"

Controller watches for changes in .js files.

Run Environment Variables

The environment variables that define how to start the development container, that is, when you use the appsody run command. You can set these environment variables so Appsody watches your local project directory for file changes, and updates the application to reflect code changes as you develop.

Environment Variable Description Example
APPSODY_RUN=<command> Mandatory. Defines the run command to start the server process after the APPSODY_PREP command completes. APPSODY_RUN="npm start"

Runs npm start after running the APPSODY_PREP command.
APPSODY_RUN_ON_CHANGE=<command> Optional. This command runs when a change is detected on the file system by the controller.

If this value is set to "", file watching is disabled.
APPSODY_RUN_ON_CHANGE="npm start"

Runs npm start when a file being watched by the controller is changed.
APPSODY_RUN_KILL=[true|false] Optional. This variable signals whether or not the controller kills the server process started by APPSODY_RUN, prior to starting the watch action specified by APPSODY_RUN_ON_CHANGE.

The default is true.
APPSODY_RUN_KILL=false

The server process started by APPSODY_RUN is not killed, prior to running APPSODY_RUN_ON_CHANGE.

Test Environment Variables

The environment variables that define how to start the development container, and run the test suite for both the stack and your application in the container, that is, when you use the appsody test command.

Environment Variable Description Example
APPSODY_TEST=<command> Recommended. Defines the test command to run the test suite after the APPSODY_PREP command completes. APPSODY_TEST="npm test && npm test --prefix user-app"

Runs npm test && npm test --prefix user-app after running the APPSODY_PREP command.
APPSODY_TEST_ON_CHANGE=<command> Optional. This command runs when a change is detected on the file system by the controller.

If this value is set to "", file watching is disabled.
APPSODY_TEST_ON_CHANGE=""

File watching is disabled, so the container terminates after the test suite has been run once.
APPSODY_TEST_KILL=[true|false] Optional. This variable is used to signal whether or not the controller kills the server process started by APPSODY_TEST prior to starting the watch action specified by APPSODY_TEST_ON_CHANGE.

The default is true.
APPSODY_TEST_KILL=false

The server process started by APPSODY_TEST is not killed, prior to running APPSODY_TEST_ON_CHANGE.

Debug Environment Variables

The environment variables that define how to start the development container with a debugger enabled, that is, when you use the appsody debug. Typically, the stack provides a debug port that connects to your IDE. You can then set breakpoints and step through your code as it runs in the container.

Environment Variable Description Example
APPSODY_DEBUG=<command> Recommended. Defines the debug command to run after the APPSODY_PREP command completes. APPSODY_DEBUG="npm run debug"

Runs npm run debug after running the APPSODY_PREP command.
APPSODY_DEBUG_ON_CHANGE=<command> Optional. This command runs when a change is detected on the file system by the controller.

If this value is set to "", file watching is disabled.
APPSODY_DEBUG_ON_CHANGE="npm run debug"

Runs npm run debug when a file being watched by the controller is changed.
APPSODY_DEBUG_KILL=[true|false] Optional. This variable signals whether or not the controller kills the server process started by APPSODY_DEBUG prior to starting the watch action specified by APPSODY_DEBUG_ON_CHANGE.

The default is true.
APPSODY_DEBUG_KILL=false

The server process started by APPSODY_DEBUG is not killed, prior to running APPSODY_DEBUG_ON_CHANGE.