12-Factor App Configuration: how to for Java

With application development and deployment changing, we’ll cover how to use 12-factor app configuration for Java applications using Typesafe Config.

Typesafe Config

One of the most used configuration libraries for Java is Typesafe Config. Over the years it has served as a solid and (mostly) unbiased building block for numerous libraries (i.e., MavenCentral lists it as a transitive dependency for 1639 artifacts).

Typesafe Config is the reference implementation for HOCON, Human-Optimized Config Object Notation.” This is a JSON superset flavored with some Java Properties syntax. The HOCON configuration format itself has gotten an impressively wide appreciation and has been adopted and ported to several other programming languages.

12-factor app

The 12-factor app is a best practices methodology for building SaaS apps that maximizes portability, agility, and scaling and minimizes developer on-boarding. It states that the configuration should be injected via environment variables. This is a very convenient way of propagating configuration and most DevOps tools and machinery support it out-of-the-box (eg Docker, Kubernetes).

Current status

Since the beginning, Typesafe Config has supported a basic form of explicit environment variable substitution that lets you define a configuration value as follows:

foo = "bar"
foo = ${?FOO_OVERRIDE}

in this way the returned values for foo in a Java application like:

com.typesafe.config.ConfigFactory.load().resolve().getString("foo")

will default to "bar" but can be overridden by using export FOO_OVERRIDE=baz.

This is quite convenient and does cover most of the normal uses cases, but it has a drawback.

To give DevOps full configurability over an application, in practice, a developer would need to know and manually re-bind in the configuration file all the configuration keys used by the application and all its transitive dependencies.

This starts to become pretty impractical if you are using a highly tunable framework like Akka.

Bridging the gap – Typesafe Config

A perfectly valid and interesting use case for a configuration library is, for example, to tune application’s internals ( such as the ThreadPool used ) and it’s parameters simply injecting a few environment variables and without needing to touch a single line of code.

Typesafe Config was already able to support this feature with the tunable config.strategy, and so we developed Env4Config. Given the widespread nature of this problem, we ended up integrating this proof-tested useful behavior in the core library itself thanks to the support of the Typesafe Config maintainers (especially @havocp ).

Now just by bumping Typesafe config in the classpath to a version > 1.3.4 (NOTE: it stays binary and api compatible! 🙂 ) and enabling this feature using a Java property ( -Dconfig.override_with_env_vars=true ) it’s possible to override ANY configuration that is loaded from the standard chain (e.g. with ConfigFactoy.load) from environment variables without the need for extra, explicit, definitions in the configuration file itself, allowing us to follow the twelve-factor methodology for apps.

Following the previous example, if you have a configuration file:

foo = "bar"

you can override the value of foo by using export CONFIG_FORCE_foo=baz.

More interestingly, if, for example you are using Akka, you can tune the default dispatcher used by your ActorSystem with something like:

export CONFIG_FORCE_akka_actor_default__dispatcher_executor="affinity-pool-executor"

and check and tune the performance of your application without having to touch it.

You may note that the property akka.actor.default-dispatcher.executor is written above as akka_actor_default__dispatcher_executor, the reason is pragmatic: Unfortunately most terminals have known limitations exporting environment variables containing characters like . or - and the environment variable is a mangled version of the Typesafe config key, but it’s a very tiny pitfall for a having access to a greater good!

12 Factor App & Codacy

At Codacy we are pretty excited by this feature. We are already using it in production, and it has drastically reduced the boilerplate in our configuration files while easing parameters modifications for our DevOps department.

About the Author

Andrea is an all-around software developer with hands-on experience in delivering any kind of software system from large scale cloud to embedded devices. He is now working at Codacy as a tech lead.

About Codacy

Codacy is a tool used by thousands of developers and teams to analyze billions of lines of code every day, allowing them to ship better code at scale.