Ambiente

Ambiente is a Clojure library for managing environment settings from a number of different sources. It works well for applications following the 12 Factor App pattern.

Currently, Ambiente supports four sources, resolved and merged down in the following order:

1. A .env.edn file in the project directory
2. A .env file on the project directory
3. Environment variables
4. Java system properties

The .env.edn file is expected to be an edn file containing a map where keys are the sanitized, keywordized names of the variables you intend to overwrite.

The .env file is expected to be a file in the traditional dotenv format.

Installation

Include the following dependency in your deps.edn:

{:deps {luchiniatwork/ambiente {:mvn/version "0.1.6"}}}

Usage

Let's say you have an application that requires a database connection. Let's pull the database connection details from the key :database-url on the ambiente.core/env map.

(require '[ambiente.core :refer [env]])

(def database-url
  (env :database-url))

The value of this key can be set in several different ways. The most common way during development is to use either a local .env.edn or .env file in your project directory. These files would be in your .gitignore to avoid them getting dangerously exposed (i.e. instead of :database-url, we could have an :api-key.)

The .env.edn file contains a map that will be merged with environment variables and system properties:

{:database-url "jdbc:postgresql://localhost/dev"}

Alternatively, the .env file could have been used. It contains a list key/value pairs separated by newlines:

$ DATABASE_URL=jdbc:postgresql://localhost/dev

This means that if you run your repl locally (i.e. $ clojure), the dev database will be used, and if you run $ DATABASE_URL=jdbc:postgresql://localhost/test clojure, the test database will be used.

When you deploy to a production environment, you can make use of environment variables, like so:

$ DATABASE_URL=jdbc:postgresql://localhost/prod java -jar standalone.jar

Or use Java system properties:

$ java -Ddatabase.url=jdbc:postgresql://localhost/prod -jar standalone.jar

Note that Ambiente automatically lower-cases keys, replaces the characters "_" and "." with "-", and keywordize variable names. The environment variable DATABASE_URL and the system property database.url are therefore both converted to the same keyword :database-url.

Variable Assertions

In some circumstances you may want to assert that your enviroment is properly set. In order to do that, use function env-assert:

(require '[ambiente.core :refer [env-assert]])

(env-assert [:foobar           ;; FOOBAR must be present
             [:barfoo string?] ;; BARFOO must be a string
             ;; FOO must not be "a" + custom message
             [:foo #(not= "a" %) "should not be a"]
             ;; BAR must not be "b" + exception handling
             [:bar #(when (not= "b" %) (throw (ex-info "my error" {})))]])

env-assert throws an exception by default. If you don't want this behavior, use {:throw? false}:

(env-assert [:foo] {:throw? false}) ;; => {:foo {:message "Missing"}}

Development

Tests can be run with:

$ clojure -A:test --watch

Motivation and Inspiration

Ambiente is heavily and openly inspired by environ and dotenv.

I've used environ for ages and it's a great project but, the more I move to tools.deps, the less I like seeing file named after Leiningen in my project directory.

Sometimes .env files are shared around developers of specific teams (particularly in non-Clojure or multi-language projects). For years I've wanted environ to support these files.

Lastly, dotenv's reliance on Leiningen's profiles also frustrated me because it's an approach that might lead to developers wrongly storing data in the project.clj file. Ambiente of course does not fully remove this possibility (developers may still commit their .env files) but it at least assumes that deps.edn, environment variables and profiles are different things to be managed.

As a bonus, I also wanted to be more explicit on the warnings emitted - particularly when variables are overwritten.

License

Distributed under the MIT Public License. Use it as you will. Contribute if you have the time.