Using the Jetty Maven Plugin

Since Jetty 12, Jetty Maven plugin is repackaged for the corresponding Jakarta EE version with an eeX classifier in the groupId and artifactId.

First, add jetty-ee{8,9,10}-maven-plugin to your pom.xml definition. Here’s an example of how to do that for Jakarta EE 10:

Then, from the same directory as the project’s root pom.xml, type:

This starts Jetty and serves up the project on http://localhost:8080/.

Jetty will continue to run until you stop it. By default, it will not automatically restart your webapp. Set a non-zero <scan> value to have Jetty scan your webapp for changes and automatically redeploy, or set <scan> to 0 to cause manual redeployment by hitting the Enter key.

Terminate the plugin with a Ctrl+c in the terminal window where it is running.

The goals prefixed with "run-" are designed to be used at the command line. They first run a Maven build on your project to ensure at least the classes are all built. They then start Jetty and pause the Maven build process until Jetty is manually terminated, at which time the build will also be terminated. Jetty can scan various files in your project for changes and redeploy the webapp as necessary, or you can choose to manually trigger a redeploy if you prefer. All output from Jetty is echoed to the console.

The goals prefixed with "start-" are designed to be used with build lifecycle bindings in the pom, and not at the command line. No part of your project will be rebuilt by invoking these goals - you should ensure that your bind the execution to a build phase where all necessary parts of your project have been built. Maven will start and terminate Jetty at the appropriate points in the build lifecycle, continuing with the build. Jetty will not scan any files in your project for changes, and your webapp will not be redeployed either automatically or manually. Output from Jetty is directed to a file in the target directory.

To see a list of all goals supported by the Jetty Maven plugin, do:

To see the detailed list of parameters that can be configured for a particular goal, in addition to its description, do:

All of the "run-" and "start-" goals can deploy your webapp either into the running maven process, or forked into a new child process, or forked into a Jetty distribution on disk.

This is controlled by setting the deployMode configuration parameter in the pom, but can also be set by defining the Maven property 'jetty.deployMode'.

The following configuration parameters are common to all of the "run-" and "start-" goals:

The Servlet Specification makes a strong distinction between the classpath for a webapp, and the classpath of the container. When running in Maven, the plugin’s classpath is equivalent to the container classpath. It will make a classpath for the webapp to be deployed comprised of <dependencies> specified in the pom.

If your production environment places specific jars onto the container’s classpath, the equivalent way to do this with Maven is to define these as <dependencies> for the plugin itself, not the project. See configuring maven plugins. This is suitable if you are using either EMBED or FORK mode. If you are using EXTERNAL mode, then you should configure the modules parameter with the names of the Jetty modules that place these jars onto the container classpath.

Note that in EMBED or FORK mode, you could also influence the container classpath by setting the useProvidedScope parameter to true: this will place any dependencies with <scope>provided<scope> onto the plugin’s classpath. Use this very cautiously: as the plugin already automatically places most Jetty jars onto the classpath, you could wind up with duplicate jars.

The run goal deploys a webapp that is not first built into a WAR. A virtual webapp is constructed from the project’s sources and its dependencies. It looks for the constituent parts of a webapp in the Maven default project locations, although you can override these in the plugin configuration. For example, by default it looks for:

The plugin first runs a Maven parallel build to ensure that the classes are built and up-to-date before deployment. If you change the source of a class and your IDE automatically compiles it in the background, the plugin picks up the changed class (note you need to configure a non-zero scan interval for automatic redeployment).

If the plugin is invoked in a multi-module build, any dependencies that are also in the Maven reactor are used from their compiled classes.

Once invoked, you can configure the plugin to run continuously, scanning for changes in the project and automatically performing a hot redeploy when necessary. Any changes you make are immediately reflected in the running instance of Jetty, letting you quickly jump from coding to testing, rather than going through the cycle of: code, compile, reassemble, redeploy, test.

The Maven build will be paused until Jetty exits, at which time Maven will also exit.

Stopping Jetty is accomplished by typing cntrl-c at the command line.

Output from Jetty will be logged to the console.

