ACS-Java 3.4 Experimental

Building and installing instructions for Tomcat and Oracle
----------------------------------------------------------

0. Get a (free) copy of Tomcat up and running on your server.  
Tomcat is available through the Apache project:
http://jakarta.apache.org.  

0.1. Make sure you have access via JDBC to Oracle; default is through the
OCI driver (on the same server Tomcat), or through the "thin" driver
over TCP/IP.

1. Check the acs-java package out of CVS on ls (since you're reading
this file, you've presumably already done this) or untar acs-java.tar.gz. 

You should put the created acs-java directory into your Tomcat webapps
directory: $TOMCAT_HOME/webapps/acs-java.


2. Set your CLASSPATH environment variable.  It must include the
following JAR files (relative to the acs-java root, which should be
$TOMCAT_HOME/webapps/acs-java): 

% export CLASSPATH=WEB-INF/lib/PerlTools.jar:WEB-INF/lib/ecs-1.3.3.jar:$ORACLE_HOME/jdbc/lib/classes111.zip:$ORACLE_HOME/jdbc/lib/jndi.zip:$TOMCAT_HOME/lib/servlet.jar:$TOMCAT_HOME/lib/xml.jar:/path/to/mail.jar:/path/to/activation.jar

Description of each:

WEB-INF/lib/PerlTools.jar 	
the com.oroinc.text.perl pakage (ORO subproject of Jakarta, we use it for
regexps)

WEB-INF/lib/ecs-1.3.3.jar: from Turbine (subproject of Java Apache),
which provides us with some useful components (logging, a nice wrapper
to JavaMail, some HTML widgets).

$ORACLE_HOME/jdbc/lib/classes111.zip 
*or* classes12.zip (from your Oracle install)
$ORACLE_HOME/jdbc/lib/jndi.zip: 
Classes needed for the Oracle JDBC driver:

mail.jar 
activation.jar:
The JavaMail and Java Activation classes; not part of ACS-Java 
distribution, may be downloaded from java.sun.com

The Java Servlet API:
$TOMCAT_HOME/lib/servlet.jar 

Java XML classes:
$TOMCAT_HOME/lib/xml.jar

3.  Build the ACS Java classes, all of which are in package com.arsdigita.acs.

** NOTE ** If you are using the "thin" driver, you will need to 
edit the database URL in com/arsdigita/acs/db/Database.java before
recompiling.

Set your current working directory to WEB-INF/classes and issue the 
following commands:

% perl make-build.pl 
% javac Build.java

The first command invokes a perl script that builds a Java class,
Build.java, which does nothing but reference all the public classes in
com.arsdigita.acs.  Compiling Build.java will generate class files
for all of the public classes in com.arsdigita.acs.

4.  Edit WEB-INF/web.xml and WEB-INF/acs-parameters.xml to reflect the
configuration for your system.  *THIS IS IMPORTANT* because you may
get some very weird errors if you forget to edit these files. 

For WEB-INF/web.xml you must at least modify the IniFileName parameter
to point to your acs-parameters.xml file.

For WEB-INF/acs-parameters.xml you must at least modify the database
user and password.  In general look to modify any parameter value
that contains "your" in it.

5. Edit your server.xml file in $TOMCAT_HOME/conf.  Add a line in the
ContextManager section to map the acs-java webapp to the root context:

  <Context path="/" docBase="webapps/acs-java" debug="1" reloadable="true">
  </Context>

(debug is 0 or 1; reloadable is true or false)

Also, since we use /admin for ACS, comment out the line:
        <ContextInterceptor className="org.apache.tomcat.context.AutoSetup" />
This will prevent the Tomcat admin servlet from being served at
/admin.

Also edit the settings for your port, inet address, etc.  

** NOTE: by default, Tomcat will listen on *all* IP addresses available
on your machine.  You can change this by specifying an "inet" parameter
after the "port" parameter.  

	<Parameter name="inet" value="a.b.c.d"/>

6. Load the data model into the database user that you
specified in acs-parameters.xml.  

a. You should first create this Oracle user with the svrmgrl statement
 "create user service_name identified by password ..."

b. Load the data model with two scripts in the WEB-INF/install dir:
./load-geo-tables service_name/dbpassword
sqlplus service_name/dbpassword < load-data-model.sql

c. if you want site-wide search to work:
./load-site-wide-search service_name dbpassword ctxpasswd 
(where "ctxpasswd" is the password for the ctxsys user)

7.  Start or re-start Tomcat ($TOMCAT_HOME/bin/startup.sh).

8.  You should be able to view http://yourserver/register and get
a login screen.

9.  For more documentation on ACS and its features, please see
http://www.arsdigita.com/doc.










