Please note that this is only a brief description of the most common tasks you may have to perform to run some of our software, and may not reflect changes in the most recent Tomcat versions.
For the most up-to-date information on Tomcat configuration please also visit the project's web site.

1. Defining a web application

There are two ways to define a web application in Tomcat: by editing the configuration file, or by using the interactive Administration Tool.

1.1 Manually editing the configuration file

Modify <Tomcat home>/conf/server.xml: Define the jchem web application by inserting

<Context path="/jchem"
         docBase="<JChem home>"
         reloadable="true" >
</Context>

above the line

</Host>

Restart the web server.

1.2 Using the administration tool

Enter the Administration Tool of Tomcat at http://localhost:8080/admin
Enter username and password: (default: admin, admin)
Select Tomcat Server >> Service >> Host in the tree component.
Select Create New Context in the Available Actions list box.
Set Document Base and Path (e.g.: c:\jchem, /jchem)
Click Save and Commit Changes
Collapse and expand the Host node to check the new subnode: Context (/jchem)

Restart Tomcat

2. Jar files / classpath

Tomcat has designated directories for jar files. All jar files in these directories are automatically included into the server's classpath (at Tomcat startup).
NOTE: Tomcat never uses the system CLASSPATH.
Copy all files from <JChem home>/lib/ and the jar or zip file(s) containing the JDBC driver of your choosed database (and all other custom libraries) into Tomcat's lib subdirectory:

Tomcat 4.0: $CATALINA_HOME/lib
Tomcat 4.1 to 5.x: $CATALINA_HOME/shared/lib
Tomcat 6.0 and above: $CATALINA_HOME/lib

Restart Tomcat, so changes can take effect.

Note: Please always update these jar files when upgrading JChem.

3. Java options

3.1 Recommended JVM options

There are two important Java options which should be set for Tomcat.

Maximum heap size : this is the maximum amount of heap memory the Java Virtual Machine (JVM) is allowed to allocate. In the case of most JVMs, the default setting of the maximum heap size is 64MB. You can increase the maximum heap size of applications by setting the -Xmx JVM parameter. For example -Xmx1024m allows maximum 1GB (1024MB) heap to be allocated for the JVM.
Note: it is recommended to specify a considerably lower value than the amount of physical RAM in your system, so the operating system and other applications will also have enough space. Otherwise the swap memory of the operating system will be used, which can result in high disk activity, and reduced system performance.

Server mode : server mode instructs the JVM to perform more extensive run-time optimization. Right after startup it means a slightly slower execution, but after the JVM had enough time to optimize the code, the execution will be considerably faster.

3.2 Setting JVM options for Tomcat

Windows running Tomcat 5.5 and later : Go to the "Apache Tomcat x.x" folder in the Start Menu. Start the "Configure Tomcat".
Select the "Java" tab in the configuration dialog.
- Server mode: this is determined by the jvm.dll specified in the "Java Virtual Machine" text box. (One should not specify the "-server" or "-client" JVM option.)
  The server .dll is usually placed under a "server" directory in the JRE directory.
  For example: "C:\Program Files\Java\jdk1.6.0_07\jre\bin\server\jvm.dll".
  The complete SDK should be downloaded for this from Oracle, as the JRE installers only contain the "client" directory.
- Maximum heap size: The "Maximum memory pool" text box coresponds to the heap size limit.
  (If using this text box it is not needed to specify "-Xmx" Java option.)
- Advanced JRE options can be specified in the "Java Options" text area. Append your other Java options at the bottom of the option list.
Windows running Tomcat 4.1 or earlier : place the Java options into the CATALINA_OPTS environment variable. To do this, run Control Panel / System, select Environment Variables and create the CATALINA_OPTS variable, and set the desired option, for example "-server -Xmx400m".

Linux : place the Java options into the CATALINA_OPTS environment variable. For example: "-server -Xmx400m".

4. Setting session timeout

In web applications every user is identified by a session. The session holds information about the user. A typical example is an internet shop: the contents of your shopping cart is stored in a session.
To prevent the number of sessions to increase infinitely, they are destroyed after certain time of inactivity (time without changing the page) from the user. This is called session timeout. All user data stored in the session disappears (e.g. you have fill your shopping cart again).
Sometimes the default session timeout may be too low, especially when the user is expected to spend a lot of time on a single page. To increase the timeout value in Tomcat, please locate the following section in [Tomcat_home]/conf/web.xml:

    <session-config>
        <session-timeout>30</session-timeout>
    </session-config>

The timeout value is specified in minutes.
Restart Tomcat after modifying the file, so the changes can take effect.

5. Disabling persistence

In newer Tomcat versions (5.5 and above) the persistent storage of the context is enabled by default.
Since not all session objects used by JChem can be stored this way (they are not serializable ), this can result in annoying (though harmless) error messages in Tomcat's log during restart..
To disable persistence please edit <Tomcat home>/conf/context.xml, and uncomment the following line (by removing " <!–" from the start and "-->" from the end of the comment):

   <Manager pathname="" />

6. Common pitfalls

If the port (8080 by default) is already in use, Tomcat will not start. Typically Oracle's web server also uses port 8080.
Try to set a different port for Tomcat:
Please locate the Connector in <Tomcat home>/conf/server.xml with port="8080" setting, and modify the port value.
You can also change the setting in Tomcat's interactive administration tool (http://localhost:8080/admin) under Tomcat Server >> Service >> Connector. Select the connector with the HTTP type.
If one of the context paths points to a non-existing directory in the file system, Tomcat may not start.
If Tomcat 4.x is started from the Start Menu under Windows, CATALINA_OPTS has no effect. Please run <Tomcat_home>\bin\startup.bat.

Tomcat Configuration