---
 Deployment
 ---
 Mark Hobson
 <markhobson@gmail.com>
 ---
 2010-02-15
 ---

 ~~ Licensed to the Apache Software Foundation (ASF) under one
 ~~ or more contributor license agreements.  See the NOTICE file
 ~~ distributed with this work for additional information
 ~~ regarding copyright ownership.  The ASF licenses this file
 ~~ to you under the Apache License, Version 2.0 (the
 ~~ "License"); you may not use this file except in compliance
 ~~ with the License.  You may obtain a copy of the License at
 ~~
 ~~   http://www.apache.org/licenses/LICENSE-2.0
 ~~
 ~~ Unless required by applicable law or agreed to in writing,
 ~~ software distributed under the License is distributed on an
 ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 ~~ KIND, either express or implied.  See the License for the
 ~~ specific language governing permissions and limitations
 ~~ under the License.

 ~~ NOTE: For help with the syntax of this file, see:
 ~~ http://maven.apache.org/doxia/references/apt-format.html

Deployment

 The plugin provides various methods of deployment to Tomcat:

 * {{{#Deploying_a_WAR_file}Deploying a WAR file}}

 * {{{#Deploying_an_exploded_WAR_directory}Deploying an exploded WAR directory}},
   with an optional <<<context.xml>>> file

 * {{{#Deploying_an_in-place_WAR_directory}Deploying an in-place WAR directory}},
   with an optional <<<context.xml>>> file

 * {{{#Deploying_a_context.xml_file}Deploying a <<<context.xml>>> file}}

 * {{{#Running_a_WAR_project}Running a WAR project}}

 []

 These are described in more detail below.

* {Deploying a WAR file}

 The simplest way to deploy a WAR project to Tomcat is to type:

+--
mvn tomcat:deploy
+--

 This goal will assemble and deploy the WAR file to Tomcat's manager using
 HTTP PUT.

** Using a different WAR file location

 To specify a different WAR file location, add a plugin configuration block to
 your <<<pom.xml>>> as follows:

+--
<project>
  ...
  <build>
    ...
    <plugins>
      ...
      <plugin>
        <groupId>org.apache.tomcat.maven</groupId>
        <artifactId>tomcat6-maven-plugin</artifactId>
        <version>${project.version}</version>
        <configuration>
          <warFile>path/to/my/warFile.war</warFile>
        </configuration>
      </plugin>
      ...
    </plugins>
    ...
  </build>
  ...
</project>
+--

 The default location is
 <<<$\{project.build.directory\}/$\{project.build.finalName\}.war>>>.

** Using a <<<context.xml>>> file

 If you need to specify a <<<context.xml>>> file when deploying a WAR file to
 Tomcat, then it must be included within the WAR.  The simplest way to achieve
 this is by adding it to your webapp resources:

+--
src
|_ main
   |_ webapp
      |_ META-INF
         |_ context.xml
+--

* {Deploying an exploded WAR directory}

 To avoid building a WAR file upon deployment, a WAR directory can instead be
 deployed to Tomcat by typing:

+--
mvn war:exploded tomcat:exploded
+--

** Using a different WAR directory location

 To specify a different WAR directory location, add a plugin configuration
 block to your <<<pom.xml>>> as follows:

+--
<project>
  ...
  <build>
    ...
    <plugins>
      ...
      <plugin>
        <groupId>org.apache.tomcat.maven</groupId>
        <artifactId>tomcat6-maven-plugin</artifactId>
        <version>${project.version}</version>
        <configuration>
          <warDirectory>path/to/my/warDir</warDirectory>
        </configuration>
      </plugin>
      ...
    </plugins>
    ...
  </build>
  ...
</project>
+--

 The default location is
 <<<$\{project.build.directory\}/$\{project.build.finalName\}>>>.

** Using a <<<context.xml>>> file

 To supply a <<<context.xml>>> when deploying a WAR directory, add a plugin
 configuration block to your <<<pom.xml>>> as follows:

+--
<project>
  ...
  <build>
    ...
    <plugins>
      ...
      <plugin>
        <groupId>org.apache.tomcat.maven</groupId>
        <artifactId>tomcat6-maven-plugin</artifactId>
        <version>${project.version}</version>
        <configuration>
          <mode>both</mode>
        </configuration>
      </plugin>
      ...
    </plugins>
    ...
  </build>
  ...
</project>
+--

 The default <<<context.xml>>> file use is located at
 <<<src/main/webapp/META-INF/context.xml>>>.

** Using a different <<<context.xml>>> file location

 To specify a different <<<context.xml>>> file location, add a plugin
 configuration block to your <<<pom.xml>>> as follows:

+--
<project>
  ...
  <build>
    ...
    <plugins>
      ...
      <plugin>
        <groupId>org.apache.tomcat.maven</groupId>
        <artifactId>tomcat6-maven-plugin</artifactId>
        <version>${project.version}</version>
        <configuration>
          <contextFile>path/to/my/contextFile.xml</contextFile>
        </configuration>
      </plugin>
      ...
    </plugins>
    ...
  </build>
  ...
</project>
+--

 The default location is
 <<<$\{project.build.directory\}/$\{project.build.finalName\}/META-INF/context.xml>>>.

* {Deploying an in-place WAR directory}

 To avoid copying resources to the build directory, the webapp source directory
 can be deployed to Tomcat by typing:

+--
mvn war:inplace tomcat:inplace
+--

** Using a different WAR directory location

 To specify a different WAR directory location, add a plugin configuration
 block to your <<<pom.xml>>> as follows:

+--
<project>
  ...
  <build>
    ...
    <plugins>
      ...
      <plugin>
        <groupId>org.apache.tomcat.maven</groupId>
        <artifactId>tomcat6-maven-plugin</artifactId>
        <version>${project.version}</version>
        <configuration>
          <warSourceDirectory>path/to/my/warSourceDir</warSourceDirectory>
        </configuration>
      </plugin>
      ...
    </plugins>
    ...
  </build>
  ...
</project>
+--

 The default location is <<<$\{basedir\}/src/main/webapp>>>.

** Using a <<<context.xml>>> file

 To supply a <<<context.xml>>> when deploying a WAR directory to Tomcat, add a
 plugin configuration block to your <<<pom.xml>>> as follows:

+--
<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.tomcat.maven</groupId>
        <artifactId>tomcat6-maven-plugin</artifactId>
        <version>${project.version}</version>
        <configuration>
          <mode>both</mode>
        </configuration>
      </plugin>
    </plugins>
  </build>
  ...
</project>
+--

 The default <<<context.xml>>> file used is located at
 <<<src/main/webapp/META-INF/context.xml>>>.

** Using a different <<<context.xml>>> file location

 To specify a different <<<context.xml>>> file location, add a plugin
 configuration block to your <<<pom.xml>>> as follows:

+--
<project>
  ...
  <build>
    ...
    <plugins>
      ...
      <plugin>
        <groupId>org.apache.tomcat.maven</groupId>
        <artifactId>tomcat6-maven-plugin</artifactId>
        <version>${project.version}</version>
        <configuration>
          <contextFile>path/to/my/contextFile.xml</contextFile>
        </configuration>
      </plugin>
      ...
    </plugins>
    ...
  </build>
  ...
</project>
+--

 The default location is
 <<<$\{project.build.directory\}/$\{project.build.finalName\}/META-INF/context.xml>>>.

* {Deploying a context.xml file}

 To simply deploy just a <<<context.xml>>> file to Tomcat:

 [[1]] Add a plugin configuration block to your <<<pom.xml>>> as follows:

+--
<project>
  ...
  <build>
    ...
    <plugins>
      ...
      <plugin>
        <groupId>org.apache.tomcat.maven</groupId>
        <artifactId>tomcat6-maven-plugin</artifactId>
        <version>${project.version}</version>
        <configuration>
          <mode>context</mode>
        </configuration>
      </plugin>
      ...
    </plugins>
    ...
  </build>
  ...
</project>
+--

 [[2]] Deploy the <<<context.xml>>> file by typing:

+--
mvn tomcat:deploy
+--

 []

 The default <<<context.xml>>> file used is located at
 <<<src/main/webapp/META-INF/context.xml>>>.

** Using a different <<<context.xml>>> file location

 To specify a different <<<context.xml>>> file location, add a plugin
 configuration block to your <<<pom.xml>>> as follows:

+--
<project>
  ...
  <build>
    ...
    <plugins>
      ...
      <plugin>
        <groupId>org.apache.tomcat.maven</groupId>
        <artifactId>tomcat6-maven-plugin</artifactId>
        <version>${project.version}</version>
        <configuration>
          <contextFile>path/to/my/contextFile.xml</contextFile>
        </configuration>
      </plugin>
      ...
    </plugins>
    ...
  </build>
  ...
</project>
+--

 The default location is
 <<<$\{project.build.directory\}/$\{project.build.finalName\}/META-INF/context.xml>>>.

* {Running a WAR project}

 A WAR project can be run under an embedded Tomcat server by typing:

+--
mvn tomcat:run
+--

 To stop the embedded server, press <<<CTRL+C>>>.