This chapter provides sample instructions for deploying Virtualize Server to Apache Tomcat. See Upgrading Virtualize Server for Apache Tomcat Deployments for instructions on updating Virtualize Server.

The first example in this chapter 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 Configuring Virtualize Server 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 Configuring Virtualize Server 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: 

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 Configuring Virtualize Server 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 Configuring Virtualize Server 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:

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 Virtualize Server 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.