Documentation Home
Changelog

Runtime Environment Configuration

Property files are added to the Spring Environment as PropertySources via the BroadleafEnvironmentConfiguringApplicationListener.java. The priority hierarchy for this merge is as follows, with latter properties overriding earlier ones. Note that we are using production as the environment for these examples -- it would obviously change if the current environment was different.

  • Broadleaf defined properties
  • classpath:/runtime-properties/common-shared.properties (usually in the core project shared between all other deployable projects)
  • classpath:/runtime-properties/production-shared.properties (usually in the core project shared between all other deployable projects)
  • classpath:/runtime-properties/common.properties from the specific deployed application
  • classpath:/runtime-properties/production.properties from the specific deployed application
  • Properties defined in the file specified by runtime JVM argument "property-shared-override"
  • Properties defined in the file specified by runtime JVM argument "property-override"
  • All other property sources added by Spring by default (e.g. OS environment variables)

The BroadleafEnvironmentConfiguringApplicationListener.java is added by default in Spring Boot projects. If you are not using Spring Boot, this must be added as a contextInitializerClass in your web.xml:

<context-param>
    <param-name>contextInitializerClasses</param-name>
    <param-value>org.broadleafcommerce.common.config.BroadleafEnvironmentConfiguringApplicationListener</param-value>
</context-param>

Setting the Active Environment

Starting with Broadleaf 5.2.0-GA, you can change the active Broadleaf environment by using Spring Profiles with the following JVM argument and a comma-separated value of the profiles that you want to activate:

-Dspring.profiles.active=production

If no profile is specified, the default environment is default (development is also added as a default environnment for older versions of Broadleaf). This value can be modified by specifying a JVM argument of -Dspring.profiles.default.

Spring Boot

If you are using Spring Boot then you have many options for external confiuration. The above configuration with the runtime-properties folder is added last in the chain of considered properties, so all boot-configured property sources take precedence.

The runtime-properties folder is not required and you can instead move your existing properties to application- variants.

Modifying property sources

Modifying Broadleaf PropertySources

See BroadleafEnvironmentConfiguringApplicationListener.java for the names of PropertySources that are added to the Environment. These can be retrieved by injecting the Environment into your own Spring component like:

CompositePropertySource profileAwareSources = env.getPropertySources().get(BroadleafEnvironmentConfiguringApplicationListener.PROFILE_AWARE_SOURCES_NAME);

All of the individual property sources are added to the environment are CompositePropertySources.

Adding your own externalized PropertySource

If you want to use your own externalized property source you must write your own ApplicationContextInitializer and reference it in your web.xml:

<context-param>
    <param-name>contextInitializerClasses</param-name>
    <param-value>com.mycompany.config.MyCustomApplicationContextInitializer</param-value>
</context-param>

From the overridden initialize() method, you can add property sources to the given applicationContext.getEnvironment().

Spring Boot

Spring Boot has an explicit hook point for modifying the environment. Implement the EnvironmentPostProcessor and add it to src/main/resources/META-INF/spring.factories:

org.springframework.boot.env.EnvironmentPostProcessor=com.mycompany.environment.MyCustomEnvironmemntPostProcessor

Adding property sources at any later date (e.g. injecting the Environment) will not not work with @Value replacement as these properties are replaced very early in the Spring lifecycle

Environment-specific Property Overrides

System property

Any JVM-specified -D argument will override application specific properties. For example, to disable resource minification from Tomcat:

export CATALINA_OPTS="... -Dminify.enabled=false"

OS environment property

Any OS-specific runtime property will override user-defined properties. The format of environment variables are all uppercase and instead of dots use underscores. Example of disabling resource minification:

export MINIFY_ENABLED=false

Property overrides file

Additionally, it's possible to specify computer specific overrides for both the application level and shared level. This is controlled by the following two JVM args:

-Dproperty-shared-override=/some/path/computer1-shared.properties
-Dproperty-override=/some/path/computer1-admin.properties

In this scenario, regardless of the environment that the application starts up under, any properties specified in computer1-shared.properties would overwrite properties from the WAR. Additionally, you could further overwrite properties with computer1-admin.properties. For example, a common use case for this could be a developer that wanted to use MySQL for their local environment. They could create developername-shared.properties, and specify the appropriate MySQL dialects in that file. Another use case would be the ability to maintain secret application keys directly on the application servers and not checked into source control.