[[howto.properties-and-configuration]]
== Properties and Configuration
This section includes topics about setting and reading properties and configuration settings and their interaction with Spring Boot applications.



[[howto.properties-and-configuration.expand-properties]]
=== Automatically Expand Properties at Build Time
Rather than hardcoding some properties that are also specified in your project's build configuration, you can automatically expand them by instead using the existing build configuration.
This is possible in both Maven and Gradle.



[[howto.properties-and-configuration.expand-properties.maven]]
==== Automatic Property Expansion Using Maven
You can automatically expand properties from the Maven project by using resource filtering.
If you use the `spring-boot-starter-parent`, you can then refer to your Maven '`project properties`' with `@..@` placeholders, as shown in the following example:

[source,yaml,indent=0,subs="verbatim",configblocks]
----
	app:
	  encoding: "@project.build.sourceEncoding@"
	  java:
	    version: "@java.version@"
----

NOTE: Only production configuration is filtered that way (in other words, no filtering is applied on `src/test/resources`).

TIP: If you enable the `addResources` flag, the `spring-boot:run` goal can add `src/main/resources` directly to the classpath (for hot reloading purposes).
Doing so circumvents the resource filtering and this feature.
Instead, you can use the `exec:java` goal or customize the plugin's configuration.
See the {spring-boot-maven-plugin-docs}#getting-started[plugin usage page] for more details.

If you do not use the starter parent, you need to include the following  element inside the `<build/>` element of your `pom.xml`:

[source,xml,indent=0,subs="verbatim"]
----
	<resources>
		<resource>
			<directory>src/main/resources</directory>
			<filtering>true</filtering>
		</resource>
	</resources>
----

You also need to include the following element inside `<plugins/>`:

[source,xml,indent=0,subs="verbatim"]
----
	<plugin>
		<groupId>org.apache.maven.plugins</groupId>
		<artifactId>maven-resources-plugin</artifactId>
		<version>2.7</version>
		<configuration>
			<delimiters>
				<delimiter>@</delimiter>
			</delimiters>
			<useDefaultDelimiters>false</useDefaultDelimiters>
		</configuration>
	</plugin>
----

NOTE: The `useDefaultDelimiters` property is important if you use standard Spring placeholders (such as `$\{placeholder}`) in your configuration.
If that property is not set to `false`, these may be expanded by the build.



[[howto.properties-and-configuration.expand-properties.gradle]]
==== Automatic Property Expansion Using Gradle
You can automatically expand properties from the Gradle project by configuring the Java plugin's `processResources` task to do so, as shown in the following example:

[source,gradle,indent=0,subs="verbatim"]
----
	tasks.named('processResources') {
		expand(project.properties)
	}
----

You can then refer to your Gradle project's properties by using placeholders, as shown in the following example:

[source,yaml,indent=0,subs="verbatim",configblocks]
----
	app:
	  name: "${name}"
	  description: "${description}"
----

NOTE: Gradle's `expand` method uses Groovy's `SimpleTemplateEngine`, which transforms `${..}` tokens.
The `${..}` style conflicts with Spring's own property placeholder mechanism.
To use Spring property placeholders together with automatic expansion, escape the Spring property placeholders as follows: `\${..}`.



[[howto.properties-and-configuration.externalize-configuration]]
=== Externalize the Configuration of SpringApplication
A `SpringApplication` has bean property setters, so you can use its Java API as you create the application to modify its behavior.
Alternatively, you can externalize the configuration by setting properties in `+spring.main.*+`.
For example, in `application.properties`, you might have the following settings:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	spring:
	  main:
	    web-application-type: "none"
	    banner-mode: "off"
----

Then the Spring Boot banner is not printed on startup, and the application is not starting an embedded web server.

Properties defined in external configuration override and replace the values specified with the Java API, with the notable exception of the primary sources.
Primary sources are those provided to the `SpringApplication` constructor:

include::code:application/MyApplication[]

Or to `sources(...)` method of a `SpringApplicationBuilder`:

include::code:builder/MyApplication[]

Given the examples above, if we have the following configuration:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	spring:
	  main:
	    sources: "com.example.MyDatabaseConfig,com.example.MyJmsConfig"
	    banner-mode: "console"
----

The actual application will show the banner (as overridden by configuration) and uses three sources for the `ApplicationContext`.
The application sources are:

. `MyApplication` (from the code)
. `MyDatabaseConfig` (from the external config)
. `MyJmsConfig`(from the external config)



[[howto.properties-and-configuration.external-properties-location]]
=== Change the Location of External Properties of an Application
By default, properties from different sources are added to the Spring `Environment` in a defined order (see "`<<features#features.external-config>>`" in the '`Spring Boot features`' section for the exact order).

You can also provide the following System properties (or environment variables) to change the behavior:

* configprop:spring.config.name[] (configprop:spring.config.name[format=envvar]): Defaults to `application` as the root of the file name.
* configprop:spring.config.location[] (configprop:spring.config.location[format=envvar]): The file to load (such as a classpath resource or a URL).
  A separate `Environment` property source is set up for this document and it can be overridden by system properties, environment variables, or the command line.

No matter what you set in the environment, Spring Boot always loads `application.properties` as described above.
By default, if YAML is used, then files with the '`.yaml`' and '`.yml`' extension are also added to the list.

TIP: If you want detailed information about the files that are being loaded you can <<features#features.logging.log-levels, set the logging level>> of `org.springframework.boot.context.config` to `trace`.



