This document details all steps needed to install the latest version of Zim 8 on Windows and Unix and provides additional steps to be checked after ZimWeb installation.
You should also refer to the Release Notes of all versions up to the current one for details about what is new in Zim 8.
Additional Instructions for IBM AIX 4.x and 5.x
Additional Instructions for HP-UX 11
Additional Instructions for Linux
Additional Instructions for Solaris
Additional Instructions for Unixware
Remarks on ZIMWeb Installation
Note: If you are installing ZimWeb, it will install the Java environment and Tomcat. However, this installation will not interfere with previous installations of any Java environment or Tomcat.
For a successful installation, you must have full administrator privileges on the local machine. If you are not sure, contact your system administrator.
1. Insert the Zim 8 software CD into your CD-ROM drive.
2. Zim 8 Setup automatically launches the Setup Wizard. If the Setup does not launch automatically, choose “Run” from the Windows Start menu and execute the setup.exe program in the CD Directory called Windows.
3. Follow the instructions as provided on the screen.
In order to run ZimExplore, you need the run-time part of .Net called Framework 1.1. If you don't have this software installed, ZimExplore will not work. To install it, just go to Microsoft .NET Framework Version 1.1 Redistributable Package and click in "Download".
If you installed ZimWeb on Windows, you can check that ZimWeb is running correctly by going through the following procedure:
Make sure that Zim Server is running with the example application database that was installed with ZimWeb. This database is located in ZimWeb\exampledb where your Zim software was installed;
Verify that the file ZimWeb\tomcat\webapps\ZII\WEB-INF\web.xml, located in the directory where your Zim software has been installed, contains the text "[ZIMWEB]". If so, change this text to the address of the directory where Zim software was installed. Example:
<param-value>[ZIMWEB]\conf\zimweb.cfg</param-value>
change it to the following:
<param-value>C:\Program Files\Zim Corporation\Zim\8.10\Zim\ZimWeb\conf\zimweb.cfg</param-value>
if you installed the Zim software in "c:\Program Files\Zim Corporation\Zim\8.10\Zim" (the default).
Similarly, change a second entry for "zimweb.log" as well, right below the above entry.
Start Tomcat by selecting Start | Programs | ZimWeb | Start Tomcat. You should see the database agents start on the Zim Integrated Server console.
Browse to the Tomcat Homepage by selecting Start | Programs | ZimWeb | Tomcat Homepage. If you see the Tomcat Homepage then Tomcat is functioning correctly.
Browse to ZimWeb Administration by selecting Start | Programs | ZimWeb | ZimWeb Administration. When requested for the username and password, enter "zimwebadmin" and "zimweb" (the default values) respectively. The ZimWeb Administration Tool should appear, and should be indicating that the Database Connections are running.
Stop and Start the database connections by pressing the appropriate button on the ZimWeb Administration page. Make sure that the connections are running for the next test.
Browse to ZimWeb Example Application by selecting Start | Programs | ZimWeb | ZimWeb Example Application. The ZimWeb Example Application page should appear. Check that each example runs correctly.
You can shutdown Tomcat by selecting Start | Programs | ZimWeb | Shutdown Tomcat. You should see the database agents terminated on the Zim Integrated Server console.
For a successful installation, you must have full administrator privileges on the local machine. If you are not sure, contact your system administrator.
1. Insert the Zim 8 software CD into your CD-ROM drive.
2. Change directories to the CD mounted directory and run the shell script "./Zim-8.xx.sh" where "xx" is the latest version of Zim 8.
3. Follow the instructions as provided on the screen.
To execute the Zim software, you first must set the UNIX environment variables. The commands used to set these variables vary depending on the shell being used.
Under the Korn Shell, Bourne Shell, or any POSIX Shell
Note: To make the settings consistent on a per-user basis, place these commands in the file “$HOME/.profile”.
1. Set the ZIM environment variable to indicate where Zim was installed (for example, /opt/zim8):
ZIM=/opt/zim8
export ZIM
2. Set the ZIMTERM environment variable to indicate the name of your terminal. (The example “build.ztcap” is installed with the software to give a starting point for configuring this file using the name ZIMTCAP):
ZIMTERM=build
export ZIMTERM
3. Add the directory where the Zim files are located to your default search PATH:
PATH=$PATH:$ZIM
export PATH
Under the C Shell
Note: To make the settings consistent on a per-user basis, place these commands in the file “$HOME/.cshrc”.
1. Set the ZIM environment variable to indicate where Zim was installed (for example, /opt/zim8):
setenv ZIM /opt/zim8
2. Set the ZIMTERM environment variable to indicate the name of your terminal (The example named “build.ztcap” is installed with the software to give a starting point for configuring this file using the name ZIMTCAP):
setenv ZIMTERM build
3. Add the directory where the Zim files are located to your default search PATH:
setenv PATH $PATH:$ZIM
1. At the OS prompt, type $ZIM/zimtcap and press Enter.
2. Follow the instructions as provided on the screen.
Under Zim 8.20, working directories (directories used by logged in users) are usually the same for many users, that is, when a user logs in, Zimserver creates a working directory with the default name 00001 (the first user) unless the options change this name (see Physical Structure of a Zim Database for more information).
When this user logs off, the next user to log in might use the same working directory name. Zimserver needs to clean this directory for the next user, but it cannot as it contains permissions from the precious user. As a result, the umask option has to be set appropriately by issuing:
umask 000
IBM AIX has no additional instructions to be followed.
HP-UX 11 has no additional instructions to be followed.
If you installed ZimWeb on Linux (not available on other UNIX platforms), you can check that ZimWeb is running correctly by going through the following procedure:
Make sure that Zim Server is running with the example application database that was installed with ZimWeb. This database is located in $ZIM/ZimWeb/exampledb;
Go to the $ZIM/ZimWeb/bin directory;
Start Tomcat by executing tomcat_startup.sh;
Browse to the Tomcat Homepage openning the Linux Web Browser and accessing http://localhost:8080. If you see the Tomcat Homepage then Tomcat is functioning correctly.
Browse to ZimWeb Administration openning the Linux Web Browser and accessing http://localhost:8080/ZII/servlet/ZIIAdmin . When requested for the username and password, enter "zimwebadmin" and "zimweb" (the default values) respectively. The ZimWeb Administration Tool should appear, and should be indicating that the Database Connections are running.
Stop and Start the database connections by pressing the appropriate button on the ZimWeb Administration page. Make sure that the connections are running for the next test.
Browse to ZimWeb Example Application openning the Linux Web Browser and accessing http://localhost:8080/ZII/example/index.htm .The ZimWeb Example Application page should appear. Check that each example runs correctly.
You can shutdown Tomcat by executing tomcat_shutdown.sh;
Solaris has no additional instructions to be followed.
Unixware has no additional instructions to be followed.
The ZimWeb installation includes not only ZimWeb, but also an Example Application, a Sun Java SDK and the Apache Tomcat Servlet Container. Together these are termed the "ZimWeb Reference Platform".
The "ZimWeb Reference Platform" is currently available for two environments: Windows and RedHat Linux.
The ZimWeb Reference Platform is straightforward to install on a Windows PC or on a redhat 7.x linux machine and is accomplished by the either Windows Installation or Unix Installation described above. It enables a Zim developer to start working with ZimWeb very quickly.
ZimWeb is a Java Servlet, which means that it can be executed on a variety of operating systems and Servlet Containers. ZimWeb has been tested successfully under various Java versions on various versions of Apache Tomcat on various platforms.
However, if you experience problems executing ZimWeb in another environment, then it is recommended that you attempt to reproduce the problem on one of the ZimWeb Reference Platform.
The ZimWeb Reference Platform consists of:
Directory j2sdk - contains the Java environment: Java2 SDK Version 1.4.1_01 for Windows or redhat Linux (it depends on the environment that you receive ZimWeb).
Directory tomcat - contains the Servlet Container: Apache Tomcat V4.1.18 LE. In particular, note that ZimWeb itself is installed at tomcat/wepapps/ZII, and that by default the Tomcat logs for ZimWeb are in the files tomcat/logs/localhost_ZimWeb_log..
Directory conf - contains the ZimWeb configuration file zimweb.cfg.
Directory logs - contains the ZimWeb log file zimweb.log.<date>.txt
Directory exampledb - A Zim database for the ZimWeb Example Application
Directory WAR - contains the ZimWeb Web Application Archive file ZII.WAR, for installing ZimWeb in other Servlet Container Environments.
The Java environment is unmodified from the original Sun distribution.
Installing web applications into Servlet Containers is typically done using a Web Application Archive or WAR file. This is a JAR (Java Archive) image of the application root, file extension ".war" and with a name matching the application root directory name.
The file [ZIMWEB]/WAR/ZII.war is a Web Application Archive consisting of ZimWeb plus the web portion of the ZimWeb Example Application.
When installing it, you will need to adjust the ZimWeb configuration parameters config-file and log-file (in Tomcat these are found in the file [TOMCAT_ROOT]/webapps/ZII/web.xml) as appropriate.
ZimWeb requires JAXP 1.1 XML Parsing and XSLT Processing facilities. Tomcat itself, and other typical Servlet Containers, require XML Parsing facilities. ZimWeb includes recent versions of the Apache Xerces and Xalan APIs to provide these facilities in the directory [TOMCAT_ROOT]/webapps/ZII/WEB-INF/lib/jaxp.
However, if different versions of XML Parsing and XSLT Processing facilities are available at the same time then there can be conflicts between them, leading to the Servlet Container and/or ZimWeb malfunctioning.
There are several choices to make the required facilities available and function correctly, including:
In the default installation environment, Java 1.4.x already includes these facilities. Hence the Tomcat 4.1.x LE version has been selected, which does not include these, and by default these facilities are not supplied in ZimWeb either, so there is no potential for conflict.
If installing into an environment using a Java version 1.2.x or 1.3.x then the Java environment does not include these facilities, so XML Parsing will probably be included in the Servlet Container environment e.g. in Tomcat non-LE versions you would find these in the directory [TOMCAT_ROOT]/common/endorsed. So for Tomcat non-LE versions, we recommend that you replace the files in that directory (xerces.jar and xml-apis.jar) with the files in the directory [TOMCAT_ROOT]/webapps/ZII/WEB-INF/lib/jaxp.
The ZimWeb Reference Platform includes the following scripts in the directory [ZIMWEB]\bin which can be used from the command line or in automated processes:
tomcat_startup.bat - Start Tomcat.
tomcat_shutdown.bat - Shutdown Tomcat.
zimwebadmin.bat - Send a command to the ZimWeb Administration Tool. The syntax is zimwebadmin.bat <command> [ <username> <password> ]. For example, zimwebadmin.bat conn-status zimwebadmin zimweb would check the status of the database connections if the username and password are set to their default values.
xmlproc.bat - A command line interface for XML processing. You can test XSLT, Page Templates and rendering with XSL-FO from the command line. Enter xmlproc.bat without any parameters for the syntax.
Start with Tomcat V4.1.18 LE.
Added the role "zimwebadmin", and the user "zimwebadmin" with password "zimweb" within that role, to the Tomcat configuration file [TOMCAT_ROOT]/conf/tomcat-users.xml. The original file is saved as [TOMCAT_ROOT]/conf/tomcat-users-ORIGINAL.xml.
Adjust the Tomcat configuration file [TOMCAT_ROOT]/conf/server.xml so that the ZimWeb application is logged separately from other applications into [TOMCAT_ROOT]/logs/localhost_ZimWeb_log.<date>.txt. The original file is saved as [TOMCAT_ROOT]/conf/server-ORIGINAL.xml.
Added the ZimWeb application directory at [TOMCAT_ROOT]/webapps/ZII. This includes the web portion (index page, stylesheets and page templates) of the ZimWeb Example Application.
Here are some additional details about installing ZimWeb.
ZimWeb is packaged as a WAR (Web Application Archive) file containing the following files:
|
Package |
Contents |
|
|
Home page for the ZimWeb Example Application. |
|
|
Page templates for the ZimWeb Example Application. |
|
|
XSLT style sheets for the ZimWeb Example Application. |
|
|
Configuration for the ZII servlets. |
|
|
Apache Avalon Framework (required by Apache FOP). |
|
|
Apache Batik SVG processor (required by Apache FOP). |
|
|
Apache FOP XSL-FO processor. |
|
|
Sun JIMI (required by Apache FOP). |
|
|
JFOR XSL-FO processor for RTF. |
|
|
Apache Logkit (required by Apache FOP). |
|
|
ZimWeb itself. |
|
|
Apache Xalan XSLT processor (in case this is not part of your Java or servlet engine environment). |
|
|
Apache Xerces XML parser (in case this is not part of your Java or servlet engine environment).. |
|
|
XML APIs for XML parsing and XSLT processing from Apache Xalan (in case this is not part of your Java or servlet engine environment).. |
The ZimWeb file zii.jar contains classes in the following
Java packages:
|
File |
Description |
|
|
The original ZimCGI, with a few modifications |
|
|
Zim JDBC Driver |
|
|
The main ZimWeb classes |
|
|
Utility classes for ZimWeb |
There are two servlets in ZimWeb which you can invoke:
|
Servlet |
Description |
|
|
The ZimWeb
itself. |
|
|
The ZimWeb
Administration servlet allows you to administer ZimWeb, including
checking its configuration parameters, starting and stopping Zim
Server agent connections, and checking and clearing the XSLT style
sheet cache. |
The ZimWeb jar file also contains the ZimCGI
Server - equivalent to the zimcgis.jar file. You may wish to use
the zii.jar for both
purposes to avoid problems with multiple versions on your Java
CLASSPATH.
Before installing ZimWeb, make sure you have a working Tomcat installation, consisting of, say, Java 1.4.x plus Tomcat V4.1.x LE. N.B. You choose a Tomcat LE version with Java 1.4.x because Java 1.4 includes XML processing facilities which would otherwise be duplicated in Tomcat.
One way of installing the ZII on Tomcat V4.1.x is as follows:
Place the ZimWeb WAR package file ZII.war in the directory [TOMCAT_ROOT]/webapps.
Remove any directory [TOMCAT_ROOT]/webapps/ZII if it already exists e.g. if you have installed a previous version of ZimWeb.
Start Tomcat. This automatically unpacks the contents of the file ZII.war into the directory [TOMCAT_ROOT]/webapps/ZII. It most likely won't connect successfully to any Zim database because the ZimWeb configuration file requires adjustment.
Stop Tomcat.
Adjust the ZimWeb configuration file [TOMCAT_ROOT]/webapps/ZII/web.xml as appropriate. In particular, you should ensure that the config-file and log-file parameters are set correctly. Note also that it secures the ZimWeb Administration servlet so that it can only be accessed by users in the role zimwebadmin - see the next step for how to add such a user.
Adjust the Tomcat configuration file [TOMCAT_ROOT]/conf/tomcat-users.xml to add a user in the role ziiadmin that can administer ZimWeb e.g. to add a user zimwebadmin with password zimweb you could do this by adding lines such as these into it:
<?xml version='1.0' encoding='utf-8'?>
<tomcat-users>
...
<role rolename="zimwebadmin"/>
...
<user username="zimwebadmin" password="zimweb" roles="zimwebadmin"/>
...
</tomcat-users>
[TOMCAT_ROOT]/conf/server.xml so
that the ZimWeb application is logged separately from other
applications into [TOMCAT_ROOT]/logs/localhost_ZII_log.<date>.txt.
You can do this by adding the following context:
...
<Host ...>
...
<!-- ZII Context -->
<Context path="/ZII" docBase="ZII" debug="0"
reloadable="true" crossContext="true">
<Logger className="org.apache.catalina.logger.FileLogger"
prefix="localhost_ZimWeb_log." suffix=".txt"
timestamp="true"/>
</Context>
...
</Host>
...
Important! You must ensure that ZimWeb's enviroment includes XML parsing and XSLT facilities, and that there are no conflicts amongst the XML processing facilities which may be supplied with your Java and Tomcat environments and ZimWeb. For example:-
If you are running a Tomcat LE version using Java 1.4 or higher, then the Java environment already includes XML parsing and XSLT facilities, and no action is required.
If you are running Tomcat non-LE version using a Java version prior to 1.4, then you will have to copy the files supplied with ZimWeb in the WEB-INF/lib/jaxp directory (xalan-xxx.jar, xercesImpl-xxx.jar and xml-apis-xxx.jar) into the [TOMCAT_ROOT]/common/endorsed directory, replacing any versions of those files which came with you version of Tomcat.
Restart Tomcat. It will automatically start the Zim database connections if it is configured to do so.
The above should get you started. You will probably want to configure Tomcat further - particularly by adjusting the file [TOMCAT_ROOT]/conf/server.xml - before installing into a production environment.
N.B. Make sure that you do not have the
zimcgis.jar file
from the ZimCGI in your Java CLASSPATH, otherwise they may
interfere with one another.
Tomcat can be configured to run both standalone, or in conjunction with other web servers like Apache.
If after reading the above you which to install ZimWeb in another manner, or on another Java Servlet engine, and you run into difficulties we recommend you read and understand the documentation for your Java Servlet Engine.