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 10.1 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 the ROOT.xml file you just created 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/soavirt.keystore
    2. Specify "changeit" for all passwords when prompted. It is recommended for the keystore and <tomcat> alias passwords to be the same.

    3. The soavirt.keystore file will be created in the specified directory.

    4. Uncomment the SSL/TLS HTTP/1.1 Connector entry in the server.xml configuration file in the <TOMCAT_HOME>/conf directory and update it based on the example provided below. Be sure to update the certificateKeystoreFile attribute value.

      <Connector
 protocol="org.apache.coyote.http11.Http11NioProtocol"
 port="8443" maxThreads="200"
 scheme="https" secure="true" SSLEnabled="true">
         <SSLHostConfig sslProtocol="TLS"
                   certificateVerification="false">
            <Certificate certificateKeystoreFile="/path/to/soavirt.keystore"
                         certificateKeystorePassword="changeit" />
        </SSLHostConfig>
</Connector>
  8. Specify the ports used by Apache Tomcat in the config.properties file in the <SOAVIRT_HOME>/WEB-INF/ directory (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 (see Server Configuration for details).
  10. Start Tomcat (for example, from <TOMCAT_HOME>/bin).

  11. Browse to http://localhost:8080/ (adjust the port as 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 10.1 for your platform from http://tomcat.apache.org/.
  2. Extract the downloaded Apache Tomcat to a location of your choice (<TOMCAT_HOME>).
  3. Delete the contents of the <TOMCAT_HOME>/webapps/ROOT directory.
  4. Extract the contents of the WAR file into <TOMCAT_HOME>/webapps/ROOT.
  5. (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/soavirt.keystore
    2. Specify "changeit" for all passwords when prompted. It is recommended for the keystore and <tomcat> alias passwords to be the same.
    3. The soavirt.keystore file will be created in the specified directory. 

    4. Uncomment the SSL/TLS HTTP/1.1 Connector entry in the server.xml configuration file in the <TOMCAT_HOME>/conf directory and update it based on the example provided below. Be sure to update the certificateKeystoreFile attribute value:

      <Connector
 protocol="org.apache.coyote.http11.Http11NioProtocol"
 port="8443" maxThreads="200"
 scheme="https" secure="true" SSLEnabled="true">
         <SSLHostConfig sslProtocol="TLS"
                   certificateVerification="false">
            <Certificate certificateKeystoreFile="/path/to/soavirt.keystore"
                         certificateKeystorePassword="changeit" />
        </SSLHostConfig>
</Connector>
  6. Edit the existing config.properties file (or create a new file) stored in the <TOMCAT_HOME>/webapps/ROOT/WEB-INF directory 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.
  7. Specify the appropriate license in the config.properties file (see Server Configuration for details).
  8. Move the config.properties file to the <TOMCAT_HOME>/webapps directory. This will make the upgrade process easier in the future.
  9. Start Tomcat (for example, from <TOMCAT_HOME>/bin).

  10. Browse to http://localhost:8080/ (adjust the port as 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.

Additional Tomcat Configurations

Depending on your infrastructure and project requirements, your Tomcat server may require additional configuration.

URI Character Encoding

The SOAtest and Virtualize server supports Tomcat's relaxedPathChars and relaxedQueryChars properties. These properties enable you to specify which unencoded characters should be allowed in URI paths and URI query strings. You can specify the following characters: " < > [ \ ] ^ ` { | }

Refer to the Tomcat documentation for additional information: https://tomcat.apache.org/tomcat-9.0-doc/config/http.html

If you do not specify which characters are allowed, the Tomcat server will reject messages that contain one or more of the unencoded characters in URI paths and queries. 

Add the relaxedPathChars and relaxedQueryChars properties to the <Connector> element in the Tomcat's server.xml file and specify the characters you want to allow. If there is more than one <Connector> element, add the attributes to the elements with the protocol set to HTTP and HTTPS.

Example:

<Connector
   URIEncoding="UTF-8" allowTrace="true" connectionTimeout="20000"
   enableLookups="true" name="default" port="9080" protocol="HTTP/1.1"
   redirectPort="9443" 
   server="Parasoft Server"
   relaxedPathChars="&quot; &lt; &gt; [ \ ] ^ ` { | }"
   relaxedQueryChars="&quot; &lt; &gt; [ \ ] ^ ` { | }"
/>