Fork me on GitHub

Configuration and modes


By convention Ninja will look for a configuration file at conf/application.conf.

application.conf is a simple properties file with keys and values. “#” is a comment.

# an arbitrary comment demo application

Like any other Ninja file it is encoded in UTF-8. Make sure your editor reads and saves the file in the correct encoding.

Ninja properties can do much more than traditional Java properties. For instance it is possible to reference other properties by their name and combine them.

fullServerName references the previously set values of the keys and will return

Inside your application there are two basic ways to access the properties.

First way is to use NinjaProperties.get(…). You have to inject NinjaProperties first, then you can use all sorts of methods to retrieve properties.

NinjaProperties ninjaProperties;

public void myMethod() {
    String value = ninjaProperties.get("fullServerName")
    ... do even more...

The second way to get properties is to inject them via @Named(“fullServerName”).

/** An arbitrary constructor */
ApplicationController(@Named("fullServerName") String fullServerName) {
    ... do something ...

By the way. And this is really important: Properties are read and managed by the excellent Apache Configurations library. Please refer to their manual for even more information on advanced usage.

Configuring the modes

Ninja uses three predefined modes (test, dev and prod as defined in If no mode is set explicitly Ninja will use the prod mode. That means if you deploy Ninja via a war file to an arbitrary servlet container Ninja will use the prod mode.

Ninja’s SuperDevMode will set the mode to dev. And Ninja’s testcases will use mode test by default.

You can set the modes by setting the Java system property ninja.mode.

On the command line:
> java -Dninja.mode=dev

Or programmatically:
System.setProperty(NinjaConstant.MODE_KEY_NAME, NinjaConstant.MODE_DEV)

Make sure that you set the system property early so that Ninja knows its mode from the very beginning.

These modes are handy if you want to define different properties for different environments. You may want to use database1 when running tests and database2 when developing and database3 when running in production.

Ninja supports that use case by using a mode prefix prior to your property key.   # will be used when no mode is set (or prod)   # will be used when running in prod mode     # will be used when running in dev mode   # will be used when running in test mode

The convention is to use a “%” and the name of the mode followed by “.”.

HTTPS (SSL) support

As of version 5.2.3, Ninja supports basic HTTPS (SSL) in both standalone and SuperDevMode. While other methods of handling SSL in production (e.g. nginx) are highly recommended, its convenient to use Ninja’s builtin support during development, testing, or light production use.

Ninja ships with a self-signed SSL certificate that is configured by default in either dev or test modes. To enable SSL in either dev or test mode you’ll simply need to set the port you’d like to start an HTTPS server on.


This can be accomplished by either adding this to your conf/application.conf configuration file or on the command line when you run Ninja’s maven plugin

mvn ninja:run -Dninja.ssl.port=8443

Ninja supports running both HTTP and HTTPS connectors at the same time. If you’d like to only run HTTPS, simply set ninja.port to -1 to disable it.

ninja.port=-1               # disable clear text http connector
ninja.ssl.port=8443         # enable ssl https connector

The SSL keystore and truststore values can be configured as well. The uri values may either be a classpath resource in the format classpath:resourceName or any other valid Java URL value since under-the-hood URL.openStream() is used. Please note that in dev and test mode the default keystore is classpath:/ninja/standalone/ninja-development.keystore and the default truststore is classpath:/ninja/standalone/ninja-development.truststore


Disabling diagnostic mode

As of version 4.0.7, Ninja features a new diagnostic extension to dev mode where detailed diagnostic error pages are returned from ninja.NinjaDefault rather than the typical Result which pulls a template from system/views.

For example, in versions prior to 4.0.7, if your controller class method threw an Exception then the default behavior of ninja.NinjaDefault was to catch it in the onException method and return a Result using the template views/system/500internalServerError.ftl.html. The default system views are basic and more intended for use in production than during development.

As of version 4.0.7, the default behavior of all the methods in ninja.NinjaDefault are to first check if dev mode is on and if NinjaProperties.areDiagnosticsEnabled() is true. If both are true then a Result is returned with the renderable set to a DiagnosticError instance. Since DiagnosticError implements Renderable – it knows how to render itself to the output stream and it will bypass the TemplateEngine.

Diagnostic mode is disabled automatically in PROD/TEST modes, but it can also be disabled in DEV mode. Simply add the following to your application.conf:


Retaining diagnostic mode if you provide conf.Ninja

If you provide your own conf.Ninja and extend ninja.NinjaDefault, then you will likely lose diagnostic mode for the particular methods you override. You can retain the feature, by calling the super method and conditionally returning its result, rather than your own.

public class Ninja extends NinjaDefault {

    public Result getInternalServerErrorResult(Context context, Exception exception) {
        if (isDiagnosticsEnabled()) {
            return super.getInternalServerErrorResult(context, exception);

        // your impl only active in test/prod or dev (with diagnostic disabled)


Configuring application’s base package

If you’d like to keep all Java code in specific package you can define


In this case you must put your Routes at

and Guice application configuration modules at accordingly.

External configuration for deployment

When running on a server you may want to use a completely different configuration. This can be accomplished by setting a Java system property:

java -Dninja.external.configuration=conf/production.conf

This tells Ninja to load conf/production.conf. It will also load conf/application.conf as usual, but values in conf/production.conf will overwrite values in conf/application.conf.

That way you can manage a production configuration separately from your project. You may want to do this for instance when your server secret should only be available to a certain set of people and not the world. Or if your cloud hoster uses a completely different configuration from prod, test or dev.

Ninja tries to load the file specified in ninja.external.configuration from several locations:

It tries to load in the following order:

  • From a URL.
  • From an absolute file path.
  • From a relative file path.
  • From the user’s home dir.
  • From the classpath.

Ninja uses the excellent Apache Configurations library to do the loading. Please refer to their manual for more information.

Hot-reloading external configuration

By default Ninja does not reload your external configuration. However for some installations it may be very useful to hot-reload this config instead of restarting your application.

java -Dninja.external.reload=true -Dninja.external.configuration=conf/production.conf

This tells Ninja to reload your configuration if it is modified during runtime.

Referencing system properties in configuration files

You can reference system properties inside your configuration files by using the default apache commons configuration syntax:


That’s especially handy when it comes to production credentials that should not be known inside your application code.