🗝️
dotenv-kotlin
A port of the Ruby dotenv project for Java and Kotlin. Load environment variables from a .env file.
Looking for the pure Java version? Get dotenv-java.
Why dotenv?
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.
But it is not always practical to set environment variables on development machines or continuous integration servers where multiple projects are run. Dotenv load variables from a .env file into ENV when the environment is bootstrapped.
Environment variables listed in the host environment override those in .env.
Use dotenv.get("...") instead of Java's System.getenv(...).
Install
Looking for the pure Java variant (no Kotlin), get dotenv-java.
Maven
<dependency>
<groupId>io.github.cdimascio</groupId>
<artifactId>dotenv-kotlin</artifactId>
<version>6.2.2</version>
</dependency>
Gradle
Gradle Groovy DSL
implementation 'io.github.cdimascio:dotenv-kotlin:6.2.2'
Gradle Kotlin DSL
implementation("io.github.cdimascio:dotenv-kotlin:6.2.2")
Usage
Use dotenv.get("...") instead of Java's System.getenv(...). Here's why.
Create a .env file in the root of your project
# formatted as key=value
MY_ENV_VAR1=some_value
MY_EVV_VAR2=some_value
With Java
import io.github.cdimascio.dotenv.Dotenv;
Dotenv dotenv = Dotenv.load();
dotenv.get("MY_ENV_VAR1")
or with Kotlin
import io.github.cdimascio.dotenv.dotenv
val dotenv = dotenv()
dotenv["MY_ENV_VAR1"]
Android Usage
-
Create an assets folder
-
Add
env(no dot) to the assets folder.
-
Configure dotenv to search
/assetsfor a file with nameenvval dotenv = dotenv { directory = "/assets" filename = "env" // instead of '.env', use 'env' } dotenv["MY_ENV_VAR1"]
Note: The above configuration is required because dot files in /assets do not appear to resolve on Android. (Seeking recommendations from the Android community on how dotenv-kotlin configuration should work in order to provide the best experience for Android developers)
Alternatively, if you are using Provider android.resource you may specify
directory = "android.resource://com.example.dimascio.myapp/raw"
Advanced Usage
Configure
Configure dotenv-kotlin once in your application.
With Java
Dotenv dotenv = Dotenv.configure()
.directory("./some/path")
.ignoreIfMalformed()
.ignoreIfMissing()
.load();
or with Kotlin
val dotenv = dotenv {
directory = "./some/path"
ignoreIfMalformed = true
ignoreIfMissing = true
}
Get environment variables
Note, environment variables specified in the host environment take precedence over those in .env.
With Java
dotenv.get("HOME");
dotenv.get("MY_ENV_VAR1", "default value");
or with Kotlin
dotenv["HOME"]
dotenv["MY_ENV_VAR1"] ?: "default value"
Iterate over environment variables
Note, environment variables specified in the host environment take precedence over those in .env.
With Java
for (DotenvEntry e : dotenv.entries()) {
System.out.println(e.getKey());
System.out.println(e.getValue());
}
or with Kotlin
for (e in dotenv.entries()) {
println(e.key)
println(e.value)
}
Configuration options
optional directory
-
pathspecifies the directory containing.env. Dotenv first searches for.envusing the given path on the filesystem. If not found, it searches the given path on the classpath. Ifdirectoryis not specified it defaults to searching the current working directory on the filesystem. If not found, it searches the current directory on the classpath.Java example
Dotenv .configure() .directory("/some/path") .load()
Kotlin Dsl example
dotenv { directory = "/some/path" }
optional filename
-
Use a filename other than
.env. Recommended for use with Android (see details)Java example
Dotenv .configure() .filename("myenv") .load()
Kotlin Dsl example
dotenv { filename = "myenv" }
optional ignoreIfMalformed
-
Do not throw when
.enventries are malformed. Malformed entries are skipped.Java example
Dotenv .configure() .ignoreIfMalformed() .load()Kotlin Dsl example
dotenv { ignoreIfMalformed = true }
optional ignoreIfMissing
-
Do not throw when
.envdoes not exist. Dotenv will continue to retrieve environment variables that are set in the environment e.g.dotenv["HOME"]Java example
Dotenv .configure() .ignoreIfMissing() .load()Kotlin Dsl example
dotenv { ignoreIfMissing = true }
optional systemProperties
-
Load environment variables into System properties, thus making all environment variables accessible via
System.getProperty(...)Java example
Dotenv .configure() .systemProperties() .load()Kotlin Dsl example
dotenv { systemProperties = true }
Examples
- with Maven (simple)
- with Spring MVC
- with Spring Webflux
- with Android
- see Kotlin DSL tests
- see Java tests
FAQ
Q: Should I deploy a .env to e.g. production?
A: Tenant III of the 12 factor app methodology states "The twelve-factor app stores config in environment variables". Thus, it is not recommended to provide the .env file to such environments. dotenv, however, is super useful in e.g a local development environment as it enables a developer to manage the environment via a file which is more convenient.
Using dotenv in production would be cheating. This type of usage, however is an anti-pattern.
Q: Why should I use dotenv.get("MY_ENV_VAR") instead of System.getenv("MY_ENV_VAR")
A: Since Java does not provide a way to set environment variables on a currently running process, vars listed in .env cannot be set and thus cannot be retrieved using System.getenv(...).
Q: Can I use System.getProperty(...) to retrieve environment variables?
A: Sure. Use the systemProperties option. Or after initializing dotenv set each env var into system properties manually. For example:
Java
Dotenv dotenv = Dotenv.configure().load();
dotenv.entries().forEach(e -> System.setProperty(e.getKey(), e.getValue()));
System.getProperty("MY_VAR");
Kotlin
val dotenv = dotenv()
dotenv.entries().forEach { (key, value) -> System.setProperty(key, value) }
Q: Should I have multiple .env files?
A: No. We strongly recommend against having a "main" .env file and an "environment" .env file like .env.test. Your config should vary between deploys, and you should not be sharing values between environments.
In a twelve-factor app, env vars are granular controls, each fully orthogonal to other env vars. They are never grouped together as “environments”, but instead are independently managed for each deploy. This is a model that scales up smoothly as the app naturally expands into more deploys over its lifetime.
– The Twelve-Factor App
Q: Should I commit my .env file?
A: No. We strongly recommend against committing your .env file to version control. It should only include environment-specific values such as database passwords or API keys. Your production database should have a different password than your development database.
Q: What happens to environment variables that were already set?
A: dotenv-kotlin will never modify any environment variables that have already been set. In particular, if there is a variable in your .env file which collides with one that already exists in your environment, then that variable will be skipped. This behavior allows you to override all .env configurations with a machine-specific environment, although it is not recommended.
Q: What about variable expansion in .env?
A: We haven't been presented with a compelling use case for expanding variables and believe it leads to env vars that are not "fully orthogonal" as The Twelve-Factor App outlines. Please open an issue if you have a compelling use case.
Q: Can I supply a multi-line value?
A: dotenv-kotlin exhibits the same behavior as Java's System.getenv(...), thus if a multi-line value is needed you might consider encoding it via e.g. Base64. see this comment for details.
Note and reference: The FAQs present on motdotla's dotenv node project page are so well done that I've included those that are relevant in the FAQs above.
Contributors
Contributions are welcome!
 Carmine DiMascio |
 Arniu Tseng |
 Paul Woolcock |
 Playacem |
 Clément P. |
 Harry Henry Gebel |
 NyCode |
see CONTRIBUTING.md
License
see LICENSE (Apache 2.0)
0 Feb 8, 2022
5 Mar 6, 2022
6 Dec 16, 2022
14 Dec 27, 2022
31 Aug 5, 2022
18.4k Jan 3, 2023
3 Jul 28, 2022
35 May 31, 2022
290 Dec 30, 2022
2 Jun 21, 2022
2 Mar 6, 2022
10 Dec 17, 2022
7 Oct 2, 2022
0 Jun 2, 2022
99 Dec 30, 2022
41 Nov 30, 2022
141 Jan 5, 2023
104 Dec 26, 2022
654 Jan 4, 2023