nomad

by jarohen

jarohen / nomad

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

203 Stars 15 Forks Last release: Not found 209 Commits 37 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

  • 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"}}

+END_SRC

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! {})

+END_SRC

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)))

+END_SRC

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)})

+END_SRC

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}})

+END_SRC

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

set-defaults!
...)

+END_SRC

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}

+END_SRC

** 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="

+END_SRC

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="}})

+END_SRC

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] ...)

+END_SRC

** 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

+END_SRC

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

+END_SRC

** 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.

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.