Here is an example, which turns on scanning for changes every ten seconds, and sets the webapp context path to /test:

When invoked at the command line this goal first executes a maven build of your project to the package phase.

By default it then deploys the resultant war to Jetty, but you can use this goal instead to deploy any war file by simply setting the <webApp><war> configuration parameter to its location.

If you set a non-zero scan, Jetty watches your pom.xml and the WAR file; if either changes, it redeploys the war.

The maven build is held up until Jetty exits, which is achieved by typing cntrl-c at the command line.

All Jetty output is directed to the console.

This is similar to the jetty:run goal, however it is not designed to be run from the command line and does not first execute the build up until the test-compile phase to ensure that all necessary classes and files of the webapp have been generated. It will not scan your project for changes and restart your webapp. It does not pause maven until Jetty is stopped.

Instead, it is designed to be used with build phase bindings in your pom. For example to you can have Maven start your webapp at the beginning of your tests and stop at the end.

If the plugin is invoked as part of a multi-module build, any dependencies that are also in the maven reactor are used from their compiled classes.

Here’s an example of using the pre-integration-test and post-integration-test Maven build phases to trigger the execution and termination of Jetty:

This goal will generate output from jetty into the target/jetty-start.out file.

Similarly to the jetty:start goal, jetty:start-war is designed to be bound to build lifecycle phases in your pom.

It will not scan your project for changes and restart your webapp. It does not pause maven until Jetty is stopped.

By default, if your pom is for a webapp project, it will deploy the war file for the project to jetty. However, like the jetty:run-war project, you can nominate any war file to deploy by defining its location in the <webApp><war> parameter.

If the plugin is invoked as part of a multi-module build, any dependencies that are also in the Maven reactor are used from their compiled classes.

This goal will generate output from jetty into the target/jetty-start-war.out file.

The stop goal stops a FORK or EXTERNAL mode running instance of Jetty. To use it, you need to configure the plugin with a special port number and key. That same port number and key will also be used by the other goals that start Jetty.

This goal calculates a synthetic web.xml (the "effective web.xml") according to the rules of the Servlet Specification taking into account all sources of discoverable configuration of web components in your application: descriptors (webdefault.xml, web.xml, web-fragment.xml`s, `web-override.xml) and discovered annotations (@WebServlet, @WebFilter, @WebListener). No programmatic declarations of servlets, filters and listeners can be taken into account.

You can calculate the effective web.xml for any pre-built war file by setting the <webApp><war> parameter, or you can calculate it for the unassembled webapp by setting all of the usual <webApp> parameters as for jetty:run.

Other useful information about your webapp that is produced as part of the analysis is also stored as context parameters in the effective-web.xml. The effective-web.xml can be used in conjunction with the Quickstart feature to quickly start your webapp (note that Quickstart is not appropriate for the mvn jetty goals).

The effective web.xml from these combined sources is generated into a file, which by default is target/effective-web.xml, but can be changed by setting the effectiveWebXml configuration parameter.

If your webapp depends on other war files, the jetty:run and jetty:start goals are able to merge resources from all of them. It can do so based on the settings of the maven-war-plugin, or if your project does not use the maven-war-plugin to handle the overlays, it can fall back to a simple algorithm to determine the ordering of resources.

You can configure LoginServices in the plugin. Here’s an example of setting up the HashLoginService for a webapp:

If you have external resources that you want to incorporate in the execution of a webapp, but which are not assembled into war files, you can’t use the overlaid wars method described above, but you can tell Jetty the directories in which these external resources are located. At runtime, when Jetty receives a request for a resource, it searches all the locations to retrieve the resource. It’s a lot like the overlaid war situation, but without the war.

Here is a configuration example:

You can specify property name/value pairs that Jetty sets as System properties for the execution of the plugin. This feature is useful to tidy up the command line and save a lot of typing.

However, sometimes it is not possible to use this feature to set System properties - sometimes the software component using the System property is already initialized by the time that maven runs (in which case you will need to provide the System property on the command line), or by the time that Jetty runs. In the latter case, you can use the maven properties plugin to define the system properties instead. Here’s an example that configures the logback logging system as the Jetty logger: