First, add jetty-maven-plugin to your pom.xml definition:

<plugin>
  <groupId>org.eclipse.jetty</groupId>
  <artifactId>jetty-maven-plugin</artifactId>
</plugin>
      
      

Then, from the same directory as your root pom.xml, type:

mvn jetty:run

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

Jetty continues to run until you stop it. While it runs, it periodically scans for changes to your project files, so if you save changes and recompile your class files, Jetty redeploys your webapp, and you can instantly test the changes you just made.

You can terminate the plugin with a ctrl-c in the terminal window where it is running.

The Jetty Maven plugin has a number of distinct Maven goals. Arguably the most useful is the run goal that we saw in the Quick Start section which runs Jetty on your unassembled webapp. There are other goals which help you accomplish different tasks. For example, you might need to run your webapp in a forked instance of Jetty, rather than within the process running Maven; or you may need finer grained control over the maven lifecycle stage in which you wish to deploy your webapp. There are different goals to accomplish these tasks, as well as several others.

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

mvn jetty:help

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

mvn jetty:help -Ddetail=true -Dgoal= goal-name

These configuration elements set up the Jetty environment in which your webapp executes. They are common to most goals:

These configuration parameters apply to your webapp. They are common to almost all goals.

The run goal runs on a webapp that does not have to be built into a WAR. Instead, Jetty deploys the webapp from its sources. 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 automatically ensures the classes are rebuilt 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.

You do not need to assemble the webapp into a WAR, saving time during the development cycle. 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.

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

<plugin>
  <groupId>org.eclipse.jetty</groupId>
  <artifactId>jetty-maven-plugin</artifactId>
  <configuration>
    <scanIntervalSeconds>10</scanIntervalSeconds>
    <webApp>
      <contextPath>/test</contextPath>
    </webApp>
  </configuration>
</plugin>
      
      

<project>
... 
  <plugins>
... 
    <plugin>
      <groupId>org.eclipse.jetty</groupId>
      <artifactId>jetty-maven-plugin</artifactId>
      <configuration>
        <webAppSourceDirectory>/Users/jesse/docsync/jetty-documentation/src/staticfiles</webAppSourceDirectory>
        <webApp>
          <contextPath>/</contextPath>
          <descriptor>/Users/jesse/docsync/jetty-documentation/src/over/here/web.xml</descriptor>
          <jettyEnvXml>/Users/jesse/docsync/jetty-documentation/src/over/here/jetty-env.xml</jettyEnvXml>
        </webApp>
        <classesDirectory>/Users/jesse/docsync/jetty-documentation/somewhere/else</classesDirectory>
        <scanTargets>
          <scanTarget>src/mydir</scanTarget>
          <scanTarget>src/myfile.txt</scanTarget>
        </scanTargets>
        <scanTargetPatterns>
          <scanTargetPattern>
            <directory>src/other-resources</directory>
            <includes>
              <include>**/*.xml</include>
              <include>**/*.properties</include>
            </includes>
            <excludes>
              <exclude>**/myspecial.xml</exclude>
              <exclude>**/myspecial.properties</exclude>
            </excludes>
          </scanTargetPattern>
        </scanTargetPatterns>
      </configuration>
    </plugin>
  </plugins>
</project>
        
        

This goal first packages your webapp as a WAR file and then deploys it to Jetty. If you set a non-zero scanInterval, Jetty watches your pom.xml and the WAR file; if either changes, it redeploys the war.

<project>
... 
  <plugins>
...
    <plugin>
      <groupId>org.eclipse.jetty</groupId>
      <artifactId>jetty-maven-plugin</artifactId>
      <configuration>
        <war>/Users/jesse/docsync/jetty-documentation/target/mycustom.war</war>
      </configuration>
    </plugin>
  </plugins>
</project>
        
        

The run-exploded goal first assembles your webapp into an exploded WAR file and then deploys it to Jetty. If you set a non-zero scanInterval, Jetty watches your pom.xml, WEB-INF/lib, WEB-INF/ classes and WEB-INF/web.xml for changes and redeploys when necessary.

<project> 
... 
  <plugins>
... 
    <plugin>
      <groupId>org.eclipse.jetty</groupId>
      <artifactId>maven-jetty-plugin</artifactId>
      <configuration>
        <war>/Users/jesse/docsync/jetty-documentation/target/myfunkywebapp</war>
      </configuration>
    </plugin>
  </plugins>
</project>
        
        

This is basically the same as jetty:run-war, but without assembling the WAR of the current module. Unlike run-war, the phase in which this plugin executes is not bound to the "package" phase. For example, you might want to start Jetty on the "test-compile" phase and stop Jetty on the "test-phase".

<project>
... 
  <plugins>
