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

Java System properties - System.getProperties()
OS environment variables - System.getenv()
Environment profile properties - config/${env.config.environment}/${env.config.profile}/*.properties
Default profile properties - config/default/${env.config.profile}/*.properties
Environment specific properties - config/${env.config.environment}/*.properties
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.

create a default environment subdirectory under config directory.
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:

integration/profile1/profile1.properties
default/profile1/profile1.properties
integration/integration.properties
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.

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.

sitture/env-config