Configuration

Configuration #

Configuration of the application is done via HOCON configuration files in the src/main/resources and src/test/resources directories for production code and test code respectively.

Providing your own configuration #

In the starter project, you can provide your own configuration in the src/main/resources/application.conf file.

Overriding configuration properties #

According to the official documentation, configuration properties are read from the following sources (in order of priority):

  1. System properties (-D command line arguments)
  2. application.conf files on the classpath
  3. application.json files on the classpath
  4. application.properties files on the classpath
  5. reference.conf that ships with the library

Configuration values are overridden by redefining the same value in any of the places listed above. For example, to change the app.http.port value, you can set it as a system property on the command line:

java -Dapp.http.port=8080 -jar myapp.jar

Or you can declare it in your own application.conf file:

# src/main/resources/application.conf
app.http.port = 8080

Choosing a configuration file #

When you declare your configuration in application.conf, this file will be read automatically as per the rules of precedence outlined in the previous section. However, you may want to specify different settings based on the application’s runtime environment. To do this, you set the config.resource system property to the location of your configuration file.

For example, to instruct the framework to load the settings stored in src/main/resources/production.conf, use -DConfig.resource=production.conf when starting the application from the command line.

Managing Secrets #

Sometimes you may not want to hard-code sensitive information such as API keys and passwords in your configuration file. In production, you can set this sensitive information as environment variables which can be substituted in the configuration file as follows:

include "application.conf"

api_key = ${SECRET_KEY}

In development, however, this environment variable probably won’t exist, in which case you might resort to hardcoding it in your application.conf file. The problem arises when code has to be checked in to version control and/or shared with others. This is a serious security risk.

You can also create these environment variables in your editor or your local machine, but they can become difficult to manage, moreso if you work on multiple devices.

For these and other reasons, you can create a env.properties file in the root of your project and place all sensitive or environment-specific information in there:

SECRET_KEY=<super_secret_key>

It is important that you do not check this file into version control.

When your configuration is loaded, it will take all of the variables in this file and set them as JVM properties.

JSON Configuration #

To configure the JSON mapper, inject the com.fasterxml.jackson.databind.ObjectMapper singleton into your main WebMvcConfiguration. All components of the framework use this singleton, so any changes you apply to it will be applied globally.

Check out the FasterXML Documentation to learn about what options are available to you.

Accessing configuration at runtime #

The Settings class holds all of the configuration details in your *.conf files. This class can be injected into your domain objects using the @Inject annotation or by using load(Settings).

For more information about load() and the @Inject annotation, see dependency injection.

Core framework configuration #

This section serves as a reference for all of the configuration properties available for all of the core components of the framework.

diego {
  # The default date format used throughout the application.
  dateFormat: "yyyy-MM-dd"
  # Set the application runtime environment (development, production or <custom>)
  env: "development"
  # Context resource base. Everything including the static assets directory will be relative to this location
  resourceBase: "src/main/resources"
  # The base URL of the application
  baseUrl: "http://localhost:"${app.http.port}"/"
  
  # HTTP configuration
  http {
    # Set the HTTP port
    port: 8080
    # Set the max file size for uploads
    maxFileSize: "5MB"
    # Set the max request body size
    maxBodySize: "10MB"
  }
  
  # Template engine configuation
  templates {
    engine: "diego.templates.freemarker.FreemarkerModule"
  }
  
  # Configure the default static asset handler
  assets {
    # The URL prefix
    path: "/public/*"
    # Caching is disabled by default. You should turn it on in production.
    cache: false
    # Sets the Cache-Control header. In the form of a duration such as 1h (1 hour), 30d (30 days), etc.
    maxAge: "1h"
  }
  
  # Settings for the live reload compiler
  compiler {
    src: "src/main/groovy"
    out: "build/classes/groovy/main"
  }
  
  # Authorization provider
  security {
    authorizationProvider: "diego.security.DefaultAuthorizationProvider"
  }
}

Next: Experimental features