|
|
|
|
Note: Tomcat is not a Unanet supported product. Unanet can be run with a number of Servlet Engines. This information is included for your convenience only. Please refer to the Tomcat site for detailed platform configuration and tuning recommendations.
The material on this page is intended to assist you with configuring Tomcat for use with your Unanet system. The topics covered on this page include:
Once you have installed Java, you may proceed with the installation of Tomcat. Tomcat can be obtained at http://tomcat.apache.org/index.html.
We would strongly recommend that you do not attempt to use any alpha versions. Saving the file to disk as a zip seems to give the best results.
Note: Depending on what other services you have running on your machine, you may need to change the default ports that Tomcat uses. For example, some services in Oracle may use a series of ports starting 8080 -- this will conflict with the default Tomcat installation.
Some versions of Tomcat have reportedly reacted differently with regard to recognizing the Java installation -- so to be safe, set up the JAVA_HOME environment variable before executing the install.
To install Tomcat, simply execute the install package and follow the on-screen directions. Unanet recommends that you choose to install Tomcat as a service in Windows.
The install process should ask for the manager UserID and Password, make sure you note what those are -- you (or whoever will be responsible for future upgrades) will need them later to upgrade your unanet warfile.
Installation Directory -- Avoid Spaces
When determining your Tomcat installation directory (and path), a best practice is to avoid the use of spaces and use all lower case letters. Spaces in the path have resulted in interfacing difficulties (ie when interfacing with IIS Connector).
Good example: c:\tomcatThe following variables need to be set in your system.
Variable Name: TOMCAT_HOME
Example Value: c:\tomcat
Variable Name: JAVA_HOME
Example Value: c:\jdk1.8
Variable Name: Path (The system’s Path – should already exist as an environment variable)
Example Value: c:\jdk1.8\bin (place this variable at the end of your system’s path)
How you will accomplish this will vary depending on your operating system (though you'll likely start by looking under "My Computer >> Properties"). Of course, your installation locations may be different -- the default of c:\ is used here as an example.
Check out the Performance Tuning Tips page for more information about Tomcat tuning.
You should modify the default unanet.properties file located in the ../unanet/config (depending on your installation location), to set the unanet.log.output property. Taking this step will allow for improved log management and troubleshooting. You can uncomment the default property and change the example value to your specific directory setting.
#unanet.log.output=c:/Program Files/Apache Software Foundation/Tomcat/logs/unanet_runtime.log
To test if the servlet engine is working properly open a browser, and enter:
<machine.domain name>:8080 or <ip Address>:8080
Navigate to <machine.domain.com:8080/manager/html and make sure you can log into the Tomcat manager. You will need to do this later when deploying and upgrading your Unanet warfile.
There are a number of java parameters that will need to be tuned in order for Unanet to function properly.
Use the Tomcat Monitor Launch icon in the system tray to edit the properties.
If the icon does not appear in your system tray, you can launch the utility from the Tomcat Start menu (or by executing Tomcat7w.exe in Tomcat's bin directory).
If running with Java 7, you will need to add the following line to the Java Options section:
-XX:MaxPermSize=256m
For Java versions beginning with Java 8, this option is obsolete. Java 8 handles permgen differently and performs its own dynamic management.
For any Java version, you will need to ensure you have a minimum value in the following fields (they can be higher):
Initial memory pool -- minimum of 128 MB
Maximum memory pool -- minimum of 512 MB
** Note that how you set these parameters will be somewhat dependent on the physical memory you have installed on your server. If you have adequate memory available on the server you may want to consider a higher maximum (e.g. 512, 1024, etc). Should you receive the java.lang.OutOfMemoryError message after the recommended settings were applied, you will need to further increase the maximum size of the Java memory allocation pool.
If this tool is not available to you on your platform, you would need to set the following environment variable then restart Tomcat:
CATALINA_OPTS="-Xmx512M -Xms128M"
After modifying these properties, you will need to restart your Apache Tomcat service (which can be accomplished using the Start / Stop on the General tab).
Note: There are several different ways to configure servlet information in Tomcat. Below are the methods that we have found work best with each supported version. If you are an experienced Tomcat shop, you can use the method that works best for you. If not, please use the methods below so that Unanet can better support your installation.
First you may need to edit the unanet.xml file (located in the main Unanet directory which was created when you installed the Unanet application). The contents of this file is shown below along with some notes about which parts you need to be concerned with. If you have a completely standard installation (Unanet installed in c:/unanet), you will not need to modify this file at all.
Note: based on the OS you're running, you'll need to refine the details in the path with respect to specific directory syntax and usage of slashes (ie linux: /home/unanet or windows: c:/unanet)
<!-- Context configuration file for u71test -->
< Context path="/unanet" docBase="c:/unanet/unanet.war" unpackWARs="true" override="true">
<Parameter name="properties" value="c:/unanet/config"/>
< /Context>
The path will be used when you access the Unanet system from a web browser. For example, in the above example (the default configuration), you will access your Unanet system with the following URL: http://machine.domain:8080/unanet -- with the "/unanet" being the path. Unless you want your path to be something other than "/unanet", you do not need to modify this value.
The docBase refers to the actual unanet warfile. It is placed by default in the main Unanet directory when you install the Unanet application. You will need to modify this if your Unanet installation was something other than "c:/unanet". Remember to pay close attention to the drive letter if it is different from the default "c:".
The value of the properties parameter should point to the properties directory for your Unanet system. This is the directory with, among other things, the database.properties file and license.properties files that you've already customized.
Important Linux Note: Support for generating graphical charts in Unanet is accommodated via the jFreeChart jars. If Unanet is being run on a Linux/Unix server that does not have X11 installed and running, you will need to add an additional Java JVM property to support charting. Check out Linux/Unix Graphics Support for additional information.
Now you will need to tell Tomcat to deploy the Unanet application. For this, you will need to access the Tomcat Manager again. Log into the Manager application (using the id and password you created when installing Tomcat). In the Deploy section, you will need to fill out the "Deploy directory or WAR file located on server" section. Please note that you must be located on the same machine that Unanet was installed on (and that Tomcat is on). Below is a screen shot of the page along with the values you need to use for a standard installation. Keep in mind that if you are using a non-standard context-path or unanet install location, you will need to change those values accordingly.
Once you have filled out the three fields, click the Deploy button. Depending on the speed of your system, this process may take several minutes. When it is done, the screen should refresh and you will see the appropriate message in the Message section along with the Unanet application listed in the Applications section (see screen shot below).
You may want to write down the values you used in the three fields for later use. Depending on your version of Tomcat, you might need to use the exact same procedure to redeploy new warfile updates.
The default Tomcat installation includes its own internal Apache web server. If you have a need to configure your system to utilize IIS as the web server, additional documentation and necessary configuration files can be retrieved from our Support Site. After signing into our Support site, click on the Downloading distribution files link. This link explains how to access the distribution site. From the distribution site, click on the Doc & Training tab. Under the Additional Documentation section, you will find the Tomcat/IIS zip file. This file contains additional instruction and necessary configuration files.
If you are experiencing difficulties contact Unanet Customer Support for assistance.
Step 6 -- Test and log into the Unanet Application
Once your Servlet Engine has been installed and configured, you are ready to move on to Step 6 -- Testing and Logging into your Unanet System.
