A typeclass-based library for reading in configuration values from multiple sources, attempting to be simple, avoid unecessarily complex types, and be able to track where each value came from.

This library models configuration files as a list of configuration Keys, for which values can be retrieved from generic sources, such as environment variables, a program's cli arguments, or a yaml (or json, etc.) file.

As a simple example, assume a program interacting with some API. We want it to read the API's base url (falling back to a default value if it is not given) and an API key (and error out if it is missing) from its config:

data ProgramConfig =
  { configBaseUrl :: URL
  , configApiKey  :: Text
  }

Then we can write an appropriate instance of Config for it:

instance Config ProgramConfig where
  readConfig = ProgramConfig
    <$> readValue "http://example.org" [key|baseUrl|]
    <*> readRequiredValue [key|apiKey|]

Config is an instance of Applicative. With the ApplicativeDo language extension enabled, the above can be equivalently written as:

instance Config ProgramConfig where
  readConfig = do
    configBaseUrl <- readValue "http://example.org" [key|baseUrl|]
    configApiKey <- readRequiredValue [key|apiKey|]
    pure (ProgramConfig {..})

Note that Config is not a Monad, so we cannot inspect the config values here, or make the reading of further keys depend on the value of earlier ones. This is to enable introspection-like uses as in configKeysOf.

To read our config we must provide a non-empty list of sources. Functions to construct these live in the Conftrack.Source.* modules; here we use mkYamlFileSource and mkEnvSource (from Conftrac.Source.Yaml and Conftrack.Source.Env respectively) to read values from either a yaml file or environment variables:

main = do
  result <- runFetchConfig
               [ mkEnvSource "CONFTRACK"
               , mkYamlFileSource [path|./config.yaml|]
               ]
  case result of
    Left _ -> ..
    Right (config, origins, warnings) -> ..

Now we can read in a config file like

baseUrl: http://localhost/api/v1
apiKey: very-very-secret

or from environment variables

CONFTRACK_BASEURL=http://localhost/api/v1
CONFTRACK_APIKEY=very-very-secret

Of course, sources can be mixed: Perhaps we do not want to have our program's api key inside the configuration file. Then we can simply omit it there and provide it via the CONFTRACK_APIKEY environment variable instead.

Multiple sources

The order of sources given to runFetchConfig matters: values given in earlier sources shadow values of the same key in all following sources.

Thus even if we have

apiKey: will-not-be-used

in our config.yaml file, it will be ignored if the CONFTRACK_APIKEY environment variable also has a value.

Keeping track of things

Conftrack is written to always keep track of the configuration values it reads. In particular, it is intended to avoid frustrating questions of the kind "I have clearly set this config key in the file, why does my software not use it?".

This is reflected in runFetchConfig's return type: if it does not produce an error, it will not only return a set of config values, but also a map of Origins and a list of Warnings indicating likely misconfiguration:

main = do
  result <- runFetchConfig
               [ mkEnvSource "CONFTRACK"
               , mkYamlFileSource [path|./config.yaml|]
               ]
  case result of
    Left _ -> ..
    Right (config, origins, warnings) -> do
      printConfigOrigins origins
      ...

May print something like this:

Environment variable CONFTRACK_APIKEY
  apiKey = "very-very-secret"
YAML file ./config.yaml
  baseUrl = "http://localhost/api/v1"

It is recommended that programs making use of conftrack include a --show-config option (or a similar method of introspection) to help in debugging such cases.