= Configuration Guide

:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Apache Causeway' is a Spring Boot application, and so is typically configured using an `application.properties` or `application.yml` file.


The configuration can be obtained from a variety of external locations; see the link:https://docs.spring.io/spring-boot/docs/current/reference/html/spring-boot-features.html#boot-features-external-config[Spring Boot] documentation for more details.

TIP: The xref:docs:starters:about.adoc[starter apps] use `application.yml` for configuration that doesn't change between environments, and `config/application.properties` for settings (such as JDBC URL) that does vary.

This chapter describes the configuration properties available to configure an Apache Causeway application.



[#deployment-types]
== Deployment Types

Apache Causeway distinguishes between the application being run in prototyping mode vs running in production mode.
The framework calls this the "deployment type" (corresponding internally to the `DeploymentType` class).

A similar concept appears in the link:https://wicket.apache.org[Apache Wicket] framework (which is the library with which the xref:vw:ROOT:about.adoc[Web UI (Wicket viewer)] is implemented, of course).
Wicket's term is the "configuration".

.Wicket equivalent concepts
[cols="1a,1a", options="header"]
|===

| Apache Causeway +
deployment type
| Apache Wicket library +
configuration

|_prototyping_
|_development_

|_production_
|_deployment_


|===

By default Apache Causeway runs in production mode.
But if configured to run instead in prototyping mode, then any actions xref:refguide:applib:index/annotation/Action.adoc#restrictTo[restricted to] to prototype mode are visible.
In particular, the "Prototyping" menu will appear, containing a number of framework-provided menu services - all restricted to prototyping mode.
For example, menu items to run in xref:testing:fixtures:about.adoc[fixture scripts] are on this menu.

Prototyping mode can be enabled in a number of ways:

* environment variable:
+
[source,bash]
----
export PROTOTYPING=true
----

* `PROTOTYPING` system property
+
[source,bash]
----
-DPROTOTYPING=true
----

* `causeway.deploymentType` system property
+
[source,bash]
----
-Dcauseway.deploymentType=PROTOTYPING
----

It is also possible to explicitly specify production mode:

* `PRODUCTION` system property
+
[source,bash]
----
-DPROTOTYPING=false
----

* `causeway.deploymentType` system property
+
[source,bash]
----
-Dcauseway.deploymentType=PRODUCTION
----

If (by a combination of mechanisms) both prototyping and production modes are specified, then production mode wins.


=== `CausewaySystemEnvironment` domain service

Applications can discover the prototyping mode by injecting the `CausewaySystemEnvironment` service.



[#specifying-components]
== Specifying components

Components are pluggable parts of the Apache Causeway framework that are responsible for the presentation layer, for security, or for persistence.
Each component corresponds to one or more Maven module(s), and are specified using the Spring link:https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/context/annotation/Import.html[@Import] statements from a top-level class annotated with Spring's link:https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/context/annotation/Configuration.html[@Configuration] annotation.
These are then bootstrapped from a link:https://docs.spring.io/spring-boot/docs/current/api/org/springframework/boot/autoconfigure/SpringBootApplication.html[@SpringBootApplication] or link:https://docs.spring.io/spring-boot/docs/current/api/org/springframework/boot/test/context/SpringBootTest.html[@SpringBootTest].

For example, the xref:docs:starters:simpleapp.adoc[simpleapp starter app] project is bootstrapped using `SimpleApp`, annotated with `@SpringBootApplication`:

[source,java]
----
@SpringBootApplication
@Import({
    AppManifest.class,                                          // <.>
})
public class SimpleApp
            extends SpringBootServletInitializer {

    public static void main(String[] args) {
        CausewayPresets.prototyping();                              // <.>
        SpringApplication.run(
                new Class[] { SimpleApp.class }, args);
    }
}
----
<.> references the `AppManifest`, discussed below.
<.> specifies prototyping mode.
This enables actions marked for prototyping to become available, useful during the early stages of development.

In turn, the "app manifest" (the name has been retained from Apache Causeway v1.x) is the top-level Spring `@Configuration`.
It looks like this:

[source,java]
.AppManifest.java
----
@Configuration
@Import({
        CausewayModuleCoreRuntimeServices.class,                    // <.>
        CausewayModuleSecurityShiro.class,                          // <.>
        CausewayModuleJpaEclipselink.class,                         // <.>
        CausewayModuleViewerRestfulObjectsJaxrsResteasy4.class,     // <.>
        CausewayModuleViewerWicketViewer.class,                     // <.>
        ...
        ApplicationModule.class,                                // <.>
        ...
})
public class AppManifest {
}
----

<.> Mandatory - specifies the core of the Apache Causeway framework
<.> Enables the Shiro security mechanism.
There are several security implementations, precisely one must be selected
<.> Enables xref:pjpa:ROOT:about.adoc[JPA/Eclipselink] for persistence.
+
Alternatively, `CausewayModuleJdoDataNucleus5.class` would be specified in order to use xref:pjdo:ROOT:about.adoc[JDO/DataNucleus] instead.
+
Optional (though if omitted then only xref:userguide:fun:overview.adoc#view-models[view models] may be used, with hand-rolled persistence).

<.> Enables the xref:vro:ROOT:about.adoc[REST API (Restful Objects viewer)].
<.> Enables the xref:vw:ROOT:about.adoc[Web UI (Wicket viewer)]
<.> References the application's module(s), in this case just the one, `ApplicationModule`. +

All of the components available are named in the form `CausewayModuleXxx`, so they are easy to discover.

NOTE: Components currently do _not_ use Spring Boot's auto-configuration capabilities.
That means that it's not enough to just add the appropriate Maven module to the classpath; its corresponding `CausewayModuleXxx` must be referenced using an `@Import`.


== Configuration Properties

The core framework has a large number of configuration properties, as do the various xref:about.adoc#specifying-components[components].
So do some of the xref:extensions::about.adoc[extensions] and xref:valuetypes:ROOT:about.adoc[value type] libraries.

The remainder of this guide lists the various configuration properties available, broken out into logical sections.

[#causewayconfiguration-domain-service]
=== CausewayConfiguration domain service

Applications can discover the current configuration properties for the framework (under the `causeway` top-level key) by injecting the `CausewayConfiguration` domain service.
There are similar domain services for xref:pjpa:ROOT:about.adoc[JPA/Eclipselink] (`EclipselinkConfiguration`), xref:pjdo:ROOT:about.adoc[JDO/DataNucleus] (`DatanucleusConfiguration`) and RestEasy (`RestEasyConfiguration`), as used by xref:vro:ROOT:about.adoc[REST API (Restful Objects viewer)].

Applications can also create their own configuration properties file; the xref:docs:starters:simpleapp.adoc[simpleapp] starter app provides an example.



include::application-specific/application-css.adoc[leveloffset=+1]
