https://github.com/james-henderson/nomad.git
git clone 'https://github.com/james-henderson/nomad.git'
(ql:quickload :james-henderson.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=
[jarohen/nomad “0.9.0-rc1”]
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:
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.
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.
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:
(n/set-defaults! {})
We then use =defconfig= to declare some configuration:
(n/defconfig email-config {:email-behaviour :just-console-for-now})
(defn email-user! [{:keys […] :as email}] (case (:email-behaviour email-config) :just-console-for-now (prn “Would send:” 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:
(n/defconfig email-config {:behaviour :actually-send-the-email :host (System/getenv “EMAIL_HOST”) :port (or (some→ (System/getenv “EMAIL_PORT”) 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!=:
(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:
;; 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 set-defaults!
…)
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:
;; 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)=
(nomad.config/generate-key) ;; ⇒ “tvuGp8oGGbP+IQSzidYS+oXB3fhGZLpVLhMFljL0I/o=”
We then pass this to Nomad as part of the call to =set-defaults!=:
(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:
;; — 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:
(n/defconfig email-config {:email-behaviour :just-console-for-now})
(defn email-user! [{:keys […] :as email}] (case (:email-behaviour email-config) :just-console-for-now (prn “Would send:” 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}] (email-user! {…})) ;; 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:
(n/defconfig email-config {:email-behaviour (n/switch :live :actually-send-the-email :just-console-for-now)})
(defn email-user! [{:keys […] :as email}] (case (:email-behaviour email-config) :just-console-for-now (prn “Would send:” 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!
Thanks!
** Changes
The Nomad changelog has moved to CHANGES.org.
** License
Copyright © 2013-2018 James Henderson
Distributed under the Eclipse Public License, the same as Clojure.