env-config

A simple utility to manage environment configs in Java-based projects by merging *.properties files with environment variables overrides.

All notable changes to this project are documented in CHANGELOG.md. The format is based on Keep a Changelog and adheres to Semantic Versioning.

Setup

Add the following dependency to use this EnvConfig:

Maven

<dependency>
    <groupId>com.github.sitture</groupId>
    <artifactId>env-config</artifactId>
    <version>${version}</version>
</dependency>

Github Packages

If you would like to use github package instead of maven central, add the following repository to pom.xml.

<repositories>
  <repository>
    <id>github</id>
    <name>GitHub Packages</name>
    <url>https://maven.pkg.github.com/sitture/env-config</url>
  </repository>
</repositories>

Gradle

compile 'com.github.sitture:env-config:${version}'

Configuration

system property	environment variable	description
env.config.path	ENV_CONFIG_PATH	The base directory where the configuration files are lived. default: config directory under the project.
env.config.environment	ENV_CONFIG_ENVIRONMENT	The environment to activate. default: default directory under the base configuration directory.
env.config.profiles.path	ENV_CONFIG_PROFILES_PATH	The base directory where the profile based configuration files are lived. default: ${env.config.path}/${env.config.environment}/
env.config.profile	ENV_CONFIG_PROFILE	The profile to activate from the active environment directory.
env.config.keepass.enabled	ENV_CONFIG_KEEPASS_ENABLED	Whether to load properties from a keepass file. default: false
env.config.keepass.filename	ENV_CONFIG_KEEPASS_FILENAME	The keepass filename to load from the resources folder (src/main/resources). default: the root project directory name. i.e. project.build.directory
env.config.keepass.masterkey	ENV_CONFIG_KEEPASS_MASTERKEY	The password to open the keepass file. This is required if env.config.keepass.enabled=true.
env.config.vault.enabled	ENV_CONFIG_VAULT_ENABLED	Whether to load properties from a vault secret. default: false
env.config.vault.address	ENV_CONFIG_VAULT_ADDRESS	The host address of the vault instance. This is required if env.config.vault.enabled=true.
env.config.vault.namespace	ENV_CONFIG_VAULT_NAMESPACE	The vault namespace to look for secrets. This is required if env.config.vault.enabled=true.
env.config.vault.default.secret.path	ENV_CONFIG_VAULT_DEFAULT_SECRET_PATH	The base secret path for the project. This is optional when there's a shared secret across multiple projects.
env.config.vault.secret.path	ENV_CONFIG_VAULT_SECRET_PATH	The base secret path for the project. This is required if env.config.vault.enabled=true.
env.config.vault.token	ENV_CONFIG_VAULT_TOKEN	The vault token used for authentication. This is required if env.config.vault.enabled=true.

Configuration precedence

