Tomcat Tutorial for Metawerx Customers - v1.3
======================================================

Contents

1. Getting Started / The default ROOT application

2. Accessing the Manager Application

3. Installing a new simple Web Application using a
   set of folders and files uploaded by FTP

4. Installing a new Application using a WAR file
   (note: this method has problems, please use
   unpacked applications, using option 2 above).
   
5. Replacing the ROOT application with your own
   application.


===========================================================================
1. Removing the default ROOT application files
===========================================================================

When you start with a new site at metawerx, the default
Tomcat files will be installed on your site as a demonstration.

To remove these files, you must remove all of the files in
the private-cgi-bin/ROOT folder.

While this may seem a little time consuming, we believe it is
a good lesson in getting started with Tomcat in a hosted environment,
as it demonstrates the Manager Application, web.xml file and how
to reload an application after you modify it.

In recent versions of Tomcat, the index.jsp file is not the
actual file displayed when you first access your site.  Instead,
a pre-compiled version is used, which is located in the folder:

	/private-cgi-bin/ROOT/WEB-INF/classes/org/apache
	
It is necessary to remove these files completely before you
can replace the default Tomcat index page.

Before removing the files, download the following file:

	/private-cgi-bin/ROOT/WEB-INF/web.xml
	
Have a look in this file to see how the Tomcat index file
is set up (this is a good learning task).

Remove the /index.jsp entry from this file, and upload it
back to the site.

Next, access the manager application, using the following URL:

	http://your_tomcat_site/manager/html
	
After logging in, you will be presented with a list of the
currently loaded web applications.

Click "Reload" on the ROOT application (this entry is listed as "/")
This will release the locks on the index file precompiled classes.

You can now delete the WEB-INF/classes folder and begin to upload
your site.

Each time you change your site's class files, you will need to
reload the application in the same way.  First, upload your new
class files and jar files, then log in to the manager and reload
the application.

There are 3 types of Tomcat Log files which are listed in the
SiteWinder Tools Page.

Tomcat System Logs:
- under this option, you will find daily system log files specific
to your application (the files with dates), and the general system log
(systemX.log) which shows any errors that could not be identified as
belonging to a specific application.  Check each of these for errors
caused by jar files, or your application, or for security exceptions.

Tomcat AppLoader Logs:
- this log shows application stop, start and reload events from the
application server.  This will show problems relating to the loading
of applications, including which step the server got to before deciding
the application could not be loaded.

Tomcat Access Logs:
- these logs show hits for the pages on your tomcat application and
can be used for statistical purposes, or to investigate access to the
site.



===========================================================================
2. Accessing the Manager Application
===========================================================================

The manager application can be used to stop, start, remove,
add and reload your applications.

Each application has it's own folder and is accessed by
using a path with the same name as the application.

The manager application is a built-in application and is 
accessed as http://your-site-name/manager/html

The ROOT application is special, because it maps to your
domain name directly instead of to a folder.

The ROOT application is located in your FTP account as:
/private-cgi-bin/tomcat/ROOT

To access the manager application, go to
http://your-site-name/manager/html.  The username and password
are the same as your SiteWinder username and password.

Stop the "jsp-examples" application using the Stop link.  You
will notice that if you now try to run any of the Tomcat
examples, they will not respond.  Start it again by clicking
the Start link.  If you replace jar files in your application,
or wish to restart your application, use the Reload link.