[[howto.properties-and-configuration.short-command-line-arguments]]
=== Use '`Short`' Command Line Arguments
Some people like to use (for example) `--port=9000` instead of `--server.port=9000` to set configuration properties on the command line.
You can enable this behavior by using placeholders in `application.properties`, as shown in the following example:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	server:
	  port: "${port:8080}"
----

TIP: If you inherit from the `spring-boot-starter-parent` POM, the default filter token of the `maven-resources-plugins` has been changed from `+${*}+` to `@` (that is, `@maven.token@` instead of `${maven.token}`) to prevent conflicts with Spring-style placeholders.
If you have enabled Maven filtering for the `application.properties` directly, you may want to also change the default filter token to use https://maven.apache.org/plugins/maven-resources-plugin/resources-mojo.html#delimiters[other delimiters].

NOTE: In this specific case, the port binding works in a PaaS environment such as Heroku or Cloud Foundry.
In those two platforms, the `PORT` environment variable is set automatically and Spring can bind to capitalized synonyms for `Environment` properties.



[[howto.properties-and-configuration.yaml]]
=== Use YAML for External Properties
YAML is a superset of JSON and, as such, is a convenient syntax for storing external properties in a hierarchical format, as shown in the following example:

[source,yaml,indent=0,subs="verbatim"]
----
	spring:
	  application:
	    name: "cruncher"
	  datasource:
	    driver-class-name: "com.mysql.jdbc.Driver"
	    url: "jdbc:mysql://localhost/test"
	server:
	  port: 9000
----

Create a file called `application.yaml` and put it in the root of your classpath.
Then add `snakeyaml` to your dependencies (Maven coordinates `org.yaml:snakeyaml`, already included if you use the `spring-boot-starter`).
A YAML file is parsed to a Java `Map<String,Object>` (like a JSON object), and Spring Boot flattens the map so that it is one level deep and has period-separated keys, as many people are used to with `Properties` files in Java.

The preceding example YAML corresponds to the following `application.properties` file:

[source,properties,indent=0,subs="verbatim",configprops]
----
	spring.application.name=cruncher
	spring.datasource.driver-class-name=com.mysql.jdbc.Driver
	spring.datasource.url=jdbc:mysql://localhost/test
	server.port=9000
----

See "`<<features#features.external-config.yaml>>`" in the '`Spring Boot features`' section for more information about YAML.



[[howto.properties-and-configuration.set-active-spring-profiles]]
=== Set the Active Spring Profiles
The Spring `Environment` has an API for this, but you would normally set a System property (configprop:spring.profiles.active[]) or an OS environment variable (configprop:spring.profiles.active[format=envvar]).
Also, you can launch your application with a `-D` argument (remember to put it before the main class or jar archive), as follows:

[source,shell,indent=0,subs="verbatim"]
----
	$ java -jar -Dspring.profiles.active=production demo-0.0.1-SNAPSHOT.jar
----

In Spring Boot, you can also set the active profile in `application.properties`, as shown in the following example:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	spring:
	  profiles:
	    active: "production"
----

A value set this way is replaced by the System property or environment variable setting but not by the `SpringApplicationBuilder.profiles()` method.
Thus, the latter Java API can be used to augment the profiles without changing the defaults.

See "`<<features#features.profiles>>`" in the "`Spring Boot features`" section for more information.



[[howto.properties-and-configuration.set-default-spring-profile-name]]
=== Set the Default Profile Name
The default profile is a profile that is enabled if no profile is active.
By default, the name of the default profile is `default`, but it could be changed using a System property (configprop:spring.profiles.default[]) or an OS environment variable (configprop:spring.profiles.default[format=envvar]).

In Spring Boot, you can also set the default profile name in `application.properties`, as shown in the following example:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	spring:
	  profiles:
	    default: "dev"
----

See "`<<features#features.profiles>>`" in the "`Spring Boot features`" section for more information.



[[howto.properties-and-configuration.change-configuration-depending-on-the-environment]]
=== Change Configuration Depending on the Environment
Spring Boot supports multi-document YAML and Properties files (see <<features#features.external-config.files.multi-document>> for details) which can be activated conditionally based on the active profiles.

If a document contains a `spring.config.activate.on-profile` key, then the profiles value (a comma-separated list of profiles or a profile expression) is fed into the Spring `Environment.acceptsProfiles()` method.
If the profile expression matches then that document is included in the final merge (otherwise, it is not), as shown in the following example:

[source,yaml,indent=0,subs="verbatim,attributes",configprops,configblocks]
----
	server:
	  port: 9000
	---
	spring:
	  config:
	    activate:
	      on-profile: "development"
	server:
	  port: 9001
	---
	spring:
	  config:
	    activate:
	      on-profile: "production"
	server:
	  port: 0
----

In the preceding example, the default port is 9000.
However, if the Spring profile called '`development`' is active, then the port is 9001.
If '`production`' is active, then the port is 0.

NOTE: The documents are merged in the order in which they are encountered.
Later values override earlier values.



[[howto.properties-and-configuration.discover-build-in-options-for-external-properties]]
=== Discover Built-in Options for External Properties
Spring Boot binds external properties from `application.properties` (or YAML files and other places) into an application at runtime.
There is not (and technically cannot be) an exhaustive list of all supported properties in a single location, because contributions can come from additional jar files on your classpath.

A running application with the Actuator features has a `configprops` endpoint that shows all the bound and bindable properties available through `@ConfigurationProperties`.

The appendix includes an <<application-properties#appendix.application-properties, `application.properties`>> example with a list of the most common properties supported by Spring Boot.
The definitive list comes from searching the source code for `@ConfigurationProperties` and `@Value` annotations as well as the occasional use of `Binder`.
For more about the exact ordering of loading properties, see "<<features#features.external-config>>".