modules/deployment-01.html

<!--
  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.
-->
<section>
  <h2>Deployment</h2>
</section>
<section>
  <h3>Definition</h3>
  <p>Adding a web application to Tomcat</p>
  <p>A web application maps request URLs to zero to many Filters and exactly one Servlet</p>
  <p>Plus a supporting cast of static content, security configuration, resources, session management
     and more</p>
  <p>Web application (Servlet spec) == Context (Tomcat)</p>
</section>
<section>
  <h3>Web application structure</h3>
  <p>Directory or Web ARchive (WAR)</p>
  <p>WAR has same format as JAR (and zip)</p>
</section>
<section>
  <h3>Web application structure</h3>
  <p>/ contains static content (and JSPs)</p>
  <p>/WEB-INF/ may contain web.xml file</p>
  <p>/META-INF/ may contain context.xml file</p>
  <p>/WEB-INF/classes Java class files</p>
  <p>/WEB-INF/lib JAR files</p>
</section>
<section>
  <h3>Servlet</h3>
  <p>Java class</p>
  <p>Accepts an HTTP request</p>
  <p>Generates an HTTP response</p>
  <p>Default Servlet: static files</p>
  <p>JSP Servlet (Jasper): JSP files</p>
</section>
<section>
  <h3>Mapping rules</h3>
  <p>Web applications are deployed to a context path</p>
  <p>First mapping rule is map to longest matching context path</p>
</section>
<section>
  <h3>Context Paths</h3>
  <p>The context path is always derived from the WAR, DIR or context.xml</p>
  <p>Any Servlet 4 defined preference in web.xml is ignored</p>
</section>
<section>
  <h3>Context Paths</h3>
  <table>
    <tr>
      <th>Context Path</th>
      <th>Context Name</th>
      <th>Base File Name</th>
      <th>Example File Names (.xml, .war &amp; directory)</th>
    </tr>
    <tr>
      <td>/foo</td>
      <td>/foo</td>
      <td>foo</td>
      <td>foo.xml, foo.war, foo</td>
    </tr>
    <tr>
      <td>/foo/bar</td>
      <td>/foo/bar</td>
      <td>foo#bar</td>
      <td>foo#bar.xml, foo#bar.war, foo#bar</td>
    </tr>
    <tr>
      <td><i>Empty String</i></td>
      <td><i>Empty String</i></td>
      <td>ROOT</td>
      <td>ROOT.xml, ROOT.war, ROOT</td>
    </tr>
  </table>
</section>
<section>
  <h3>Automatic deployment</h3>
  <p>Default Host appBase is $CATALINA_BASE/webapps</p>
  <p>Directories and WARs placed here are deployed at start-up by default</p>
  <p>WAR or directory for a Context is called the docBase</p> 
  <p>deployOnStartUp, autoDeploy, unpackWARs</p>
</section>
<section>
  <h3>Deployment Descriptors</h3>
  <p>context.xml files</p>
  <p>/META-INF/context.xml
  <p>$CATALINA_BASE/conf/engine-name/host-name/base-name.xml</p>
  <p>$CATALINA_BASE/conf/Catalina/localhost/manager.xml</p>
  <p>$CATALINA_BASE/conf/engine-name/host-name/ is known as xmlBase</p>
</section>
<section>
  <h3>Deployment Descriptors</h3>
  <p>copyXML - copy to $CATALINA_BASE</p>
  <p>deployXML - ignore /META-INF/context.xml</p>
  <p>Note: defaults changed in Tomcat 7</p>
  <p>Can point to a docBase outside the appBase</p>
</section>
<section>
  <h3>Automatic deployment</h3>
  <p>1st Deployment descriptors in xmlBase</p>
  <p>2nd WARs in appBase</p>
  <p>3rd Directories in appBase</p>
</section>
<section>
  <h3>Automatic deployment</h3>
  <p>Detecting changes</p>
  <p>Tomcat will pick up the change</p>
  <p>Aims to do the minimum necessary for the change to take effect</p>
  <p>The <a href="https://tomcat.apache.org/tomcat-9.0-doc/config/automatic-deployment.html">details</a>
     are documented</p>
</section>
<section>
  <h3>Automatic deployment</h3>
  <p>You can define Contexts in server.xml</p>
  <p>Don't</p>
  <p>Changes require a Tomcat restart</p>
</section>
<section>
  <h3>Changes while shutdown</h3>
  <p>Most will take effect on start-up</p>
  <p>Updated WAR with unpacked DIR used to be ignored</p>
  <p>/META-INF/war-tracker as of 8.0.21</p> 
</section>
<section>
  <h3>Parallel deployment</h3>
  <p>Different versions of web application at the same time</p>
  <p>Sessions using old version continue to do so</p>
  <p>New sessions use latest version</p>
</section>
<section>
  <h3>Parallel deployment</h3>
  <p>foo##001.war</p>
  <p>foo##002.war</p>
  <p>Version is a string, not a number</p>
</section>
<section>
  <h3>Demonstration</h3>
  <p>Automatic deployment</p>
  <p>Changes</p>
  <p>Parallel deployment</p>
</section>
<section>
  <h3>Exercise</h3>
  <p>Create a web application and deploy it</p>
  <p>Demonstrate parallel deployment</p>
</section>