How to implement 12-factor a configuration for Java


Monorepo with Static Code Analysis

Monorepo is short for monorepository. With it, code for many projects is stored in the same repository. I like to use...

Automated Code Review Benefits: Webinar

Our sales team member Matt Kohler recently gave a presentation on code review benefits with his "Benefits of Automated Code Review" webinar....

Codacy at DevOps Jenkins World

Gain key insight on the state of DevOps and come together with the global Jenkins community... The Codacy team...

Codacy announces raising $7.7M in funding

Today we’re excited to make a funding announcement.  We have raised $7.7M in funding.  Join Capital along with existing investors EQT Ventures, Armilar Venture...

DNS problems scaling with Kubernetes

Here at Codacy, everyone has been working really hard in the last few months to move all of our services to Kubernetes. And it...

How to write legible QA tests

Our quality-minded software engineer shares best practices for writing legible QA tests.

With application development and deployment changing, this post will cover how to apply the 12-factor app methodology to Java applications using 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,” 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 (Docker, K8s, etc.).

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:


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 an highly tunable framework like Akka.

Bridging the gap

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

That’s all!

I can say that here in 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 Andrea

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.