This chapter provides sample instructions for deploying the WAR to Apache Tomcat. See Upgrading for Apache Tomcat Deployments for instructions on updating to a newer version of the SOAtest and Virtualize Server.

The first example outlines the recommended method for deploying a WAR file at the root context of Apache Tomcat. The second example describes a shortcut for an easier (but not recommended) installation method. Using a "non-root" context might not work for some servlet containers. 

Apache Tomcat Deployment Example 1 (Recommended Method)

One way to deploy the WAR file with Apache Tomcat at the ROOT context path is as follows:

  1. Create a new folder to serve as <SOAVIRT_HOME>. It can be located anywhere except within the Apache Tomcat webapps directory. For example, on Windows you might use c:/wars/soavirt.
  2. Extract the contents of the WAR file into <SOAVIRT_HOME>.
  3. Download Apache Tomcat Core 7 or above for your platform from http://tomcat.apache.org/.
  4. Extract the downloaded Apache Tomcat to a location of your choice (<TOMCAT_HOME>).
  5. In <TOMCAT_HOME>/conf/Catalina/localhost/, create an empty ROOT.xml file.

  6. Open <TOMCAT_HOME>/conf/Catalina/localhost/ROOT.xml file and add a Context element such as the following (making the appropriate adjustments to docBase absolute path as needed, depending on your specific <SOAVIRT_HOME> location):

    <Context 
  docBase="c:/wars/soavirt" 
  path="" 
  reloadable="true" 
/>
  7. (Optional) If you want to deploy the WAR file over HTTPS, perform the following steps to configure for SSL:
    1. Create a keystore file to store the server's private key and self-signed certificate by executing the following command:

      <JAVA_HOME>/bin/keytool -genkey -alias tomcat -keyalg RSA -keystore /path/to/my/keystore
       
    2. Specify changeit as the password when prompted.

    3. A new file in the /path/to/my directory named "keystore" will be created. Uncomment the SSL HTTP/1.1 Connector entry in the <TOMCAT_HOME>/conf/server.xml configuration file:

      <!-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->
<Connector
     protocol="org.apache.coyote.http11.Http11NioProtocol"
     port="8443" maxThreads="200"
     scheme="https" secure="true" SSLEnabled="true"
     keystoreFile="${user.home}/.keystore" keystorePass="changeit"
     clientAuth="false" sslProtocol="TLS"/>
keystoreFile attribute value to "/path/to/my/keystore"
  8. Specify the ports used by Apache Tomcat in the config.properties file at <SOAVIRT_HOME>/WEB-INF/config.properties (see Server Configuration for details). For example, you might use server.port.http=8080 or server.port.https=8443. The ports specified in config.properties must match the ports specified in the Tomcat configuration.
  9. Specify the appropriate license in the config.properties file at <SOAVIRT_HOME>/WEB-INF/config.properties (see Server Configuration for details).
  10. Start Tomcat (e.g., from <TOMCAT_HOME>/bin).
  11. Browse to http://localhost:8080/ (adjust the port if needed). The following message confirms that the application was installed correctly: 

There are no deployments on this server. Cannot respond to this request: /.

By default, a workspace directory will be created in <SOAVIRT_HOME>.

Apache Tomcat Deployment Example 2 (Shortcut Method)

Although this method is easier than the first, it is not recommended because it removes the default Tomcat ROOT web application.

  1. Download Apache Tomcat Core 7 or above for your platform from http://tomcat.apache.org/.
  2. Extract the downloaded Apache Tomcat to a location of your choice (<TOMCAT_HOME>).
  3. Remove the “ROOT” folder from the webapps directory.
  4. Rename the “soavirt_<version>.war” file to “ROOT.war”.
  5. Copy “ROOT.war” into the <TOMCAT_HOME>/webapps/ folder.
  6. (Optional) If you want to deploy the WAR file over HTTPS, perform the following steps to configure for SSL:
    1. Create a keystore file to store the server's private key and self-signed certificate by executing the following command:

      <JAVA_HOME>/bin/keytool -genkey -alias tomcat -keyalg RSA -keystore /path/to/my/keystore
       
    2. Specify "changeit" as the password when prompted.
    3. A new file in the /path/to/my directory named "keystore" will be created.

    4. Uncomment the SSL HTTP/1.1 Connector entry in the <TOMCAT_HOME>/conf/server.xml configuration file:

      <!-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->
<Connector
     protocol="org.apache.coyote.http11.Http11NioProtocol"
     port="8443" maxThreads="200"
     scheme="https" secure="true" SSLEnabled="true"
     keystoreFile="${user.home}/.keystore" keystorePass="changeit"
     clientAuth="false" sslProtocol="TLS"/>
keystoreFile attribute value to "/path/to/my/keystore"
  7. Edit the existing config.properties file (or create a new file) stored in the <TOMCAT_HOME>/webapps folder and add entries for the ports used by Apache Tomcat (see Server Configuration for details). For example, add server.port.http=8080 or server.port.https=8443. The ports specified in config.properties must match the ports specified in the Tomcat configuration.
  8. Specify the appropriate license in the config.properties file at <TOMCAT_HOME>/webapps/config.properties (see Server Configuration for details).
  9. Start Tomcat (e.g., from <TOMCAT_HOME>/bin).
  10. Browse to http://localhost:8080/ (adjust the port if needed). The following message confirms that the application was installed correctly:

There are no deployments on this server. Cannot respond to this request: /.

By default, a workspace directory will be created in <TOMCAT_HOME>/webapps/ROOT.

Custom Status Message Configuration

You can enable Tomcat to set a custom HTTP status code message. This allows Virtualize to customize status messages in response headers if your responders set custom HTTP status message. Add the following property to the conf/catalina.properties file when deploying the WAR file:

org.apache.coyote.USE_CUSTOM_STATUS_MSG_IN_HEADER=true

See http://tomcat.apache.org/tomcat-6.0-doc/config/systemprops.html for additional information about setting this property.