Each time Tomcat starts, it will scan your /private-cgi-bin/tomcat
folder and automatically add each folder as an application.
For this reason, if adding new applications, always use a folder
name the same as your applications name.  (eg: do not add an 
application called MyApp2, with a path of /private-cgi-bin/tomcat/MyApp1,
otherwise this will be re-mapped when the server is next reset.



===========================================================================
3. Installing a new simple Web Application using a set of folders
   and files uploaded by FTP
===========================================================================

This example shows you how to create a new application folder
under your tomcat folder, and install it using the Tomcat Manager
Application.

a. Connect using FTP to your site

b. Change to the folder /private-cgi-bin/tomcat

c. You will see a series of applications already loaded as
   follows:
   
      webdav
      examples
      ROOT
      manager
      
d. Create a new folder named MyTest

e. Create a new file on your local machine named index.htm,
   containing the following text:
   
      Hello World
      
   Upload this file to your new MyTest folder
   
f. Access the manager application, and log in.
   http://yoursite/manager
   
g: You will see the following applications already loaded and
   running:
   
      /webdav
      /manager
      /examples
      /
      
   (the last one is the ROOT folder, which is mapped to a slash,
   meaning this application will load from the root of your URL,
   eg: http://yoursite)
   
h. Add the new application using the manager as follows:

	Path: /test
	War-URL: file:/[rootpath]/private-cgi-bin/tomcat/MyTest
	
	Substitute [rootpath] with your root file path.
	For example, if your root path was specified as ...
	
       d:/httpd/users/HKYOZSHHG_cust100
	
	.. then you would use the path:
	
	file:/d:/httpd/users/HKYOZSHHG_cust100/private-cgi-bin/tomcat/MyTest

	Hint: to find our your root path, check the Technical Details email
	sent to you when your site was created.  A copy of this email is also
	available on the SiteWinder Tools page.

i. Click [install], the screen should now show the following text:

    OK - Installed application at context path /test
    
j. Now test the application using your browser:

    http://yoursite/test
    
   You should see the contents of the index.htm file that you uploaded.

k. If the application did not load properly, see the Tomcat System Log
	and Tomcat AppLoader Log files on the SiteWinder Tools Page.



===========================================================================
4. Installing a new Application using a WAR file
===========================================================================

WAR files are difficult to maintain in a hosted environment,
and therefore we recommend that you unpack your applications
before uploading them to your metawerx site.

See sections 3 and 5 for information on using an unpacked application. 

The following notes apply if you really want to use a WAR file.

*NOTE: Make sure you make the WAR file with JAR or ANT and
not simply with WinZip.  WinZip does not seem to make valid
WAR files because the Manifest files are missing from the
archive.

*NOTE 2: Tomcat does not allow reloading of WAR files easily,
and often locks the WAR file preventing further updates.

a. Connect using FTP to your site

b. Change to the folder /private-cgi-bin/tomcat

c. You will see a series of applications already loaded as
   follows:
   
      webdav
      examples
      ROOT
      manager
      
d. Upload the WAR file to this folder.  For this example,
   we will assume the WAR file is named testing.war

f. Access the manager application, and log in.
   http://yoursite/manager
   
g: You will see the following applications already loaded and
   running:
   
      /webdav
      /manager
      /examples
      /
      
   (the last one is the ROOT folder, which is mapped to a slash,
   meaning this application will load from the root of your URL,
   eg: http://yoursite)
   
h. Add the new application as follows:

	Path: /wartest
	War-URL: jar:file:/[rootpath]/private-cgi-bin/tomcat/testing.war!/
	
	Substitute [rootpath] with your root file path.
	For example, if your root path was specified as ...
	
       d:/httpd/users/HKYOZSHHG_cust100
	
	.. then you would use the path:
	
	jar:file:/d:/httpd/users/HKYOZSHHG_cust100/private-cgi-bin/tomcat/testing.war!/

	Note that it is important to start the URL with jar:file:/
	and to end with !/
	
	eg: jar:file:[path to your war file]!/

i. Click [install], the screen should now show the following text:

    OK - Installed application at context path /wartest
    
j. Now test the application using your browser:

    http://yoursite/wartest
    
   You should see the default page (index.htm or another file) of the
   application contained in the WAR file that you uploaded.
   


===========================================================================
5. Replacing the ROOT application with your own application.
===========================================================================

To have your application work as the ROOT application,
upload the files to the ROOT folder.

If you simply replace "/" with your own application using the
manager application, this will be forgotten when the server is reset.

a. Log into the Manager application

b. Unload the root application
   - click Remove on the line that shows details for the "/" application
   - do NOT remove the Manager application

c. Add the new application as follows by uploading all your files
   to the ROOT folder, making sure you have a valid ROOT/WEB-INF/web.xml
   file.

d. Using the Manager application, use the following details to
   re-activate the new ROOT application.
   
	Path: /
	War-URL: file:/[rootpath]/private-cgi-bin/tomcat/ROOT
    
	Substitute [rootpath] with your root file path.
	For example, if your root path was specified as ...
	
       d:/httpd/users/HKYOZSHHG_cust100
	
	.. then you would use the path:
	
    For WAR files:
	jar:file:/d:/httpd/users/HKYOZSHHG_cust100/private-cgi-bin/tomcat/ROOT
	*NOTE: Tomcat does not allow reloading of WAR files correctly,
	and locks the WAR file preventing further updates.  Instead,
	please use unpacked applications only.
	
	For unpacked applications:
	file:/d:/httpd/users/HKYOZSHHG_cust100/private-cgi-bin/tomcat/ROOT

	Note that for WAR files, it is important to start the URL with jar:file:/
	and to end with "!/"
	
	eg: jar:file:[path to your war file]!/

e. Click [install], the screen should now show the following text:

    OK - Installed application at context path /
    
f. Now test the application using your browser:

    http://yoursite
    
   You should see the default page (index.htm or another file) of the
   application contained in the WAR file that you uploaded.