Dropwizard Template Config

A Dropwizard Bundle that allows you to write your config.yaml as a Freemarker template. This is especially useful when you need to access environment variables or system properties. In fact, this project is the successor to the fabulous dropwizard-environment-config plugin.

Setup

First add the dependency to your POM:

<dependency>
    <groupId>de.thomaskrille</groupId>
    <artifactId>dropwizard-template-config</artifactId>
    <version>1.5.0</version>
</dependency>

Your project is assumed to separately pull in dropwizard-core version 0.7.1 or newer. Compatibility has been tested through Dropwizard 1.0.0.

To enable, simply add the TemplateConfigBundle to the Bootstrap object in your initialize method:

@Override
public void initialize(final Bootstrap<Configuration> bootstrap) {
    ...
    bootstrap.addBundle(new TemplateConfigBundle());
    ...
}

You can configure the bundle by passing an instance of TemplateConfigBundleConfiguration to the constructor:

@Override
public void initialize(final Bootstrap<Configuration> bootstrap) {
    ...
    bootstrap.addBundle(new TemplateConfigBundle(
            new TemplateConfigBundleConfiguration().charset(Charsets.US_ASCII)
    ));
    ...
}

You can add your own variables to the template by adding your own implementations of the TemplateConfigProvider to the constructor:

@Override
public void initialize(final Bootstrap<Configuration> bootstrap) {
    ...
    bootstrap.addBundle(new TemplateConfigBundle(
        new TemplateConfigBundleConfiguration()
            .addCustomProvider(myCustomProvider1)
            .addCustomProvider(myCustomProvider2)
    ));
    ...
}

Look at TemplateConfigBundleConfiguration's javadoc to see all available options.

Heads up: The Bundle gets the content of the config.yaml by wrapping any previously defined io.dropwizard.configuration.ConfigurationSourceProvider. So you must set any custom ConfigurationSourceProvider before adding this Bundle to the Bootstrap.

Quickstart

Environment variables and system properties can be specified in config.yaml by using the following Freemarker magic:

server:
  type: simple
  connector:
    type: http
    # replacing environment variables
    port: ${PORT}
logging:
  # with default values too
  level: ${LOG_LEVEL!'WARN'}
  appenders:
    # system properties also work
    - type: ${log_appender!'console'}

See Freemarker's Template Author's Guide for more information on how to write templates.

Tutorial

Using this bundle you can write your config.yaml as Freemarker template. Let's start with a simple example: replacing environment variables. For all the Heroku users out there, we will try to use Heroku's environment variables for the examples. Let's focus on a single piece of the configuration shown in the Quickstart:

server:
  type: simple
  connector:
    type: http
    port: ${PORT}

You can specify a default value in case the environment variable is missing. This is useful for local tests on your development machine:

server:
  type: simple
  connector:
    type: http
    port: ${PORT!8080}

Default values are separated from the variable name by a ! and follow more or less the well-known Java syntax for scalars. If there is no default value for a missing variable an exception will be thrown by Freemarker and wrapped in a RuntimeException. Java system properties (the contents of System.getProperties()) are available, too:

server:
  type: simple
  connector:
    type: http
    port: ${http_port}