1. Java System properties - System.getProperties()
2. OS environment variables - System.getenv()
3. Environment profile properties - config/${env.config.environment}/${env.config.profile}/*.properties
4. Default profile properties - config/default/${env.config.profile}/*.properties
5. Environment specific properties - config/${env.config.environment}/*.properties
6. Default properties - config/default/*.properties

Usage

To start using this:

config directory

The default required directory for configuration files in config under project root. This can be overridden by ENV_CONFIG_PATH environment variable.

• create a directory called config in project root.

config environments

The default environment is set to default and can be overridden by ENV_CONFIG_ENVIRONMENT environment variable.

1. create a default environment subdirectory under config directory.
2. create a default.properties file in the default directory. E.g. config/default/default.properties

# formatted as key=value
my.first.property=my_first_value
my.second.property=my_second_value

You can add multiple .properties files under environment directory. E.g. You may want to split the properties into:

.
├── config
│   └── default
│       ├── default.properties
│       └── db.properties

You can create as many environments as needed.

.
├── config
│   └── default
│       ├── default.properties
│       └── db.properties
│   └── integration
│       └── integration.properties

config profiles

You can also have config profiles within an environment directory by specifying the ENV_CONFIG_PROFILE=profile1 variable E.g.

.
├── config
│   └── default
│       └── profile1
│           └── profile1.properties
│       └── profile2
│           └── profile2.properties
│       └── default.properties
│   └── integration
│       └── profile1
│           └── profile1.properties
│       └── integration.properties

If ENV_CONFIG_ENVIRONMENT=integration and ENV_CONFIG_PROFILE=profile1 suggests to load properties in the following order:

1. integration/profile1/profile1.properties
2. default/profile1/profile1.properties
3. integration/integration.properties
4. default/default.properties

base environments

You can base an environment based on another by specifying multiple environment in ENV_CONFIG_ENVIRONMENT environment variable.

E.g. if you would like env2 environment to inherit properties from env2 environment:

ENV_CONFIG_ENVIRONMENT=env1,env2

The above will load environment properties from env2 on top of env1 and finally the default properties from default environment.

KeePass Database Entries

If you have secret passwords which cannot be stored as plain text within project repository, you can store them into a password-protected KeePass database file.

1. create a keepass database file, add to your resources folder. i.e. src/main/resources or src/test/resources.

Configurations

• ENV_CONFIG_KEEPASS_ENABLED - A flag to enable reading of the keePass file. Default is set to false.
• ENV_CONFIG_KEEPASS_FILENAME - This is the name of the DB file. Default is the name of project directory.
• ENV_CONFIG_KEEPASS_MASTERKEY - The key to access the DB file.

KeePass Groups

• The top level group should have the same name as the DB filename. e.g. if DB file is keepass.kdbx then top level group should be keepass.
• The sub-groups should match with the environment directory you have created above. For example, you should have default group for the default environment.
• The entries within the default group will be shared across all environments similar to the environment directories behaviour.

Environment priority

The EnvConfig will go through properties set under your environment and then load properties from default environment ignoring the ones already set. You can keep the shared properties under your default environment without having to repeat them in every other environment.

Current environment

You can get the current environment by:

EnvConfig.getEnvironment();

Get property EnvConfig.get("...")

To get a property set either in the properties file, system property or environment variable:

EnvConfig.get("my.property");
EnvConfig.getInt("my.property");
EnvConfig.getBool("my.property");
EnvConfig.getList("my.property"); // will return a List<String> from a comma separated String.

Get required property

// when a property is required to continue
EnvConfig.getOrThrow("my.property");

If the property isn't set then a EnvConfigException is thrown.

Get property with defaultValue

// return a default value when a property isn't found
EnvConfig.get("my.property", "defaultValue");

Note: All the environment variable names are set to properties naming convention. E.g. MY_ENV_VAR can either be accessed by EnvConfig.get("my.env.var"); or EnvConfig.get("MY_ENV_VAR");

Property overrides

You can override any property set in the environment properties file by setting an system environment variable.

E.g. my.env.property can be overridden by MY_ENV_PROPERTY environment variable.

Add property EnvConfig.add("...")

You can add key/value pairs to the EnvConfig to be accessed somewhere else in the project.

EnvConfig.add("my.property", "my_value");

Set property EnvConfig.set("...")

You can set/update an existing property in EnvConfig:

EnvConfig.set("my.property", "my_value");

The .set(...) can be used for both existing and non-existing properties.

Clear property EnvConfig.clear("...")

You can clear an existing property in EnvConfig:

EnvConfig.clear("my.property")

Get all EnvConfig.asMap()

You can get a full list of available properties with EnvConfig.asMap() which is a combination of properties from config directory, system properties and all environment variables.

Issues & Contributions

Please open an issue here on GitHub if you have a problem, suggestion, or other comment.

Pull requests are welcome and encouraged! Any contributions should include new or updated unit tests as necessary to maintain thorough test coverage.

Read CONTRIBUTING.md for guidelines.