DOCSEARCHbyAlgolia
Submit Docs

environ

repository·master·Indexed 21 days ago

https://github.com/weavejester/environ

A Clojure library for 12-factor app compliance that manages configuration from multiple sources, including environment variables, Java system properties, and Leiningen/Boot profiles. It provides a unified way to retrieve settings via `environ.core/env` with automatic key normalization.

Tokens
887
Snippets
3
Records
5
Agent score
26%

What's inside environ

  1. How Environ resolves configuration sources

    master

    Environ manages environment settings by resolving them from multiple sources in a specific order of precedence. If a key exists in multiple sources, the one higher in this list wins:

    1. A .lein-env file in the project directory (managed by lein-environ).
    2. A .boot-env file on the classpath (managed by boot-environ).
    3. Environment variables.
    4. Java system properties.

    Important Note: When running a compiled uberjar (e.g., via lein uberjar), Environ cannot access settings from project.clj. In production/compiled environments, you must use shell environment variables or Java system properties.

  2. Install Environ

    master

    To use Environ in your Clojure project, add it as a dependency in your project.clj file.

    If you are using Leiningen and want to pull settings from your project map, also include the lein-environ plugin.

    If you are using the Boot toolchain, add boot-environ to your dependencies and require the environ.boot/environ task in your build.boot file.

    ;; project.clj
:dependencies [[environ "1.2.0"]] 

;; Optional: for Leiningen project map integration
:plugins [[lein-environ "1.2.0"]] 
    ;; build.boot
:dependencies '[[boot-environ "1.2.0"]]

(require '[environ.boot :refer [environ]])

  3. Configure settings for Leiningen and Boot

    master

    Leiningen

    Use a profiles.clj file in your project directory to define local development or testing settings. These profiles are merged with your project.clj profiles. Use the :env key within a profile to define settings.

    ;; profiles.clj
{:dev  {:env {:database-url "jdbc:postgresql://localhost/dev"}}
 :test {:env {:database-url "jdbc:postgresql://localhost/test"}}}

    To look up values directly from the Leiningen project map, use keywords with the project namespace (e.g., :project/version looks up the :version key in the project map).

    Boot

    In Boot, you can pass settings via the CLI or within build pipelines:

    CLI usage:

    $ boot environ -e database-url=jdbc:postgresql://localhost/dev repl

    Pipeline usage:

    (environ :env {:database-url "jdbc:postgresql://localhost/dev"})
    ;; Example of using a project-mapped value in profiles.clj
{:env {:app-version :project/version}}

  4. Set configuration via Shell or System Properties

    master

    For production environments or compiled uberjars, set configuration using standard OS environment variables or Java system properties. Environ will normalize these to keywords.

    Shell Environment Variable:

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

    Java System Property:

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

  5. Access environment settings with `environ.core/env`

    master

    Use the env function from environ.core to retrieve configuration values by keyword. Environ automatically normalizes keys: it lowercases them and replaces underscores (_) and dots (.) with hyphens (-).

    For example, the environment variable DATABASE_URL or the system property database.url will both be accessed using the keyword :database-url.

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

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