|
Home
Installation
Indexing
Configuration
Purchasing
|
|
This page is for information purposes only.
It is not a recommendation to use this Java servlet engine or application server.
Please consult the supplier's documentation for full installation information
and details of how to deploy and configure servlets such as Spy-Server.
Introduction
Spy-Server is a Java servlet.
It is a program that must be run by a Java servlet engine on a web server,
with its output viewed in a browser.
Java application servers usually have built-in support for Java servlets.
Alternatively, a Java servlet engine can be installed and connected up to an
existing server.
Please refer to these pages for more information:
Servers page for details of application servers and servlet engines.
Installation guide for application servers and servlet engines.
Deployment overview for Spy-Server.
Please consult our Getting Started Guide for an overview
of how to obtain Spy-Server, set up your server, install and configure Spy-Server.
Get the Spy-Server software from the Download page.
|
|
Apache Tomcat
Apache Tomcat is a free servlet engine for use primarily with the Apache server
on many platforms -
available from jakarta.apache.org.
Tomcat 3 and earlier supports the servlet specification JSDK 2.2;
Tomcat 4 supports the newer JSDK 2.3.
Tomcat includes a servlet web server so it does not need to be connected
to a web server when testing.
Deploying Spy-Server in Tomcat is easy because Tomcat will install the Spy-Server
Web application archive (WAR) automatically.
Some aspects of Tomcat and Spy-Server can be configured using the Tomcat
Server Administration and Web Application Manager screens.
However a significant amount of configuration can only be
done by editing configuration text files manually.
Once Spy-Server is installed and the work init parameter
set to your desired work directory, then all Spy-Server configuration can be done using
the Spy-Server online configuration screen.
Spy-Server Deployment, Configuration and Usage Instructions
Overview of the instructions:
- Install Spy-Server.
- Find the Spy-Server URLs and display the Spy-Server configuration screen.
- Check the work directory location.
If necessary, change the work init parameter
and restart Spy-Server.
- Run test searches of the Spy-Server documentation
and confirm that result pages are shown correctly.
- Index your own site from the Spy-Server configuration screen
Indexing section.
Set Spy-Server to use your search database index.
- If desired, set up word highlighting
for searches of your web site.
Further instructions:
Installing Spy-Server
Installing the Spy-Server web application SpySrv50.war is usually called
deployment.
There are four deployment options:
- Automatic
- Simply copy the Spy-Server Web Application
SpySrv50.war
into the Tomcat webapps sub-directory.
(In some cases, you might have to put SpySrv50.war in the
webapps/your-domain/ sub-directory.
Ask your webmaster or ISP for advice.)
- If Tomcat is not running, start it now.
The WAR file is automatically installed
into directory
webapps/SpySrv50.
- If Tomcat is running, then it should shortly detect the
new WAR file, and install it into directory
webapps/SpySrv50.
If not, try installing Spy-Server using the Tomcat Web Application Manager.
Or failing that, stop and restart Tomcat.
- Spy-Server should now be installed with context path
/SpySrv50.
- Web Application Manager user interface
The Tomcat Web Application Manager user interface is usually found at a URL like this:
http://localhost/manager/.
The Manager lets you control all servlet applications and install new servlets.
In Tomcat 4.1.12 we could not get the Install option to work.
- Web Application Manager commands
You can issue commands directly to install and control servlet applications.
For example, the following URL would install Spy-Server on context path /spy
with the Spy-Server WAR at D:\tomcat4\webapps\SpySrv50.war on
a Windows system:
http://localhost/manager/install?path=/spy&war=jar:file:/D:/tomcat4/webapps/SpySrv50.war!/
See the Tomcat 'Manager App HOW-TO' instructions for more details.
- If all else fails
In some cases, you may have to set up Spy-Server manually:
- Copy the runtime file
web.xml into the server WEB-INF
directory.
- Copy
SpySrv50.jar into the server WEB-INF/lib directory.
- Restart your Java VM
- The Spy-Server context path and therefore its URL will depend on your server configuration.
Spy-Server URLs
The following URLs should now be available
(assuming that Tomcat is running on the default web server port of 80, and the context path is /SpySrv50):
Some older versions of Tomcat have slightly different URLs for the Spy-Server search page and
configuration screen, eg:
http://localhost/SpySrv50/servlet/SpyServer
http://localhost/SpySrv50/servlet/SpyServer?config=now
Check the work directory location
Before you start testing Spy-Server, it is important to check that the
Spy-Server work directory is in a suitable location.
Spy-Server uses a work directory to store all its configuration information
and search database files. It is important that this directory is secure from
unwanted direct access, while still being available to Spy-Server.
It is also a good idea to make sure that this directory is not wiped accidentally,
eg if you update the Spy-Server runtime to a newer version.
Finally, it is also a good idea to backup the contents of the Spy-Server work directory regularly.
Spy-Server makes a directory called SpyData when it starts.
For most Tomcat installations, this is a sub-directory of webapps/SpySrv50,
ie webapps/SpySrv50/SpyData/.
Although this location is fine, its contents will be visible to browsers and
might be lost if you update the Spy-Server runtime,
so it might be best to change the work directory.
(For Web Application Manager command installation, the Spy-Server work directory
might be in the Tomcat bin directory.)
- If you want to change the work directory, then first create a suitable directory.
In the Spy-Server configuration screen General section, enter this location in the
"Test work directory" field and press the "Make Changes" button.
Spy-Server checks that this directory is usable and reports back to you.
- Assuming your directory location is fine, you then need to set the Spy-Server
work init parameter
to this value. This ensures that Spy-Server uses this directory
even if Tomcat or Spy-Server is restarted.
Changing init parameters
In Tomcat, the only way to change an init parameter is to edit a file
called web.xml in the webapps/SpySrv50/WEB-INF directory.
Find the work init-param and put your directory name in between the
param-value tags (which is empty by default).
For example, to set the work init parameter to
D:\search, use the following (with the changes highlighted):
<init-param><param-name>work</param-name>
<param-value>D:\search</param-value></init-param>
- Restart Spy-Server in the Tomcat Web Application Manager
(or stop and start Tomcat).
- Check that the Spy-Server configuration screen shows your chosen work directory.
Test Search
Check that you can search the Spy-Server documentation correctly, as follows:
- Browse to the Spy-Server localised search page, eg
http://localhost/SpySrv50/search.
(Or http://localhost/SpySrv50/servlet/SpyServer
on older versions of Tomcat.)
- Enter some search text, eg engine and click on "Search".
- The first 10 hits are displayed. Click on a hit and check that the result page is displayed
correctly in the browser.
If the hit page is not shown correctly, then you probably need to alter the
Additional Base URL setting in the configuration screen Searching section.
If you are using an older version of Tomcat, then you will almost certainly
need to change the Additional Base URL from its default value of
doc/ to
../doc/.
Index your own site
Follow the general Getting Started instructions
to index your own site to build a search database and start searching.
Test Word highlighting
See the Word highlighting instructions
for details of how to set this up for HTML pages shown in Internet Explorer 4+.
Additional Tomcat Instructions
Memory
Spy-Server's memory usage will depend on the size of your search database.
The Sun JVM defaults its maximum size for the memory allocation pool to 64MB;
this could cause "Out of memory" errors in Spy-Server.
If you want to increase this value then set the -Xmx parameter in the java command that runs Tomcat,
eg -Xmx256M to set the maximum pool size to 256MB.
Probably the simplest way to set this parameter is to set the following environment variable
(in Windows use Control Panel+System+Advanced+Environment Variables):
CATALINA_OPTS
-Xmx256M
I think that this option applies to all ways of running Tomcat.
The main batch files that start Tomcat are in the installation directory "bin" sub-directory:
file "startup.bat" or "startup.sh" calls "catalina.bat" or "catalina.sh" to run Tomcat.
Windows systems may have a short-cut on the desktop to run Tomcat;
you could add in the memory parameter there instead.
I think that Tomcat can also be run automatically at startup as a service on Windows system - I am not sure how this is done.
Log files
By default, Tomcat has logging switched on, producing log files in its logs
directory. Log files are produced for each day, eg named localhost_log.2002-11-07.txt.
If Spy-Server logging is enabled in the Spy-Server Configuration screen General section
then it produces log output to the Tomcat log file. Each line of the log file
is prefixed with a date-time stamp and "SpyServer", eg:
2002-11-07 15:45:13 SpyServer: Spy-Server 5.00, 7 November 2002. init JSDK 2.3
Note that all the output from an indexing run can be displayed in the Configuration screen
Indexing section by clicking on an indexing's Details
i icon.
This "Last run output" is also included in the (optional) email report.
Startup issues
It is important that Spy-Server is running if you want it to reindex your site regularly.
A scheduled indexing run may be missed if Spy-Server has not been started and run.
If the servlet engine stops and restarts then Spy-Server might not be restarted automatically.
The Tomcat Manager may show Spy-Server as running, but in fact it has not been started.
Any access to the Spy-Server servlet will start Spy-Server.
To ensure that a reindex runs every day, for example,
then use some tool to schedule a regular 'ping' of a Spy-Server URL,
ie access a Spy-Server page eg the Spy-Server localised search page
http://localhost/SpySrv50/search.
Remember to take into account any time zone differences.
Note that accessing the Spy-Server welcome page will usually NOT start the servlet, eg:
http://localhost/SpySrv50.
Updating Spy-Server
If you receive a new version of Spy-Server then you will need to install it.
Before you proceed, make a backup copy of your Spy-Server work directory contents
in case it is accidentally lost.
Different versions of Tomcat seem to have different characteristics.
- In Tomcat 4.1.12 updating is hard:
- The best way is to unzip the new
SpySrv50.war in a temporary directory
and copy file WEB-INF/lib/SpySrv50.jar into directory
webapps/SpySrv50/WEB-INF/lib/. Then click Reload in the
Tomcat Web Application Manager (or restart Tomcat).
- Alternatively, you could uninstall Spy-Server and install it again
using the new version of
SpySrv50.war. Be careful to save
your Spy-Server work directory if you use this method.
You may need to change the work init parameter
again.
- Updating older versions of Tomcat is easier:
- Put the new
SpySrv50.war in the Tomcat webapps directory.
- Simply press the Reload button in the
Tomcat Web Application Manager to update the Spy-Server runtime
without destroying the Spy-Server work directory.
Uninstalling Spy-Server
Follow these steps to uninstall Spy-Server completely:
- First stop Spy-Server in the Tomcat Web Application Manager (or stop Tomcat itself).
- Delete the file
webapps/SpySrv50.war.
- Delete the
webapps/SpySrv50 directory and all its sub-directories.
- If your Spy-Server work directory was elsewhere, then delete that as well.
|
