Oscar Installation Under Debian Sarge

Note that the following installation notes were not for a "from scratch" installation. These were assembled as part of downloading and building new .war files from CVS, modifying configuration files to suit Debian and local context, and from dropping and recreating the database table structures in MySQL.

Other notes:

• using testing packages including tomcat5
• some install notes under Ubuntu Linux using original(?) Oscar instructions

Apache, Tomcat, Java

The Java Runtime Environment (package: j2re1.4) and Java SDK (package: j2sdk1.4) were installed via Blackdown (www.blackdown.org) project DEB packages. As well, the “j2se- common” package was installed with APT via regular Debian mirrors.

The “tomcat4” package was then installed via APT. In the configuration file /etc/default/tomcat4, the JAVA_HOME variable was set to /usr/lib/j2se/1.4/.

Note that for more recent versions of Oscar we had had to update tomcat4 to version 4.1.31-3.

An SSL certificate was generated for Tomcat’s usage. However, we didn't use this SSL cert, as we run Apache in front of Tomcat, using Apache’s SSL functionality.

Apache 1.3.31-2 was installed via APT (packages: “apache”, “apache- common”, “apache-utils”). Apache’s mod_ssl was also installed (package: “libapache-mod-ssl”), as well as mod_jk (package: “libapache-mod-jk”).

The mod_ssl key in use resides in /etc/apache/ssl.key/server.key. The key’s pass phrase is (use your own), which is supplied to the server by this script: /etc/apache/passphrases/default.

All Tomcat connectors were disabled (in server.xml), save for an AJP13 connector on port 8009. The AJP13 connector’s “redirectPort” value was set to “443”. With the appropriate security-constraint setting in an application’s web.xml file, Apache/Tomcat will force all HTTP connections to be SSL-secured.

OSCAR’s properties files were placed in /etc/tomcat4, and this location was specified in OSCAR’s web.xml file. As well, a policy change was required in /etc/tomcat4/policy.d/04webapps.policy to allow OSCAR to access various Java values (e.g. user.home). These are outlined further below.

Apache’s mod_jk was setup to redirect OSCAR page requests to Tomcat’s AJP13 connector via /etc/apache/mod_jk.conf. This is also shown below.

Apache is configured to allow HTTP connections on port 80, and HTTPS connections on ports 443 and 8443.

Notes:

1. use log files to diagnose for errors /usr/share/tomcat4/logs
2. Tomcat needs to be sufficiently recent (apt-cache policy tomcat4, we have installed 4.1.31-3) to contain or install catalina-ant, on which ant depends to build Oscar. While tomcat can compile the jsp files on the fly there would still remain the servlets. While some installations had originally employed a combination of downloaded war files plus eclipse for apache, ant is now required.
3. Under Debian, several subdirectories of usr/share/tomcat4 are symlinked to name-alikes in /var/lib/tomcat4/conf
4. Within tomcat's usr/share/tomcat4/conf/server.xml
   • election to port forward via 8443 requires the insertion, into AJP connection script (before its end), of redirectPort="8443"
   • comment-out tomcat-docs webapp because it is not installed when installing tomcat:

<!-- Allow symlinks for the tomcat-docs webapp. This is required in
the Debian packages to make the Servlet/JSP API docs work. -->
 <!--Context path="/tomcat-docs" docBase="tomcat-docs" debug="0">
    <Resources className="org.apache.naming.resources.FileDirContext"
               allowLinking="true" />
 </Context-->

CVS Oscar

Notes:

• Oscar's "rolling release" of code can be a bit of a crapshoot unless the person updating knows to specify in the CVS command a date constraint that is known to be bug-free
• web-INF folder contains non-jsp stuff, webxml file
• /classes/src contains the application source code in .java files.
• "locate" command handy to find files

Ant (v 1.6.2-2)

> apt-get search ant | grep ^ant (^ = start of line char)
> apt-get install ant
> ant --help

--> change into oscar cvs' /build directory
--> run ant
/build> ant
--> creates two web archive files in build/tmp
   OscarDocument.war and oscar.war
--> copy into usr/share/tomcat4/webapps
> cd build/tmp
> cp *.war /var/lib/tomcat4/webapps

verify permission and ownerships for server.xml and web.xml

Make sure these are correct, depending how the files had been installed or modified:

> ls -la /etc/tomcat4
-rw-r--r--    1 tomcat4 nogroup  5566 2006-05-15 12:42 server.xml
-rw-r--r--    1 tomcat4 nogroup 35704 2006-05-15 12:24 web.xml

chgroup nogroup server.xml
chgroup nogroup  web.xml
chown tomcat4 web.xml server.xml
chmod u=r,w

grant permission to java's security files

in /etc/tomcat4/policy.d/04webapps.policy add the following line.

//all permissions for all webapps:
permission java.security.AllPermission;

edit the downloaded install/oscar_mcmaster.properties file

edit for following properties to match local settings:

db_name = oscar
db_username = oscar
db_password = xxxPASSWORDxxx
db_selectuser = oscarselect
db_selectpassword = xxxPASSWORDxxx

billregion=BC
visitlocation = 00|VANCOUVER
logintitle = Dr J Busser: Test server

change all tomcat directory (/usr/local/tomcat/) to /usr/share/tomcat4/ (about 8 occurrences)

rename properties file and copy to tomcat location

> cp oscar_mcmaster.properties oscar.properties
> mv oscar.properties /usr/share/tomcat4

edit /etc/apache/mod_jk.conf for context for each webapp

#/oscar Context:
JkMount /oscar worker1
JkMount /oscar/* worker1

#/OscarDocument context
JkMount /OscarDocument worker1
JkMount /OscarDocument/* worker1

run database scripts & do any clean-up

• run oscarinstall.sql, oscarinstall_bc.sql, oscardata...sql

mysql> show databases;
select * from security;
--> displays current entries

select * from user;

• clean-up e.g.

delete * from scheduleholiday;
delete * from ctl_billingservice where servicetype = "AN";
delete * from ctl_billingservice where servicetype = "GP";
delete * from ctl_billingservice where servicetype = "OB";

restart apache/tomcat

The normal OSCAR (fedora) instruction to restart tomcat under the webapps directory does evidently not really apply with the Debian version of tomcat running as a daemon etc/init.d/

Inside my root directory are kept some "restart" scripts, with restartweb copied into etc/apache, this restarts apache and tomcat. Colleagues with sudo access, though they cannot change into the /root directory to view or directly run the scripts, can identify and run the scripts from the command line:

$ sudo ls -all /root | grep "restart*.*"
-rwxrw----   1 root root       39 2004-06-07 19:08 restartapache
-rwxr-----   1 root root       38 2004-07-22 17:57 restartbind
-rwxrw----   1 root root       41 2004-06-07 19:32 restarttomcat
-rwxrw----   1 root root      182 2004-07-10 13:10 restarttomcatfull
-rwxrw----   1 root root       68 2004-06-07 19:32 restartweb
$ sudo /root/restartweb

login to the OSCAR application as oscardoc (not oscaradmin or oscarrep)

Note: oscaradmin and oscarrep, although they get created by default in the provider table, do not by default appear in the security table, however oscardoc can enable these via the Admin tab / Assign Role to Provider.