Original Sakai notes
These Sakai installation notes are obsolete, based on our attempts to install an older version of the software. They are being kept here for historical purposes only.
Contents:
Contents
1. Installing Sakai
These notes describe out installation of Sakai on Scientific Linux 4.02 (a Redhat enterprise clone).
We have decided not to use the quickstart install, instead following instructions per http://cvs.sakaiproject.org/release/1.5.0/index-dev.html.
The host we are using is sakai-vre-demo.oucs.oc.ac.uk.
1.1. File protections
Our first attempt at installtion ran into a couple of problems due to file protections. Tomcat was installed as root, with root owner/group for all the Tomcat directories. This caused problems when installing Sakai.
Our proposed approach is to install all Tomcat files under a new user tomcat, group tomcat, and make the Tomcat install files all group writeable. Then add group tomcat to the user used to install the Sakai software (sakaivre in our case. We have also declared all directories to carry the group sticky bit, so that new files are created with the same group ownetrship.
Everying inder $CATALINA_HOME/webapps needs to be changed to have group full access permission (g+rw).
We also want to ensure that Tomcat always runs as user tomcat.
1.2. Prerequisites
Java 1.4.2: use yum install java to install java-1.4.2-sun-compat and j2sdk.
Tomcat 5.5.16: download from Apache site http://tomcat.apache.org/download-55.cgi#5.5.16, and install to /opt. Unzip core tomcat package, tomcat-admin and tomcat-compat to the same base directory /opt. The archives contain a top-level directory apache-tomcat-5.5.16/. Define environment variable:
- {{{CATALINA_HOME=/opt/apache-tomcat-5.5.16
}}}
Maven 1.0.2 - download from http://maven.apache.org/start/download.html and follow installation instructions given at http://maven.apache.org/start/install.html. In out case, download the archive file and unpack to /opt (the archive contains a top-level directory maven-1.0.2/.
Before you begin using Maven you will need to define the MAVEN_HOME environment variable which is the directory where you just unpacked the Maven install archive. You will also need to add MAVEN_HOME/bin to your path so that you can run the scripts provided with Maven.
You will also need to define the JAVA_HOME environment variable. This variable should be the directory where a Java Development Kit is installed (note that a JRE is not sufficient). This directory will contain the bin, jre and lib directories.
Place the relevant environment variable definitions in /etc/bashrc (noting our system is effectively dedicated for Sakai development/testing, so defining for all-users seems appropriate). {{{export JAVA_HOME=/usr/java/j2sdk-1.4.2_10/
export MAVEN_HOME=/opt/maven-1.0.2 export PATH=$PATH:$MAVEN_HOME/bin }}}
We choose to create a new user sakaivre as the "home user" for Maven configuration, repositories, etc. {{{su -
useradd sakaivre }}}
Place a Maven build.properties in the skaivre home directory: {{{maven.repo.remote = http://www.ibiblio.org/maven/,http://cvs.sakaiproject.org/maven/
maven.tomcat.home = /opt/apache-tomcat-5.5.16 ### Can use $CATALINA_HOME? }}}
- Enable execute permissions on Maven executable: {{{chmod a+x /opt/maven-1.0.2/bin/*
}}}
Remove or rename Tomcat ROOT webapp, so that Sakai can take over the root application (see "special tomcat installation" in http://cvs.sakaiproject.org/release/1.5.0/index-dev.html); e.g. {{{mv $CATALINA_HOME/webapps/ROOT $CATALINA_HOME/webapps/ROOT-OLD
}}}
If Tomcat is run at this point, browsing to http://sakai-vre-demo.oucs.oc.ac.uk:8080 will display a blank page. http://sakai-vre-demo.oucs.oc.ac.uk:8080/jsp-examples displays example data and confirms JSP operation.
1.3. Sakai installation
Download Sakai kit from http://cvs.sakaiproject.org/release/1.5.0/src/sakai-src.zip to /home/sakaivre/sakai-1.5.0.
Now run /opt/maven-1.0.2/bin/maven tomcat_context from the /home/sakaivre/sakai-1.5.0 directory. Maven should create a new repository and then configure Sakai as the Tomcat ROOT application, but at this stage does not actually install any software. (Cf. $CATALINA_HOME/conf/Catalina/localhost/sakai-dispatch.xml.)
Run /opt/maven-1.0.2/bin/maven (no arguments) bfrom the /home/sakaivre/sakai-1.5.0 directory. This will cause lots of dependencies to be downloaded, and Sakai software should be build. This can take a while. Our first attempt failed after 17 minutes.
NOTE
The Sakai software file maven.xml contains hardwired breferences to /usr/local/sakai. We have replaced these with ${sakai.local.home}, and added an appropriate definition to our /home/sakaivre/build.properties file. For our installation, we use /opt/sakai for this. There are also hard-wired references to this directory all over the code, so we have also created a symlink: {{{ln -s /opt/sakai /usr/local/sakai
}}}
Even with all this in place, Sakai startup was failing with access failure in directory /opt/sakai/sakai-dispatch - this directory had not been created, Why? This installation was leftb running for about a week, and when we came back to it we found about 500Mb of Tomcat logs, predominantly reporting SQL (no default pool) errors.
1.4. Sakai installation take 2
Coming back to this, we decided to restart from a clean installation of Tomcat, using user tomcat to perform the installation of both tomcat and sakaivre.
- log in session as user tomcat
- download apache tomcat distros:
- {{{apache-tomcat-5.5.16.tar.gz
apache-tomcat-5.5.16-compat.tar.gz apache-tomcat-5.5.16-admin.tar.gz }}
Unpack the tomcat distros to /opt/apache-tomcat-5.5.16, and set environment variable CATALINE_HOME to point to that directory. Unpacked files ownerwhip is tomcat:tomcat
- Start up Tomcat and confirm that it works:
- {{{cd /opt/apache-tomcat-5.5.16/bin
./startup.sh }}}
Then browse to http://sakai-vre-demo.oucs.ox.ac.uk:8080/.
- Shut down Tomcat
Still running as user Tomcat, download and unpack the Sakai source from http://cvs.sakaiproject.org/release/1.5.0/src/sakai-src.zip to /opt/sakai
Establish a maven repository in /home/tomcat/.maven (copying files from the repository previosuly created in /home/sakaivre.
- Go to the sakai directory and run maven to build the sakai software:
- {{{cd /opt/sakai
/opt/maven-1.0.2/maven }}}
On first attempt, this failed trying to copy files to /webapps/sakai-(something), suggesting that the tomcat location has not been configured properly. We forgot to create the /home/tomcat/build.properties file, which we have containing:
{{{maven.repo.remote = http://www.ibiblio.org/maven/,http://cvs.sakaiproject.org/maven/
maven.tomcat.home = /opt/apache-tomcat-5.5.16 sakai.local.home = /opt/sakai }}}
- This time, the maven build was successful. The last operations performed were deploying sakai software to the Tomcat webapps directory.
- Restart Tomcat - this time, Tomcat starts without significant errors (some complaints about missing database files), but we still don't have a running Sakai instance. Stop Tomcat again.
- Copy Sakai configuration files:
- {{{cp -r $SAKAI_DEV/reference/src/usr_local_sakai/* /opt/sakai/
}}}
where $SAKAI_DEV is the directory to which the source was unpacked (/opt/sakai).
Now start tomcat: this time we get errors in theb startup log "SEVERE: Error listenerStart" in the catalina.out logfile, followed soon after by "Context [/sakai-module] failed to start duee to previosu errors" and "Context [/sakai-crud] failed to start duee to previosu errors" (the latter is suggestive of database problems. The localhost.*.log logfile shows java.lang.NoClassDefFound exceptions for class org/apache/commons/collections/ExtendedPoperties and org/apache/commons/collections/ArrayStack.
Locate file commons-collections-3.0.jar
(e.g. at http://www.ibiblio.org/maven2/commons-collections/commons-collections/3.0/commons-collections-3.0.jar), and copy it to /opt/apache-tomcat-5.5.16/shared/lib. Restart Tomcat. This time, it starts without errors.
Browse to http://sakai-vre-demo.oucs.ox.ac.uk:8080/portal. Nothing is displayed. The log indicates listening on port 8009 (as well as 8080?). Check firewall settings; enable port 8009. Stop tomcat, restart network software, start tomcat. Logs look good.
Browse to http://sakai-vre-demo.oucs.ox.ac.uk:8080/jsp-examples - appears top work OK. Browse to http://sakai-vre-demo.oucs.ox.ac.uk:8080/portal - no data returned. The documentation says /portal but it appears we must use /sakai-portal - this can be determined by looking at file /opt/apache-tomcat-5.5.16/conf/Catalina/localhost/sakai-portal.xml.
Browse to http://sakai-vre-demo.oucs.ox.ac.uk:8080/sakai-portal - this time we see something, thoughj not very enlightening - something about "Sakai: Varuna portal webapp". Nothing appears in the Tomcat log directories. Also nothing in /var/log/.... Also nothing else we could find in the Tomcat file area.
- Hmmm... it apperas we missed a couple of maven operations: try them now:
maven reg maven conf_db
1.5. Sakai installation take 3
Coming back to the installation created above, I've tried a couple of things:
- Check that build.properties has trailing slashes on the directory names (it did); i.e.
{{{maven.repo.remote = http://www.ibiblio.org/maven/,http://cvs.sakaiproject.org/maven/
maven.tomcat.home = /opt/apache-tomcat-5.5.16/ sakai.local.home = /opt/sakai/ }}}
- Edited /etc/bashrc so that JAVA_HOME and MAVEN_HOME directory names defined there also have trailing '/'; e.g.
- {{{export JAVA_HOME=/usr/java/j2sdk1.4.2_10/
export MAVEN_HOME=/opt/maven-1.0.2/ export CATALINA_HOME=/opt/apache-tomcat-5.5.16 }}}
- I noticed that the shutdown.sh script in $CATALINA_HOME/bin had been zapped (why?), so replaced it from the original Tomcat distribution archive.
Stop and restart Tomcat, and browse to http://sakai-vre-demo.oucs.ox.ac.uk:8080/sakai-portal/. The same page display as before is seen, but this time the links are not broken. Rather, they generate almost blank pages, but with reference to some javascript, and a page with two <div>s containing blank <iframe>s:
{{{<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<title>Sakai : Gateway : Welcome</title> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> <link href="/sakai-portal/css/portalskins/sakai_core/skin/sakai_core.css" type="text/css" rel="stylesheet" media="all" /> <script type="text/javascript" language="JavaScript" src="/sakai-chef-tool/js/headscripts.js"></script> <script type="text/javascript" language="JavaScript"> var courierUrl = "http://sakai-vre-demo.oucs.ox.ac.uk:8080/tunnel/sakai-chef-tool/courier?site=!gateway&page=!gateway-100&auto=courier&tool=!gateway-110&tool=!gateway-120"; function doLoad() {} </script>
</head>
<body marginwidth="0" marginheight="0" topmargin="0" leftmargin="0" onload="doLoad();">
<!-- $Source: /cvs/sakai/portal/src/webapp/vm/portal3.vm,v $ $Date: 2005/02/08 22:36:02 $ --> <div id="container">
<div class="channeltitlewrap"> <iframe name="Titlexgatewayx110" id="Titlexgatewayx110" title="Title Bar" class="channelTitleIframe"
- height="22" width="99%" frameborder="0" marginwidth="0" marginheight="0" scrolling="no"
src="http://sakai-vre-demo.oucs.ox.ac.uk:8080/tunnel/sakai-chef-tool/ chef-motd?pid=!gateway-110&panel=Title">
</iframe> </div>
<div class="uportalchannelcontent"> <iframe name="Mainxgatewayx110" id="Mainxgatewayx110" title="Message of the day" class="channelMainIframe"
- height="50" width="100%" frameborder="0" marginwidth="0" marginheight="0" scrolling="auto"
src="http://sakai-vre-demo.oucs.ox.ac.uk:8080/tunnel/sakai-chef-tool/ chef-motd?pid=!gateway-110&panel=Main">
</iframe> </div>
</div>
- height="22" width="99%" frameborder="0" marginwidth="0" marginheight="0" scrolling="no"
</body>
</html> }}}
- This suggests to me that the portal software is probably working, but that it is lacking a usable configuration. Maybe we need to rebuild everything again?
1.6. Sakai installation take 4
This attmept uses a pair of scripts to completely install and/or unistall the software.
### as root su - #install java yum install java #create the user and group useradd tomcat usermod -G tomcat syeates usermod -G tomcat zool0635 #create dircetories for the compnents we're going to install for filename in /opt/maven /opt/sakai /opt/commons-logging /opt/logging-log4j /opt/apache-tomcat; do mkdir -p $filename chown tomcat:tomcat $filename done ln -s /opt/sakai/sakai-1.5.0 /usr/local/sakai ### as tomcat su - tomcat #java is already installed export JAVA_HOME=/usr/java/j2sdk1.4.2_10/ # install tomcat cd /opt/apache-tomcat wget http://apache.rmplc.co.uk/tomcat/tomcat-5/v5.5.16/bin/apache-tomcat-5.5.16.tar.gz tar -xzf apache-tomcat-5.5.16.tar.gz wget http://apache.rmplc.co.uk/tomcat/tomcat-5/v5.5.16/bin/apache-tomcat-5.5.16-compat.tar.gz tar -xzf apache-tomcat-5.5.16-compat.tar.gz wget http://apache.rmplc.co.uk/tomcat/tomcat-5/v5.5.16/bin/apache-tomcat-5.5.16-admin.tar.gz tar -xzf apache-tomcat-5.5.16-admin.tar.gz #rename the ROOT webapp, mv $CATALINA_HOME/webapps/ROOT $CATALINA_HOME/webapps/ROOT-OLD #remember where we've kept it export CATALINA_HOME=/opt/apache-tomcat/apache-tomcat-5.5.16/ # install maven cd /opt/maven wget http://www.mirror.ac.uk/mirror/ftp.apache.org/maven/binaries/maven-1.1-beta-2.tar.gz tar -xzf maven-1.1-beta-2.tar.gz # set some maven defualts in our home dircetory cat > /home/tomcat/build.properties << EOF maven.repo.remote = http://www.ibiblio.org/maven/,http://cvs.sakaiproject.org/maven/ sakai.local.home = /opt/sakai/sakai-1.5.0/ maven.tomcat.home = /opt/apache-tomcat/apache-tomcat-5.5.16 ### Can use $CATALINA_HOME? EOF #remember whre we've kept it export MAVEN_HOME=/opt/maven/maven-1.1-beta-2 # install sakai cd /opt/sakai wget http://cvs.sakaiproject.org/release/1.5.0/src/sakai-src.zip unzip sakai-src.zip -d sakai-1.5.0 # run maven on sakai cd /opt/sakai/sakai-1.5.0/ $MAVEN_HOME/bin/maven tomcat_context $MAVEN_HOME/bin/maven reg $MAVEN_HOME/bin/maven conf_db $MAVEN_HOME/bin/maven
The above fails in $MAVEN_HOME/bin/maven in legacy-component, because of a dependency problem. This can be fixed with the following patch:
[tomcat@sakai-vre-demo sakai-1.5.0]$ diff /opt/sakai/sakai-1.5.0/legacy-component/project.xml /opt/sakai/sakai-1.5.0/legacy-component/project.xml~ 16,20d15 < <dependency> < <groupId>xerces</groupId> < <artifactId>xercesImpl</artifactId> < <version>2.6.0</version> < </dependency>
Which has the effect of adding the xerces jar to the class path. It turns out that SAKAI is refering to an internal xerces class (org.apache.xerces.impl.dv.util.Base64). With this patch it comiples and can be run with
$CATALINA_HOME/bin/startup.sh
That is is running can be verified by going to: http://sakai-vre-demo.oucs.ox.ac.uk:8080/sakai-portal/ and what we see is:
Sakai : Varuna Portal Webapp This is "index.html" Portal /sakai-portal/varuna Varuna Portal /sakai-portal/varuna.html
The first error messages in the logs are:
Apr 24, 2006 4:14:44 PM org.apache.catalina.startup.HostConfig deployDescriptor WARNING: A docBase /opt/apache-tomcat/apache-tomcat-5.5.16/webapps/sakai-portal inside the host appBase has been specified, and will be ignored Apr 24, 2006 4:14:44 PM org.apache.tomcat.util.digester.Digester startElement SEVERE: Begin event threw exception java.lang.ClassNotFoundException: org.sakaiproject.dav.DavRealm at java.net.URLClassLoader$1.run(URLClassLoader.java:199) at java.security.AccessController.doPrivileged(Native Method) ... at org.apache.catalina.startup.Bootstrap.main(Bootstrap.java:413) Apr 24, 2006 4:14:44 PM org.apache.catalina.startup.ContextConfig processContextConfig SEVERE: Parse error in default web.xml java.lang.ClassNotFoundException: org.sakaiproject.dav.DavRealm at org.apache.tomcat.util.digester.Digester.createSAXException(Digester.java:2725) ...
The script for removing these changes from the server is:
### as root su - userdel tomcat groupdel tomcat mv /home/tomcat-old/ /home/tomcat/ mv /home/tomcat/ /home/tomcat-old/ mv /opt-old/ /opt mv /opt /opt-old/ rm -rf /usr/local/sakai du -s /opt /opt-old/ yum remove java
1.7. Sakai installation take 5 SUCCESS!
1.7.1. Approach
After some advice from Adrian, we worked out that the root of the problem was that we were not using the latest version of Sakai (1.5 not 2.1.2). So we trid again, using a similar script to last time and it worked. As Adrian said, it should take less that 3 hours, if you're doing it right. The instructions I followed were the ones at: http://cvs.sakaiproject.org/release/2.1.2/InstallGuide.html for the source install.
Before the JACA_OPTS were set, the tomcat start up was taking ages and attempts to access port 8080 resulted in timeouts. In such a situation, the normal tomcat shutdown.sh script does not work, presumably because it too can't connect. Thus the "killall java" command.
### as root su - #install java yum install java #create the user and group useradd tomcat usermod -G tomcat syeates usermod -G tomcat zool0635 #create dircetories for the compnents we're going to install for filename in /opt/maven /opt/sakai /opt/apache-tomcat; do mkdir -p $filename chown tomcat:tomcat $filename done ### as tomcat su - tomcat #java is already installed export JAVA_HOME=/usr/java/j2sdk1.4.2_10/ # install tomcat cd /opt/apache-tomcat wget http://apache.rmplc.co.uk/tomcat/tomcat-5/v5.5.16/bin/apache-tomcat-5.5.16.tar.gz tar -xzf apache-tomcat-5.5.16.tar.gz wget http://apache.rmplc.co.uk/tomcat/tomcat-5/v5.5.16/bin/apache-tomcat-5.5.16-compat.tar.gz tar -xzf apache-tomcat-5.5.16-compat.tar.gz wget http://apache.rmplc.co.uk/tomcat/tomcat-5/v5.5.16/bin/apache-tomcat-5.5.16-admin.tar.gz tar -xzf apache-tomcat-5.5.16-admin.tar.gz #remember where we've kept it export CATALINA_HOME=/opt/apache-tomcat/apache-tomcat-5.5.16/ # we're not caring about non-roman characters to start with #emacs $CATALINA_HOME/conf/server.xml cat > $CATALINA_HOME/webapps/ROOT/index.html << EOF <html> <head> <meta http-equiv="refresh" content="0;url=/portal"> </head> <body> redirecting to /portal ... </body> </html> EOF # install maven cd /opt/maven wget http://apache.mirror.positive-internet.com/maven/binaries/maven-1.0.2.tar.gz tar -xzf maven-1.0.2.tar.gz # set some maven defualts in our home dircetory cat > /home/tomcat/build.properties << EOF maven.repo.remote=http://source.sakaiproject.org/maven/ maven.tomcat.home = /opt/apache-tomcat/apache-tomcat-5.5.16/ EOF #remember whre we've kept it export MAVEN_HOME=/opt/maven/maven-1.0.2/ # install sakai cd /opt/sakai wget http://cvs.sakaiproject.org/release/2.1.2/sakai_2-1-2/sakai-src_2-1-2.tar.gz tar -xzf sakai-src_2-1-2.tar.gz # run maven on sakai cd /opt/sakai/sakai-src $MAVEN_HOME/bin/maven $MAVEN_HOME/bin/maven sakai $MAVEN_HOME/bin/maven sakai:deploy # this is sometimes needed because the normal shutdown times out / doesn't work when the JVM is very low on memory killall java # these are the recommended JAVA_OPTS from http://cvs.sakaiproject.org/release/2.1.2/postconfig.html#jvm JAVA_OPTS="-server -Xms1500m -Xmx1500m -XX:NewSize=400m -XX:MaxNewSize=400m -XX:PermSize=128m -XX:MaxPermSize=128m -verbose:gc -XX:+PrintGCTimeStamps -XX:+PrintGCDetails" $CATALINA_HOME/bin/startup.sh $CATALINA_HOME/bin/shutdown.sh
The resulting page looks like:
The install uses quite a bit of space:
243136 /opt/apache-tomcat 13648 /opt/maven 402212 /opt/sakai 149644 /home/tomcat/
The size of /home/tomcat/ is due to the presence of the maven repository, which a cache of all the libraries that maven has downloaded from the web.
Sakai 2.1.2 does a number of things better than 1.5, and a number of our earlier criticisms are no longer valid.
1.8. Notes
We think the following are broken or questionable. This is work-in-progress, so our views may change as we get on further with Sakai.
- Hardwiring path into application (/usr/local/sakai). Fixed in 2.1.2
- Doing strange things with Tomcat (to be fair, this is made clear in the documentation)) Fixed in 2.1.2
- Claiming to use standards, but not using a standard servlet container
- Deployment structure breaks chroot model (we think) Fixed in 2.1.2?
- Deployment seems to be hardwired to Tomcat, not allowing other servlet containers
- Maven build does not seem to create all the necessary files and/or directories for operation (notably, sakai_dispatch directory). (This problem was not observed on 2nd attempt, so may have been a file protection anomaly.)
-- GrahamKlyne 2006-02-10 15:01:32