Need help with nomad?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

205 Stars 15 Forks 209 Commits 0 Opened issues


A configuration library designed to allow Clojure applications to travel painlessly between different environments.

Services available


Need anything else?

Contributors list

  • nomad

A configuration library designed to allow Clojure applications to travel painlessly between different hosts and environments.

** Usage

*** Set-up

Add the nomad dependency to your =project.clj=

+BEGIN_SRC clojure

[jarohen/nomad "0.9.0"]

{jarohen/nomad {:mvn/version "0.9.0"}}


Please see the Changelog for more details.

*** Rationale

In an ideal world, we'd choose to declare configuration as a vanilla Clojure map, and access it as such, from anywhere, and everything would Just Work™.

Nomad aims to get as close to that as possible. In doing so, it makes a few opinionated decisions:

  • Configuration is declared near the code it is configuring - i.e. not in an EDN file, not in environment variables, not in a separate infrastructure repository, not in deploy scripts, etc etc etc. This locality allows us to reason about how the code will behave in certain environments without having to audit an entire system, and aids us when we come to adding new configuration variables.

Sure, we'll always need to allow whatever's bootstrapping our application to alter the behaviour in some way (Nomad relies on passing in a set of 'switches', for example), but let's minimise it.

  • Configuration is declared in Clojure - this gives us the full flexibility of normal Clojure functions to build/compose our configuration as necessary. In our experience, configuration libraries often tend to try to replicate a full language trying to emulate certain behaviours - retrieving configuration from elsewhere, fallbacks/defaults, environment variable parsing and composing multiple configuration files, to name a few.

Let's just use Clojure core/simple Java interop over a config-specific DSL - they're good at this.

Is there a possibility of this freedom getting abused, and the boundary between 'configuration' and code getting blurred? Sure. I'm trusting you to know when your configuration goes significantly beyond 'just a map', though.

*** Migrating from 0.7.x/0.8.x betas

I had a significant re-think of what I wanted from a configuration library between 0.7.x/0.8.x and 0.9.x, based on learnings from using it in a number of non-trivial applications.

  • The original 0.7.x behaviour will be maintained for the time being, in the original =nomad= namespace, although will be removed in a later release.
  • The 0.8.x behaviour never made it to a stable release, and so has been removed in 0.9.0-rc1.

There is a migration guide for both of these versions in the changelog.

** Getting started

First, we require =[nomad.config :as n]=.

In the entry point to our application (or, for now, at the REPL) we need to initialise Nomad - over time, we'll need to add to this:

+BEGIN_SRC clojure

(n/set-defaults! {})


We then use =defconfig= to declare some configuration:

+BEGIN_SRC clojure

(n/defconfig email-config {:email-behaviour :just-console-for-now})

(defn email-user! {:keys [...] :as email} :actually-send-the-email (send-email! email)))


We can see that, once we've declared our configuration, we use it in the same way we'd use any other vanilla Clojure data structure. We can destructure it, compose it, pass it around, play with it/redefine it in our REPL - no problem.

If I wanted to, I could use =System/getenv=, =System/getProperty=, or any vanilla Clojure functions etc in here:

+BEGIN_SRC clojure

(n/defconfig email-config {:behaviour :actually-send-the-email :host (System/getenv "EMAILHOST") :port (or (some-> (System/getenv "EMAILPORT") Long/parseLong) 25)})


This obviates the need for any kind of config DSL to retrieve/parse/default configuration values.

** Changing configuration based on location

Your configuration will likely vary depending on whether you're running your application in development, test/beta/staging environments, or production. Nomad accomplishes this using 'switches', which are set in your call to =set-defaults!=:

+BEGIN_SRC clojure

