🗝 spring-dotenv

Provides a Spring PropertySource that delegates to the excellent dotenv-java library.

Storing configuration in the environment is one of the tenets of a twelve-factor app. Anything that is likely to change between deployment environments – such as resource handles for databases or credentials for external services – should be extracted from the code into environment variables.

It is not always practical to set environment variables on development machines or continuous integration servers. Dotenv loads variables from a .env file for your convenience during development.

Installation

... but first!

Add this to .gitignore

### Local Configuration ###
.env

Loading environment variables from the .env is for your development convenience and the file should not be committed to source control.

It is common, however, to commit a .env.example file to source control which documents the available variables and gives developers an understanding of how to create their own local .env file.

Maven and Gradle

Installation instructions

Usage

Refer to the demo application.

Imagine a simple application which outputs "Hello, example.name". We can use Spring to load the property example.name from an application.properties file or an application.yml file.

Now imagine we want to extract that example.name so that it is loaded from the environment instead of hard-coded into application.properties.

If a value for example.name is set in the environment, we certainly want to use that value. However, for your convenience during development, you may declare that value in a .env file and it will be loaded from there. It is important to understand the precedence; a variable set in the environment will always override a value set in the .env file.

Spring provides different ways to read properties. This example uses the @Value annotation, but feel free to use whichever ways suit your case.

@Value("${example.name}")
String name;

With Spring, you may provide properties in a .properties file or a .yml file.

Notice the reference to env here. This is the property source which invokes the dotenv library to load values from the environment and .env file.

Add to application.yml

example:
  name: ${env.EXAMPLE_NAME}

or with a default value of "World"

example:
  name: ${env.EXAMPLE_NAME:World}

And of course, a .properties file works too

example.name = ${env.EXAMPLE_NAME}

At this point, we've told Spring to load the value example.name from the environment. It must be supplied, otherwise you will get an exception.

Now create a .env file

EXAMPLE_NAME=Paul

This file is yours and does not belong in source control. Its entire purpose is to allow you to set environment variables during development.

Now set the variable in the environment and notice that it has higher precedence than the value set in the .env file.

export EXAMPLE_NAME=World

Configuration (optional)

This library supports the same configuration values as the underlying dotenv-java configuration. Configuration is completely optional, however if you need to override defaults, you may do so by adding the following to your application.yml (or .properties):

.env:
  directory: <string>
  filename: <string>
  ignoreIfMalformed: <boolean>
  ignoreIfMissing: <boolean>
  systemProperties: <boolean>
  prefix: <string>

By default, this library sets ignoreIfMissing to true. You may change this behaviour as follows:

.env:
  ignoreIfMissing: false

This library expects properties to be prefixed with env. as follows. However, you may configure a different prefix.

.env:
  prefix: ""

example:
  name: ${EXAMPLE_NAME:World}

If you prefer .properties files:

.env.directory: <string>
.env.filename: <string>
.env.ignoreIfMalformed: <boolean>
.env.ignoreIfMissing: <boolean>
.env.systemProperties: <boolean>
.env.prefix: <string>

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

License

MIT

Acknowledgements

Laravel Configuration for a great example of integrating dotenv with a framework.
The dotenv libraries for Ruby and Java.
Spring Boot's RandomValuePropertySource for an example of a custom property source.
Michał Bychawski for help putting this together.