This manual is a work in progress and is currently incomplete.
If you'd like to help improve it, and we hope you do, please see the README.

17 Config

Most applications need some level of configuration. This can be used to specify the correct external resources to use (databases, other services, etc.), tune performance, or otherwise adjust to the requirements of a given environment. ratpack-config provides an easy, flexible mechanism to access configuration information in your Ratpack application.

Configuration data is accessed via object binding using Jackson. Configuration objects provided by Ratpack are intended to be usable out of the box. Configuration data can be loaded from multiple sources, such as YAML files, JSON files, properties files, environment variables and system properties.

17.1 Quick-Start

To get started using ratpack-config:

  1. Add a compile dependency on the module to your build file
  2. Within your RatpackServer definition function, build a ConfigData instance (see class documentation for an example)
  3. Retrieve bound configuration objects from the config data

17.2 Config Sources

ConfigDataSpec provides methods to easily load data from the most common sources.

Commonly used file formats can be used via the yaml, json and props methods. The provided signatures can be used to load data from local files (String or Path), over the network (URL), from the classpath (use Resources.getResource(String) to get a URL), or anywhere else you can treat as a ByteSource. Additionally, you can load data from non-file sources such as Maps/Properties objects (particularly useful for default values), system properties, and environment variables. If additional flexibility is needed, you can provide your own ConfigSource implementation.

17.2.1 Flat Config Sources

Environment variables, Properties, and Maps are flat data structures, whereas the binding model used by ratpack-config is hierarchical. To bridge this gap, these config source implementations apply conventions to allow for the flat key-value pairs to be transformed into useful data.

17.2.1.1 Environment Variables

The default environment variable config source uses the following rules:

If custom environment parsing is needed, you can supply an EnvironmentParser implementation.

17.2.1.2 Properties/Maps

The default Properties/Map config source uses the following rules:

TODO: example

17.3 TODO