... 
  <plugin>
    <groupId>org.eclipse.jetty</groupId>
    <artifactId>jetty-maven-plugin</artifactId>
    <configuration>
      <war>/Users/jesse/docsync/jetty-documentation/target/mycustom.war</war>
    </configuration>
    <executions>
      <execution>
        <id>start-jetty</id>
        <phase>test-compile</phase>
        <goals>
          <goal>deploy-war</goal>
        </goals>
        <configuration>
          <daemon>true</daemon>
          <reload>manual</reload>
        </configuration>
      </execution>
      <execution>
        <id>stop-jetty</id>
        <phase>test</phase>
        <goals>
          <goal>stop</goal>
        </goals>
      </execution>
     </executions>
    </plugin>
  </plugins>
</project>
        
        

This goal allows you to start the webapp in a new JVM, optionally passing arguments to that new JVM.

mvn jetty:run-forked

This goal is for use with an execution binding in your pom.xml. It is similar to the jetty:run goal, however it 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. This is most useful when you want to control the start and stop of Jetty via execution bindings in your pom.xml.

For example, you can configure the plugin to start your webapp at the beginning of your unit tests and stop at the end. To do this, you need to set up a couple of execution scenarios for the Jetty plugin and use the <daemon>true</daemon> configuration option to force Jetty to execute only while Maven is running, instead of running indefinitely. You use the pre-integration-test and post-integration-test Maven build phases to trigger the execution and termination of Jetty:

<plugin>
  <groupId>org.eclipse.jetty</groupId>
  <artifactId>jetty-maven-plugin</artifactId>
  <configuration>
    <scanIntervalSeconds>10</scanIntervalSeconds>
    <stopKey>foo</stopKey>
    <stopPort>9999</stopPort>
  </configuration>
  <executions>
    <execution>
      <id>start-jetty</id>
      <phase>pre-integration-test</phase>
      <goals>
        <goal>start</goal>
      </goals>
      <configuration>
        <scanIntervalSeconds>0</scanIntervalSeconds>
        <daemon>true</daemon>
      </configuration>
    </execution>
    <execution>
      <id>stop-jetty</id>
      <phase>post-integration-test</phase>
       <goals>
         <goal>stop</goal>
       </goals>
     </execution>
  </executions>
</plugin>
      
      

Of course, you can use this goal from the command line ( mvn jetty:start), however you need to be sure that all generated classes and files for your webapp are already present first.

The stop goal stops a 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 start goal.

Here's a configuration example:

<plugin>
  <groupId>org.eclipse.jetty</groupId>
  <artifactId>jetty-maven-plugin</artifactId>
  <configuration>
    <stopPort>9966</stopPort>
    <stopKey>foo</stopKey>
  </configuration>
</plugin>
      
      

Then, while Jetty is running (in another window), type:

mvn jetty:stop

The stopPort must be free on the machine you are running on. If this is not the case, you get an "Address already in use" error message after the "Started SelectedChannelConnector ..." message.

If your webapp depends on other war files, thejetty:run and jetty:run-forked 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.

<dependency>
  <groupId>com.acme</groupId>
  <artifactId>X</artifactId>
  <type>war</type>
</dependency>
<dependency>
  <groupId>com.acme</groupId>
  <artifactId>Y</artifactId>
  <type>war</type>
</dependency>
          
          

WebAppX: 

 /foo.jsp 
 /bar.jsp 
 /WEB-INF/web.xml 

WebAppY: 

 /bar.jsp
 /baz.jsp
 /WEB-INF/web.xml
 /WEB-INF/special.xml
        
        

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-war-plugin</artifactId>
  <configuration>
    <overlays>
      <overlay>
        <groupId>com.acme</groupId>
        <artifactId>X</artifactId>
        <excludes>
          <exclude>bar.jsp</exclude>
        </excludes>
      </overlay>
      <overlay>
        <groupId>com.acme</groupId>
        <artifactId>Y</artifactId>
        <excludes>
          <exclude>baz.jsp</exclude>
        </excludes>
      </overlay>
      <overlay>
      </overlay>
    </overlays>
  </configuration>
</plugin>

<dependency>
  <groupId>com.acme</groupId>
  <artifactId>X</artifactId>
  <type>war</type>
</dependency>
<dependency>
  <groupId>com.acme</groupId>
  <artifactId>Y</artifactId>
  <type>war</type>
</dependency>

WebAppX: 

 /foo.jsp 
 /bar.jsp 
 /WEB-INF/web.xml 

WebAppY: 

 /bar.jsp 
 /baz.jsp
 /WEB-INF/web.xml 
 /WEB-INF/special.xml
        

/foo.jsp (X) 
/bar.jsp (X) 
/baz.jsp (Y) 
/WEB-INF/web.xml (X)
/WEB-INF/special.xml (Y)
                

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

<plugin>
  <groupId>org.eclipse.jetty</groupId>
  <artifactId>jetty-maven-plugin</artifactId>
  <configuration>
    <scanIntervalSeconds>10</scanIntervalSeconds>
    <webApp>
      <contextPath>/test</contextPath>
    </webApp>
    <loginServices>
      <loginService implementation="org.eclipse.jetty.security.HashLoginService">
        <name>Test Realm</name>
        <config>/Users/jesse/docsync/jetty-documentation/src/etc/realm.properties</config>
      </loginService>
    </loginServices>
  </configuration>
