AppConfig

AppConfig is a configuration library which provides properties for applications deployed to different environments. For example, your local file storage is located at /home/joe/project1/files in a development environment (laptop), but in production it is located on the NFS: /opt/project1/files.

AppConfig makes it easy to configure multiple property files, one per environment and load just one depending what environment the application is running on.

As such, you may have a property file development.properties with content:

file_storage=/home/joe/project1/files

while the production.properties file will include:

file_storage=/opt/project1/files

Reading properties

First, import a static import AppConfig.p(...) method:

import static org.javalite.app_config.AppConfig.p;

then, simply call it as: p(..) in places where you need to inject a property:

String name = p("name");

Property substitution

AppConfig allows a property substitution to make it possible to refactor large property files by specifying a repeating value once.

If your property file has these properties:

first.name=John
phrase= And the name is ${first.name}

than this code will print And the name is John:

System.out.println(p("phrase"));

Note: The order of properties does not matter.

Setting up for multiple environments

AppConfig allows configuration of applications that is specific for different deployment environments. Applications have environment-specific files, whose names follow this pattern: environment.properties, where environment is a name of a deployment environment, such as development, staging, production, etc.

You can also provide a global file, properties from which will be loaded in all environments: global.properties.

In all cases the files need to be on the classpath under directory/package /app_config.

Environment-specific file will have an environment part of the file name match to an environment variable called ACTIVE_ENV. Such configuration is easy to achieve in Unix shell:

export ACTIVE_ENV=test

A typical file structure

/app_config
        |
        +--global.properties
        |
        +--development.properties
        |
        +--staging.properties
        |
        +--production.properties
        

If you are using Maven, then the location will be: src/main/resources/app_config.

Global property file will always be loaded, while others will be loaded depending on the value of `ACTIVE_ENV`` environment variable.

If environment variable ACTIVE_ENV is missing, AppConfig defaults to environment development.

System property override

You can also provide an environment as a system property app_config.properties.

Here is an example (add this to the startup script for your app):

-Dapp_config.properties=/opt/project1/production.properties

The app_config.properties system property points to a file specific to that computer (local box, server, etc.). If a specific property is provided in the properties file loaded on classpath, and the same property is also found in the file app_config.properties, then the value loaded from a local file overrides the one loaded from classpath.

Environment Variables Override

Production passwords and other sensitive data are often supplied as environment variables, especially in contenerized environments.

JavaLite allows any property looked up from the AppConfig be overridden by a matching system environment variable.

Environment Variables Naming Mapping

While Java property names allow for dots, dashes and other characters, the system environment variables typically do not. In addition, the Java property names are usually lowercase, but the environment variables use upper case.

When AppConfig loads a Java property, it looks for a corresponding system environment variable that shadows it, and performes the following steps:

1. Converts dots to underscores: . -> _
2. Converts dashes to underscores: - -> _
3. Converts letters to upper case: aBcDe -> ABCDE

Example: Java property name can be:

some.property.name.1

while the corresponding environment variable should be:

SOME_PROPERTY_NAME_1

AppConfig reads SOME_PROPERTY_NAME_1 and convert it to some.property.name.1.

For instance: there exists an env var:

export DATABASE_USERNAME=john_doe

and there exists a property:

database.username = mary_doe

so, the code:

AppConfig.p("database.username")

will yield john_doe.

Watch out for log lines like: Duplicate property defined.... in case of a duplicate value override. It will tell you exactly where the new value is coming from and which property source is overridden with it.