This file is committed to svn as web_tool_dev/Readme.txt
See Admin.txt for information about adminstration of web_tool_dev on 8ball under the toolw account.

HOW TO CONFIGURE WEB_TOOL_DEV TO RUN ON a NEW HOST (or account).
====================================================================================================

1. We use one web server (i.e. one installation of tomcat) to run the web_tool_dev
site and several other servers to run the users' test versions of ngbw.  All the servers must be 
installed on the same host, under the same directory, where each installation has it's own subdirectory.  
All will be run as the same "user".  

	- Get IT (jd bottorof) to set up different ip addresses and virtual hostnames for each instance of tomcat.

	- Create a directory to house the tomcat installations, download tomcat, currently using 5.5.25,
	and expand the archive.  Rename the directory to the name of the first virtual host, then "cp -r"
	to directories for each of the other virtual hosts, where the subdirectories are named for
	the virtual host they'll run on.

	For instance, under the toolw account on 8ball I have 4 tomcat instances in ~/tomcat/apache-tomcat-5.5.25:

	total 4
	drwxr-sr-x   11 toolw    toolw         512 Jul 10 09:34 8ball-ngbw-1.sdsc.edu
	drwxr-sr-x   11 toolw    toolw         512 Jul 10 09:34 8ball-ngbw-2.sdsc.edu
	drwxr-sr-x   11 toolw    toolw         512 Jul 10 09:35 8ball-ngbw-3.sdsc.edu
	drwxr-sr-x   11 toolw    toolw         512 Jul 10 09:33 8ball-ngbw.sdsc.edu

	where 8ball-ngbw.sdsc.edu runs web_tool_dev and the others run the user's web applications.  Each
	of the 8ball-ngbw* subdirs is the root of a tomcat installation (i.e. they each have conf, webapps, logs, etc.
	subdirs).

	See bottom of this file for an explanation of why it must be set up this way. 

2. Configuring the tomcat instances.

	- For each tomcat instance, edit conf/server.xml.  Search for "Connector", and everywhere you find it
	add (or modify) 
		address="<virtual_host_ip_address>"
	line.

	- Search for SHUTDOWN and change the port and command. I used 8162 - 8165 and "SHUTDOWN-8ball-ngbw-1", etc
	as the commands on 8ball.  Use "netstat -a |grep <port>" to verify that you're choosing a port that isn't 
	already in use.

	- Comment out the AprLifecycleListener line because it causes some errors that are logged.

	- I think that's it.  We don't use the tomcat manager at all.  We do use the bin/shutdown.sh and
	bin/startup.sh to start and stop the web servers.  CATALINA_HOME must be set to the server
	you want to control when using these scripts, but my scripts that call them take care
	of that.  

	- Since you haven't yet configured the profile.xml and web_tool_dev scripts, you'll have to
	test out the tomcat instances by setting CATALINA_HOME and running bin/startup.sh manually.
	Try starting all the servers and stopping them one at a time.

3. Add an entry to web_tool_dev/profiles.xml.  

	- The only slightly tricky thing here is that the value specified for user.build.env property must match a 
	- profile in web/profiles.xml.  At the moment, there's nothing in web/profiles.xml that must be configured differently 
	- on different hosts, so you can use exactly the same user.build.env as used by the toolw_8ball entry in 
	- web_tool_dev/profiles.xml.

4. Create a properties file in web_tool_dev/src/main/resources that lists the virtual hostnames of the user's 
web servers and their urls.  See toolw_8ball.properties for exact format.  The name of this file must match the 
value of the "env" property that you add to profiles.xml for this build target, since web_tool_dev.properties
referencs the file as ${env}.properties.  Add the file to svn.

5. In .bashrc, or wherever, for the user who'll run the web user, set CATALINA_HOME to the tomcat installation
that will be used to run web_tool_dev (this is used in sake of web_tool_dev/tl.sh), and add web_tool_dev/bin.out 
to the PATH.

6. Modify web_tool_dev/tl.sh to set the correct -Denv=xxx value on the maven command.  Build but don't deploy
(cd web_tool_dev; sh tl.sh build).  Now you should be able to use the tomcat_control.sh script in bin.out
to stop/start the web servers.

7. Create a directory to store web_tool_dev's data on the shared filesystem.  You need to create a
structure like: 

web_td_home

    reference_copy
		To configure this directory copy bin.out/update_source.sh to reference_copy and run it to get a 
		copy of the sdk, web and documents.

	users
		everything under here is initialized by bin.out/setup_user.py when the user first logs in.

	userdb
		create userdb files under userdb; they just need to have a "password=<password>" line.

8. Deploy web_tool_dev: "sh tl.sh deploy"


SOME WHYS
====================================================================================================
web_tool_dev and users tomcat servers must share a filesystem because users servers create log files
that are read by web_tool_dev.  Actually, they must be on the same physical host because web_tool_dev
stops and starts the users' servers using their bin/shutdown.sh and bin/startup.sh scripts which
communicate with the tomcat process over a local tcp/ip port.

I'm not using jsvc like production's /etc/init.d scripts for controlling tomcat because it must be
run as root, which means the web_tool_dev site would have to be running as root to control the users'
tomcat servers.  It would be nice however to find a solution that didn't require specifying separate
SHUTDOWN ports for each server.


Project To Do List:
====================================================================================================

*) Don't let user log in again if he's got a prior session with a build that's still running.
*) Need to be able to cancel a build and kill all associated processes.
*) Make catalina.out from web run available to user.
*) Need a script that will show a different page when we want to bring down the web_tool_dev site.