[[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:

[source,shell]
----
$ mvn spring-boot:run
----

Application arguments can be specified using the `arguments` parameter, see xref:run.adoc#run.examples.using-application-arguments[using application arguments] for more details.

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 (that is for debugging purposes), you can use the `jvmArguments` parameter, see xref:run.adoc#run.examples.debug[Debug the application] for more details.
There is also explicit support for xref:run.adoc#run.examples.system-properties[system properties] and xref:run.adoc#run.examples.environment-variables[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 xref:run.adoc#run.examples.specify-active-profiles[Specify active profiles].

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"]
----
include::example$running/devtools-pom.xml[tags=devtools]
----

When `devtools` is running, it detects changes 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]
----
spring.devtools.remote.restart.enabled=false
----

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

[source,xml,subs="verbatim,attributes"]
----
include::example$running/hot-refresh-pom.xml[tags=hot-refresh]
----

When `addResources` is enabled, any `src/main/resources` directory will be added to the application classpath when you run the application and any duplicate found in the classes output 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 xref:packaging.adoc#packaging.examples.exclude-dependency[the dedicated example].

Sometimes it is useful to run a test variant of your application.
For example, if you want to xref:reference:features/dev-services.adoc#features.dev-services.testcontainers.at-development-time[use Testcontainers at development time] or make use of some test stubs.
Use the `test-run` goal with many of the same features and configuration options as `run` for this purpose.

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

include::partial$goals/test-run.adoc[leveloffset=+1]



[[run.examples]]
== Examples



[[run.examples.debug]]
=== Debug the Application

The `run` and `test-run` goals run 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"]
----
include::example$running/debug-pom.xml[tags=debug]
----

These arguments can be specified on the command line as well:

[source,shell]
----
$ mvn spring-boot:run -Dspring-boot.run.jvmArguments=-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=*:5005
----



[[run.examples.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"]
----
include::example$running/system-properties-pom.xml[tags=system-properties]
----

If the value is empty or not defined (that is `<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 through 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 (for example 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`:

[source,shell]
----
$ mvn spring-boot:run -Dspring-boot.run.jvmArguments="-Dproperty1=overridden"
----



[[run.examples.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"]
----
include::example$running/environment-variables-pom.xml[tags=environment-variables]
----

If the value is empty or not defined (that is `<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 (for example 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.examples.using-application-arguments]]
=== Using Application Arguments

Application arguments can be specified using the `arguments` attribute.
The following example sets two arguments: `property1` and `property2=42`:

[source,xml,indent=0,subs="verbatim,attributes"]
----
include::example$running/application-arguments-pom.xml[tags=application-arguments]
----

On the command-line, arguments are separated by a space the same way `jvmArguments` are.
If an argument contains a space, make sure to quote it.
In the following example, two arguments are available: `property1` and `property2=Hello World`:

[source,shell]
----
$ mvn spring-boot:run -Dspring-boot.run.arguments="property1 'property2=Hello World'"
----



[[run.examples.specify-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 `local` and `dev` profiles:

[source,xml,indent=0,subs="verbatim,attributes"]
----
include::example$running/active-profiles-pom.xml[tags=active-profiles]
----

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:

[source,shell]
----
$ mvn spring-boot:run -Dspring-boot.run.profiles=local,dev
----