(n/set-defaults! {:switches #{:live}})


You can then vary your configuration using the =n/switch= macro, which behaves a lot like Clojure's =case= macro:

+BEGIN_SRC clojure

;; in your app entry point (n/set-defaults! {:switches #{:live}})

;; in your namespace (n/defconfig db-config (merge {:port 5432} (n/switch :beta {:host "beta-db-host" :username "beta-username"} :live {:host "live-db-host" :username "live-username"}

         ;; you can also provide a default, if none of the above switches are
         ;; active
         {:host "localhost"
          :username "local-user"})))

;; at the REPL (say) (let [{:keys [host port username]} db-config] ;; in here, we get the live config, because of our earlier



You're free to choose how to select your switches - or, you can use =n/env-switches=, which looks for the =NOMAD_SWITCHES= environment variable, or the =nomad.switches= JVM property, expecting a comma-separated list of switches:

+BEGIN_SRC clojure

;; starting the application NOMAD_SWITCHES=live,foo java -cp ... clojure.main -m ...

;; --- in the entry point (n/set-defaults! {:switches n/env-switches}) ;; sets switches to #{:live :foo}


** Secrets (shh!)

Nomad can manage your secrets for you, too. Under Nomad, these are encrypted and checked in to your application repository, with the encryption keys managed outside of your application (in whatever manner you choose).

First, generate yourself an encryption key using =(n/generate-key)=

+BEGIN_SRC clojure

(nomad.config/generate-key) ;; => "tvuGp8oGGbP+IQSzidYS+oXB3fhGZLpVLhMFljL0I/o="


We then pass this to Nomad as part of the call to =set-defaults!=:

+BEGIN_SRC clojure

(n/set-defaults! {:secret-keys {:my-dev-key "tvuGp8oGGbP+IQSzidYS+oXB3fhGZLpVLhMFljL0I/o="}})


Obviously, normally, this would not be checked into your application repository! You can get it from an environment variable, an out-of-band file on the local disk, some external infrastructure management, some cloud key manager, or something else entirely - take your pick!

We then encrypt credentials using =n/encrypt=, and store this cipher-text, along with the key-id used to encrypt the credentials, in our =defconfig= declarations:

+BEGIN_SRC clojure

;; --- at your REPL

(n/encrypt :my-dev-key "super-secure-password123") ;; => "y/DwItK86ZgtUUTzz+sDCNd3rpsOuiyKmqcHIelHnRdrpr06k43NEnrraWrfUHE39ZXtLItqxZVM3hmCj1pqLw=="

;; --- in your namespace (defconfig db-config {:host "db-host" :username "db-username" :password (n/decrypt :my-dev-key "y/DwItK86ZgtUUTzz+sDCNd3rpsOuiyKmqcHIelHnRdrpr06k43NEnrraWrfUHE39ZXtLItqxZVM3hmCj1pqLw==")})

;; access the password like any other map key (let [{:keys [host username password]} db-config] ...)


** Testing your configuration

Given configuration declarations are just normal Clojure variables, you can experiment with them at the REPL, as you would any other Clojure data structure.

Nomad does offer a couple of other tools to facilitate testing, though. First, =defconfig= declarations can be dynamically re-bound, using Clojure's standard =binding= macro:

+BEGIN_SRC clojure

(n/defconfig email-config {:email-behaviour :just-console-for-now})

(defn email-user! {:keys [...] :as email} :actually-send-the-email (send-email! email)))

(email-user! {...}) ;; prints the email to the console

(binding email-config {:email-behaviour :actually-send-the-email}) ;; actually sends the email


Nomad also offers a =with-config-override= macro, which allows you to override what switches are active, throughout your system, for the duration of the expression body:

+BEGIN_SRC clojure

(n/defconfig email-config {:email-behaviour (n/switch :live :actually-send-the-email :just-console-for-now)})

(defn email-user! {:keys [...] :as email} :actually-send-the-email (send-email! email)))

(email-user! {...}) ;; prints the email to the console

(n/with-config-override {:switches #{:live}} (email-user! {...})) ;; actually sends the email


** Bugs/features/suggestions/questions?

Please feel free to submit bug reports/patches etc through the GitHub repository in the usual way!


** Changes

The Nomad changelog has moved to

** License

Copyright © 2013-2018 James Henderson

Distributed under the Eclipse Public License, the same as Clojure.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.