</plugin>
           

If you have external resources that you want to incorporate in the execution of a webapp, but which are not assembled into WARs, 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's a configuration example:

<configuration>
  <webApp>
    <contextPath>/jetty-documentation-9.0.2-SNAPSHOT</contextPath>
    <baseResource implementation="org.eclipse.jetty.util.resource.ResourceCollection">
      <resourcesAsCSV>src/main/webapp,/home/johndoe/path/to/my/other/source,/yet/another/folder</resourcesAsCSV>
    </baseResource>
  </webApp>
</configuration>      
      

You can use either a jetty.xml file to configure extra (pre-compiled) webapps that you want to deploy, or you can use the <contextHandlers> configuration element to do so. If you want to deploy webapp A, and webapps B and C in the same Jetty instance:

Putting the configuration in webapp A's pom.xml:

<plugin>
  <groupId>org.eclipse.jetty</groupId>
  <artifactId>jetty-maven-plugin</artifactId>
  <configuration>
    <scanIntervalSeconds>10</scanIntervalSeconds>
    <webApp>
      <contextPath>/test</contextPath>
    </webApp>
    <contextHandlers>
      <contextHandler implementation="org.eclipse.jetty.webapp.WebAppContext">
        <war>/Users/jesse/docsync/jetty-documentation../../B.war</war>
        <contextPath>/B</contextPath>
      </contextHandler>
      <contextHandler implementation="org.eclipse.jetty.webapp.WebAppContext">
        <war>/Users/jesse/docsync/jetty-documentation../../C.war</war>
        <contextPath>/B</contextPath>
      </contextHandler>
    </contextHandlers>
  </configuration>
</plugin>
            

Alternatively, add a jetty.xml file to webapp A. Copy the jetty.xml file from the jetty distribution, and then add WebAppContexts for the other 2 webapps:

<Ref refid="Contexts">
  <Call name="addHandler">
    <Arg>
      <New class="org.eclipse.jetty.webapp.WebAppContext">
        <Set name="contextPath">/B</Set>
        <Set name="war">../../B.war</Set>
      </New>
    </Arg>
  </Call>
  <Call> 
    <Arg>
      <New class="org.eclipse.jetty.webapp.WebAppContext">
        <Set name="contextPath">/C</Set>
        <Set name="war">../../C.war</Set>
      </New>
    </Arg>
  </Call>
</Ref>      
      

Then configure the location of this jetty.xml file into webapp A's jetty plugin:

<plugin>
  <groupId>org.eclipse.jetty</groupId>
  <artifactId>jetty-maven-plugin</artifactId>
  <configuration>
    <scanIntervalSeconds>10</scanIntervalSeconds>
    <webApp>
      <contextPath>/test</contextPath>
    </webApp>
    <jettyXml>src/main/etc/jetty.xml</jettyXml>
  </configuration>
</plugin>      
      

For either of these solutions, the other webapps must already have been built, and they are not automatically monitored for changes. You can refer either to the packed WAR file of the pre-built webapps or to their expanded equivalents.

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:

<plugin>
  <groupId>org.codehaus.mojo</groupId>
  <artifactId>properties-maven-plugin</artifactId>
  <version>1.0-alpha-2</version>
  <executions>
    <execution>
      <goals>
        <goal>set-system-properties</goal>
      </goals>
      <configuration>
        <properties>
          <property>
            <name>logback.configurationFile</name>
            <value>${project.baseUri}/resources/logback.xml</value>
          </property>
        </properties>
      </configuration>
    </execution>
  </executions>
</plugin>
      

Note that if a System property is already set (for example, from the command line or by the JVM itself), then by default these configured properties DO NOT override them (see below for use of the <force> parameter).

<plugin> 
  <groupId>org.eclipse.jetty</groupId>
  <artifactId>jetty-maven-plugin</artifactId>
  <configuration> 
    <systemProperties>
      <systemProperty>
        <name>fooprop</name>
        <value>222</value>
      </systemProperty>
    </systemProperties>
    <webApp>
      <contextPath>/test</contextPath>
    </webApp>
  </configuration> 
</plugin>
                

<plugin> 
  <groupId>org.eclipse.jetty</groupId>
  <artifactId>jetty-maven-plugin</artifactId>
  <configuration>
    <systemProperties>
      <force>true</force>
      <systemProperty>
       <name>fooprop</name>
       <value>222</value>
     </systemProperty>
    </systemProperties>
    <webApp>
      <contextPath>/test</contextPath>
    </webApp>
  </configuration>
</plugin>
                

fooprop=222
                

<plugin>
  <groupId>org.eclipse.jetty</groupId>
  <artifactId>jetty-maven-plugin</artifactId>
  <configuration>
    <systemPropertiesFile>/Users/jesse/docsync/jetty-documentation/mysys.props</systemPropertiesFile>
    <webApp>
      <contextPath>/test</contextPath>
    </webApp>
  </configuration>
</plugin>