There are some limitations to the variables and properties you can access through these top-level variables. For one, environment variables and system properties with the same name will collide (environment variables will mask system properties in this case). For another, names containing [characters such as . and - that have special meaning to Freemarker] (http://freemarker.org/docs/dgui_template_exp.html#dgui_template_exp_var_toplevel) won't be available. To alleviate these problems, this bundle also provides Maps for the environment (env) and system properties (sys) at the top level:

# Use `sys` to access a system property masked by an environment variable
port: ${sys.http_port}

# Use bracket notation to access a system property with a `.` in its name
port: ${sys['my_app.http.port']}

# Names with a dash (`-`) can be accessed via brackets or backslash
port: ${sys['http-port']}
port: ${http\-port}

You can output variables inline in values. This is helpful to specify the database connection:

database:
  driverClass: org.postgresql.Driver
  user: ${DB_USER}
  password: ${DB_PASSWORD}
  url: jdbc:postgresql://${DB_HOST!'localhost'}:${DB_PORT}/my-app-db

In fact, you can output anything anywhere, because Freemarker doesn't know anything about YAML:

#
# Given the following environment:
#
# SERVER_TYPE_LINE='type: simple'
# SERVER_CONNECTOR_TYPE_LINE='type: http'
#
server:
  ${SERVER_TYPE_LINE}
  connector:
    ${SERVER_CONNECTOR_TYPE_LINE}
    port: 8080

Be careful though, not to mess up YAML's data structure. Of course, you can use any other Freemarker features beyond simple variable interpolation:

# Use with:
#
# ENABLE_SSL=true
# SSL_PORT=8443 (optional)
# SSL_KEYSTORE_PATH=/etc/my-app/keystore
# SSL_KEYSTORE_PASS=secret
#
# or
#
# ENABLE_SSL=false
#
server:
  applicationConnectors:
    - type: http
      port: ${PORT!8080}
<#if ENABLE_SSL == 'true'>
    - type: https
      port: ${SSL_PORT!8443}
      keyStorePath: ${SSL_KEYSTORE_PATH}
      keyStorePassword: ${SSL_KEYSTORE_PASS}
</#if>

The previous example conditionally enables HTTPS if the environment variable ENABLE_SSL is true. Comments are available too:

server:
  applicationConnectors:
    - type: http
      port: ${PORT!8080}
<#-- Un-comment to enable HTTPS
    - type: https
      port: ${SSL_PORT!8443}
      keyStorePath: ${SSL_KEYSTORE_PATH}
      keyStorePassword: ${SSL_KEYSTORE_PASS}
-->

Comments are writen between the <#-- --> Freemarker tags. They can span multiple lines. Another advanced use case might be introducing configuration profiles that can be switched by using an environment variable like this:

logging:
<#if PROFILE == 'production'>
  level: WARN
  loggers:
    com.example.my_app: INFO
    org.hibernate.SQL: OFF
  appenders:
    - type: syslog
      host: localhost
      facility: local0
<#elseif PROFILE == 'development'>
  level: INFO
  loggers:
    com.example.my_app: DEBUG
    org.hibernate.SQL: DEBUG
  appenders:
    - type: console
</#if>

You can include snippets from external config files via the <#include> tag. For this to work, you have to set an include directory based either on a resource in the classpath:

@Override
public void initialize(final Bootstrap<Configuration> bootstrap) {
    ...
    bootstrap.addBundle(new TemplateConfigBundle(
            new TemplateConfigBundleConfiguration().resourceIncludePath("/config")
    ));
    ...
}

or on the local filesystem:

@Override
public void initialize(final Bootstrap<Configuration> bootstrap) {
    ...
    bootstrap.addBundle(new TemplateConfigBundle(
            new TemplateConfigBundleConfiguration().fileIncludePath("./config")
    ));
    ...
}

Feel free to use sub-folders to organize your configurations. While the argument to fileIncludePath may be relative to the current working directory or absolute, the argument to resourceIncludePath will always be made absolute by prepending a slash (/) if not present. You can then include configuration templates from other files. To extract the database config, for example, create a config like this:

server:
  type: simple
  connector:
    type: http
    port: 8080

<#include "database.yaml">

logging:
  level: WARN

The database.yaml looks like this:

database:
  driverClass: org.postgresql.Driver
  user: my-app
  password: secret
  url: jdbc:postgresql://localhost:5432/my-app-db

The result will look like this:

server:
  type: simple
  connector:
    type: http
    port: 8080

database:
  driverClass: org.postgresql.Driver
  user: my-app
  password: secret
  url: jdbc:postgresql://localhost:5432/my-app-db

logging:
  level: WARN

Of course, you can also use any templating feature in the included file, like:

• accessing environment variables
• using conditionals
• including additional files

If you're not seeing the behavior you expect, it can be useful to inspect the rendered text of your template. Since 1.3.0, you can provide an outputPath to which the bundle will write the filled-out text of the config before passing it on to Dropwizard:

@Override
public void initialize(final Bootstrap<Configuration> bootstrap) {
    ...
    bootstrap.addBundle(new TemplateConfigBundle(
            new TemplateConfigBundleConfiguration().outputPath("/tmp/config.yml")
    ));
    ...
}

Be careful to not overuse all this stuff. In the end, a configuration file should stay as simple as possible and be easily readable. Extensively using advanced Freemarker features might get in the way of this principle.

See Freemarker's Template Author's Guide for more information on how to write templates.

Migration from Dropwizard Environment Config

TODO: write me!

Copyright Notice

This project is licensed under the Apache License, Version 2.0, January 2004, and uses the following 3rd party software:

• Dropwizard

  Copyright 2010-2015, Coda Hale, Yammer Inc.

• Freemarker

  Copyright 2002-2015, The FreeMarker Project, Attila Szegedi, Daniel Dekany, Jonathan Revusky

See LICENSE-3RD-PARTY and NOTICE-3RD-PARTY for the individual 3rd parties.