spring-boot/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/running.adoc

[[run]]
== Running your application with Maven

The plugin includes a run goal which can be used to launch your application from the command line, as shown in the following example:

[indent=0]
----
	$ mvn spring-boot:run
----

By default the application is executed in a forked process and setting properties on the command-line will not affect the application.
If you need to specify some JVM arguments (i.e. for debugging purposes), you can use the `jvmArguments` parameter, see <<run-example-debug,Debug the application>> for more details.
There is also explicit support for <<run-example-system-properties,system properties>> and <<run-example-environment-variable,environment variables>>.

As enabling a profile is quite common, there is dedicated `profiles` property that offers a shortcut for `-Dspring-boot.run.jvmArguments="-Dspring.profiles.active=dev"`, see <<run-example-active-profiles,Specify active profiles>>.

Although this is not recommended, it is possible to execute the application directly from the Maven JVM by disabling the `fork` property.
Doing so means that the `jvmArguments`, `systemPropertyVariables`, `environmentVariables` and `agents` options are ignored.

Spring Boot `devtools` is a module to improve the development-time experience when working on Spring Boot applications.
To enable it, just add the following dependency to your project:

[source,xml,indent=0,subs="verbatim,attributes"]
----
	<dependencies>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-devtools</artifactId>
			<version>{gradle-project-version}</version>
			<optional>true</optional>
		</dependency>
	</dependencies>
----

When `devtools` is running, it detects change when you recompile your application and automatically refreshes it.
This works for not only resources but code as well.
It also provides a LiveReload server so that it can automatically trigger a browser refresh whenever things change.

Devtools can also be configured to only refresh the browser whenever a static resource has changed (and ignore any change in the code).
Just include the following property in your project:

[source,properties,indent=0]
----
	spring.devtools.remote.restart.enabled=false
----

Prior to `devtools`, the plugin supported hot refreshing of resources by default which has now be disabled in favour of the solution described above.
You can restore it at any time by configuring your project:

[source,xml,indent=0,subs="verbatim,attributes"]
----
<build>
	<plugins>
		<plugin>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-maven-plugin</artifactId>
			<version>{gradle-project-version}</version>
			<configuration>
				<addResources>true</addResources>
			</configuration>
		</plugin>
	</plugins>
</build>
----

When `addResources` is enabled, any `src/main/resources` folder will be added to the application classpath when you run the application and any duplicate found in `target/classes` will be removed.
This allows hot refreshing of resources which can be very useful when developing web applications.
For example, you can work on HTML, CSS or JavaScript files and see your changes immediately without recompiling your application.
It is also a helpful way of allowing your front end developers to work without needing to download and install a Java IDE.

NOTE: A side effect of using this feature is that filtering of resources at build time will not work.

In order to be consistent with the `repackage` goal, the `run` goal builds the classpath in such a way that any dependency that is excluded in the plugin's configuration gets excluded from the classpath as well.
For more details, see <<run-example-exclude-dependency,the dedicated example>>.

Sometimes it is useful to include test dependencies when running the application.
For example, if you want to run your application in a test mode that uses stub classes.
If you wish to do this, you can set the `useTestClasspath` parameter to true.
Note that this is only applied when you run an application: the `repackage` goal will not add test dependencies to the resulting JAR/WAR.

include::goals/run.adoc[leveloffset=+1]

[[run-examples]]
=== Examples



[[run-example-debug]]
==== Debug the Application
By default, the `run` goal runs your application in a forked process.
If you need to debug it, you should add the necessary JVM arguments to enable remote debugging.
The following configuration suspend the process until a debugger has joined on port 5005:

[source,xml,indent=0,subs="verbatim,attributes"]
----
	<project>
		<build>
			<plugins>
				<plugin>
					<groupId>org.springframework.boot</groupId>
					<artifactId>spring-boot-maven-plugin</artifactId>
					<version>{gradle-project-version}</version>
					<configuration>
						<jvmArguments>
							-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005
						</jvmArguments>
					</configuration>
				</plugin>
			</plugins>
		</build>
	</project>
----

These arguments can be specified on the command line as well, make sure to wrap that properly, that is:

[indent=0]
----
	$ mvn spring-boot:run -Dspring-boot.run.jvmArguments="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005"
----



[[run-example-system-properties]]
==== Using System Properties
System properties can be specified using the `systemPropertyVariables` attribute.
The following example sets `property1` to `test` and `property2` to 42:

[source,xml,indent=0,subs="verbatim,attributes"]
----
	<project>
		<build>
			<properties>
				<my.value>42</my.value>
			</properties>
			<plugins>
				<plugin>
					<groupId>org.springframework.boot</groupId>
					<artifactId>spring-boot-maven-plugin</artifactId>
					<version>{gradle-project-version}</version>
					<configuration>
						<systemPropertyVariables>
							<property1>test</property1>
							<property2>${my.value}</property2>
						</systemPropertyVariables>
					</configuration>
				</plugin>
			</plugins>
		</build>
	</project>
----

If the value is empty or not defined (i.e. `<my-property/`>), the system property is set with an empty String as the value.
Maven trims values specified in the pom so it is not possible to specify a System property which needs to start or end with a space via this mechanism: consider using `jvmArguments` instead.

Any String typed Maven variable can be passed as system properties.
Any attempt to pass any other Maven variable type (e.g. a `List` or a `URL` variable) will cause the variable expression to be passed literally (unevaluated).

The `jvmArguments` parameter takes precedence over system properties defined with the mechanism above.
In the following example, the value for `property1` is `overridden`:

[indent=0]
----
	$ mvn spring-boot:run -Dspring-boot.run.jvmArguments="-Dproperty1=overridden"
----



[[run-example-environment-variables]]
==== Using Environment Variables
Environment variables can be specified using the `environmentVariables` attribute.
The following example sets the 'ENV1', 'ENV2', 'ENV3', 'ENV4' env variables:

[source,xml,indent=0,subs="verbatim,attributes"]
----
<project>
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
				<version>{gradle-project-version}</version>
				<configuration>
					<environmentVariables>
						<ENV1>5000</ENV1>
						<ENV2>Some Text</ENV2>
						<ENV3/>
						<ENV4></ENV4>
					</environmentVariables>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>
----

If the value is empty or not defined (i.e. `<MY_ENV/`>), the env variable is set with an empty String as the value.
Maven trims values specified in the pom so it is not possible to specify an env variable which needs to start or end with a space.

Any String typed Maven variable can be passed as system properties.
Any attempt to pass any other Maven variable type (e.g. a `List` or a `URL` variable) will cause the variable expression to be passed literally (unevaluated).

Environment variables defined this way take precedence over existing values.



[[run-example-active-profiles]]
==== Specify Active Profiles
The active profiles to use for a particular application can be specified using the `profiles` argument.

The following configuration enables the `foo` and `bar` profiles:

[source,xml,indent=0,subs="verbatim,attributes"]
----
<project>
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
				<version>{gradle-project-version}</version>
				<configuration>
					<profiles>
						<profile>foo</profile>
						<profile>bar</profile>
					</profiles>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>
----

The profiles to enable can be specified on the command line as well, make sure to separate them with a comma, as shown in the following example:

[indent=0]
----
	$ mvn spring-boot:run -Dspring-boot.run.profiles=foo,bar
----