commandbox-dotenv

Load a local file into Java Properties for CommandBox commands and servers

Storing secrets in source-controlled files is a bad idea, but we still need some way to provide these sensitive credentials or configuration values to our projects. This problem is exacerbated in development environments where we are running multiple servers at once. This package let's us solve this problem for servers started with CommandBox.

Usage

This package loads up local files as Java Properties for both CommandBox commands and servers. The usage is nearly identical, but with enough gotchas to warrant breaking them out in to separate sections.

One note about the .env file: Do not commit it to source control. Add it to your .gitignore immediately.

Another good tip is to create an .env.example file that is source controlled that contains all the keys required in your .env file but none of the values.

CommandBox Startup

When loading up the CLI, this package will look for a .env file in the directory where CommandBox is being loaded or executed. If found it will take the key / value pairs found in the file and store them as CommandBox environment variables. These values are now available in any CommandBox command either using systemSettings.getSystemSetting( name, defaultValue ), or by using CommandBox's built-in system variable expansion.:

echo ${myvar}

CommandBox Commands

Any time you run a command, if there is a .env file in the current working directory where the command was run, those vars will be loaded into the environment context of that command only. This is great for localized variables that only apply to a specific project. Note, this feature only kicks in if you are on CommandBox 4.5 or higher.

CommandBox Servers

When starting up a server, this package will look for a .env file in the webroot of the server starting. If found, it will take the key / value pairs found in the file and store them as Java properties. These values are now available in your web application using the java.lang.System object and the getProperties() or getProperty(name, defaultValue) methods (Note: the keys are case-sensitive).

To point to a custom properties file to be loaded in addition to the convention .env file above, you can set a dotenvFile key in your server.json or config setting server.defaults.

server set dotenvFile=foo.properties

You can also set a comma-delimited list of paths using file globbing patterns.

# Load all properties files in the web root as well as foo.properties in the config folder.
server set dotenvFile=*.properties,config/foo.properties

When using CommandBox in multi-site mode (6.0.0+) any time a .site.json file is read for a specific site, any existing .env will be read from the web root of that site and used for expanding any system setting placeholders in that site JSON file. CommandBox will use a nested environment for loading this .env file so any env var names declared here will not conflict with env vars in the global sheel or loaded at the top server level or or any other sites. None of the site-specific env vars will be passed to the running server process. They are only used inside the .site.json.

Global Env File

When starting up the CLI, CommandBox will look for a ~/.box.env file. It will load the file's key / value pairs as environment variables inside CommandBox.

If you change the contents of this file, you will need to reload your shell for the changes to take effect.

If you want to change the name of the global environment file, you can update your module settings:

config set modules.commandbox-dotenv.globalEnvFile = "~/.commandbox.env"

Different Property File Name

The file name .env can be overridden, if desired.

For instance, by running:

config set modules.commandbox-dotenv.fileName=env.properties

all your file names will need to be env.properties.

You can also set your example env file name:

config set modules.commandbox-dotenv.exampleFileName=env.properties

There is currently no way to provide a per-project override.

Logging Properties

There are two levels of logging available. You can log to the console every time an .env file has been loaded by setting the printOnLoad setting to true.

config set modules.commandbox-dotenv.printOnLoad=true

You can get further output that shows you the name and value of every variable that was loaded by setting the verbose setting to true as well.

config set modules.commandbox-dotenv.verbose=true

The verbose setting will only kick in if printOnLoad is also true.

Check Command

When using environment variables, you will inevitably run in to a situation where you lose time debugging a strange error only to find that you haven't provided a value for a new environment variable. The check command will check that all the keys in your .env.example file exist in your .env file.

dotenv check

The filenames can be overridden with the envFileName and envExampleFileName parameters to the command.

dotenv check envFileName=env.properties envExampleFileName=env.example.properties

You can reverse the check to ensure the .env.example file has all the keys in your .env file by passing the --reverse flag.

dotenv check --reverse

One great place to add this command is using CommandBox GitHooks.

{
    "githooks": {
        "preCommit": "dotenv check --reverse",
        "postCheckout": "dotenv check",
        "postMerge": "dotenv check"
    }
}

This will prevent you from commiting code when you have .env keys that are not in your .env.example file. It will also check for any new keys in your .env.example file and notify you of them after checking out a new branch

Another great place to add this command is in your CI pipeline to avoid deploying a build with a missing environment variable.

preServerStart Check

Enabled by default is a preServerStart check. This will run dotenv check for you and throw an error if the .env file does not have all of the .env.example keys. This is to help prevent you spending precious time debugging your application just to find you are missing an env key.

If you do not want this behavior, you can set the checkEnvPreServerStart module setting to false.

box config set modules.commandbox-dotenv.checkEnvPreServerStart=false

Env File Commands

Thanks to Dan Card and his commandbox-envfile library, you can interact with your env file right from CommandBox. There are four commands to help you out.

dotenv show

This shows the current .env file contents. You can pass an override envFileName or folder, if desired.

dotenv get

This gets the value of a key in the current .env file. You can pass an override envFileName or folder, if desired. Don't forget tab completion here to help you fill out the key names quickly!

dotenv set

This takes two arguments, a name and a value, and sets it in your current .env file. Current property names can be tab completed. You can pass an override envFileName or folder, if desired.

dotenv populate

This command will inspect your .env.example file and help you fill out the values in your .env file. Additionally, it can only prompt you for new values using the --new flag. The exampleFileName, envFileName, and folder can all be customized, if desired.

dotenv load

This command will load arbitrary properties files into your CommandBox environment. Useful for task runners where you need to load a shared environment file.