Home Education 12-Factor App Configuration: how to for Java

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:


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.


Please enter your comment!
Please enter your name here

Subscribe to our newsletter

To be updated with all the latest news, offers and special announcements.

Recent posts

OWASP Top 10 vulnerabilities and how Codacy helps to address them

In today’s modern, digitized world, security is more important than ever to respond to growing threats. Every web application comes with system vulnerabilities, and...

2020, It’s a wrap! 🎊

Looking back at 2020, it has been a year of change and innovation for Codacy. We became fully remote and will continue to be,...

Migrating to React: Typed named routes in react-router and Typescript

INTRODUCTION If you’re a regular user of Codacy, you might have noticed a few changes over the course of this year on some pages. We’re...

Introducing Pulse to help companies achieve elite engineering performance

At Codacy, we envision a future where everyone can impact the world by crafting complex software with confidence and focus at the speed of...

First QA Engineer in a Startup

This is the story of how I joined a startup as the first QA Engineer in the company.  My name is Bruno Medley, I'm a...