/
Sakai 2.9 install guide (binary)

Sakai 2.9 install guide (binary)

Dec 14, 2021

1.0 Get the binary archive

 

 Binary limitations. Post-release patches are not always packaged as jars, so a binary install forces a relatively static implementation that cannot be as readily patched later.

The binary distribution of Sakai provides a shortcut for those that already have Tomcat in place and configured as needed (including the database setup and configuration) and it does so by providing a pre-built Sakai that can simply be dropped into place. All you need to do is unpack the binary archive at the root Tomcat directory and the appropriate *.wars, *.jars, etc., for the Sakai application will be deposited in the correct locations.

The latest Sakai binary archive is available at http://source.sakaiproject.org/release/.

 

2.0 Verify/Install Java 1.6

 

Oracle's Sun Java SE 6, a.k.a Java 1.6, is the preferred version to use with the Sakai CLE, because it has been tested the most thoroughly. Java SE 7, a.k.a Java 1.7 should also be compatible. Certain files, such as *.jsp and *.jws, require compilation so downloading and attempting to use only the JDK, the JRE with only the run time environment (JRE 6.0 or JRE 7.0) will not suffice.  Mac OS X 10.6 (Snow Leopard) and later includes the full version of Java SE 6 so Mac users do not need to install Java.  If you find Sun's version and naming conventions confusing, see Sun Java SE Naming and Versions for an outline of their practices.

 Oracle's Sun Java J2SE 5.0 (a.k.a Java 1.5) has completed the EOL process and is no longer supported. If are still running Java 1.5 please note that security vulnerabilities exist in JDK/JRE 5.0 updates 1.5.0_17 and earlier. Sun recommends that you install JDK/JRE 5.0 Update 18+ (the final update is JDK/JRE 5.0 Update 22).

Java 7

As of June 19, 2013, an issue has been reported with respect to Java 7 compatibility. The problem is in the Comparators and the workaround is to use the JVM property

-Djava.util.Arrays.useLegacyMergeSort=true

For details see - http://sakai-project-mail-list-archives.1343168.n2.nabble.com/Building-Sakai-Java-7-and-Sakai-comparators-tt7589944.html and 

SAK-38978 - Content Hosting comparators are incompatible with java 7 CLOSED

 

To confirm that Java is both installed on your system and is the correct version for Sakai, run java -version from the command line:

java -version

If Java is installed, basic version and build information will be displayed:

java version "1.6.0_24" Java(TM) SE Runtime Environment (build 1.6.0_24-b07-334-10M3326) Java HotSpot(TM) 64-Bit Server VM (build 19.1-b02-334, mixed mode)

If Java is not installed or you are running the wrong version you can download the Java SE 6.0 JDK or the Java SE 7.0 JDK release from Oracle's Sun archive:

http://www.oracle.com/technetwork/java/javase/archive-139210.html

Install the JDK, typically in the /opt directory, i.e. /opt/java. Install the JRE in a different directory (usually the default directory, especially if running Windows) or you may experience run-time issues.

 

2.1 Set Java environment variables

 

Several environment variables and related properties must be set for Java. For UNIX operating systems one typically modifies a startup file like ~/.bash_login to set and export shell variables while Mac users typically set and export environment variables in .bash_profile. For Windows, go to Start -> Control Panel -> System -> Advanced -> Environment Variables and set JAVA_HOME via the GUI.

Set the JAVA_HOME environment variable to point to the base directory of your Java installation and add Java's /bin directory to the PATH environment variable.

 If the variable JRE_HOME is already set or if you want to use a particular JRE if you have more than one JRE installed on your machine then you'll want to set the JRE_HOME variable as well. JRE_HOME is what Apache Tomcat uses when it starts up, but it defaults to use JAVA_HOME if JRE_HOME is not set. In most cases, setting JAVA_HOME should cover both cases sufficiently.

Variable

Unix

Mac

Windows

Variable

Unix

Mac

Windows

JAVA_HOME

export JAVA_HOME=/usr/java/java-current

export JAVA_HOME=/Library/Java/Home

JAVA_HOME=C:\jdk1.6.0_24

PATH

export PATH=$PATH:$JAVA_HOME/bin/

export PATH=$PATH:$JAVA_HOME/bin/

;C:\jdk1.6.0_24\bin

 Windows: append the string to the end of the Path system variable

Set JAVA_OPTS

The default Java virtual machine (JVM) settings are insufficient for an application of Sakai's size. As a result several JVM parameters must be increased for Sakai to run, while others may need to be adjusted for optimal performance. At a minimum add the following property settings to your JAVA_OPTS environment variable.

 We recommend that you define these settings in Tomcat's /bin directory in a file named setenv.sh (Unix/Mac) or setenv.bat (Windows). See the Tomcat section below for more details.

Unix/Mac:

export JAVA_OPTS='-server -Xms512m -Xmx1024m -XX:PermSize=128m -XX:MaxPermSize=512m -XX:NewSize=192m -XX:MaxNewSize=384m -Djava.awt.headless=true -Dhttp.agent=Sakai -Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false -Dsun.lang.ClassLoader.allowArraySyntax=true'

Windows:

set JAVA_OPTS=-server -Xms512m -Xmx1024m -XX:PermSize=128m -XX:MaxPermSize=512m -XX:NewSize=192m -XX:MaxNewSize=384m -Djava.awt.headless=true -Dhttp.agent=Sakai -Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false -Dsun.lang.ClassLoader.allowArraySyntax=true

 Additional required settings

Certain JSF tools (chat, portfolios, test & quizzes) do not compile properly in Java 1.6. The workaround requires adding the system property allowArraySyntax in order to avoid deserialization bottlenecks in arrays (see 

SAK-17578 - Compiling with Java 1.6 breaks tools in Sakai CLOSED ). Second, Tomcat 5.5.27+ enforces strict quote escaping, a change in *.jsp handling that has yet to be addressed in certain tools such as portfolios (see 
SAK-15736 - NPE when trying to preview portfolios when running in tomcat 5.5.27 and websphere CLOSED ). Finally, specify an HTTP user agent other than "Java/xxxxx" in order to resolve Google and other RSS feeds (see 
SAK-10159 - Unable to interpret RSS from Google News CLOSED , 
SAK-13353 - Unable to render news from Times Higher Education Supplement (THES) CLOSED and 
SAK-18044 - Add -Dhttp.agent=Sakai to demo startup scripts to resolve Google RSS feed issues CLOSED ).

-Dsun.lang.ClassLoader.allowArraySyntax=true -Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false -Dhttp.agent=Sakai

Specify a Language and Locale (optional)

You can define the default language/locale when starting Sakai by setting the system properties -Duser.language and -Duser.region. For information on supported languages see the release notes or visit the i18N Work Group space.

-Duser.language=pt -Duser.region=PT

In the case your locale were not fully supported in Java (as it happens with Basque or Mongolian languages) you should read this information:
Endorsed I18n Project 

Specify an HTTP Proxy (optional)

In environments where local network policy or firewalls require use of an upstream HTTP proxy/cache, Sakai needs to be configured accordingly. Otherwise components or services which use HTTP requests, such as the BasicNewsService for RSS feeds in the News tool, cannot retrieve data from the target URLs. This can be fixed with the following JAVA_OPTS arguments:

-Dhttp.proxyHost=cache.some.domain -Dhttp.proxyPort=8080

 

3.0 Install Tomcat 7

 

  • Apache Tomcat - http://tomcat.apache.org/

  • Note: Always do a fresh install of Tomcat (please note that Tomcat has a bug. Please use Tomcat 7.0.65 or Tomcat 7.0.68, when released. Addendum 30January2017 - appears to work with 7.0.75 as of this writing. Is known not to work with 7.0.72 through 7.0.74 

    SAK-31912 - FacesContext already released in JSF tools with Tomcat 7.0.72+ RESOLVED )

  • Note: Windows users should ensure that there are no spaces in the complete tomcat path as this causes errors with JSF tools in Sakai
    GOOD: C:\opt\tomcat\, C:\sakaistuff\installs\tomcat\
    BAD: C:\program files\tomcat\, C:\opt\apache tomcat 7.0.1\

  1. Download Tomcat 7 if you're using Sakai 10- http://tomcat.apache.org/download-70.cgi
    Download Tomcat 8 if you're using Sakai 11 - https://tomcat.apache.org/download-80.cgi
    (The directions below are mostly the same for 7 or 8, but the setenv.sh is a little different)

    • Windows users should get the zip file instead of installing a service
      It makes viewing the tomcat logs easier and it is easier to configure

      If you're running the tag of Sakai 2.9.1 or earlier you need to be running Tomcat 7.0.21 or earlier. If you go any higher Webdav and Sitestats will have errors and not work. A better solution is to upgrade to the latest version of Sakai and Tomcat.

      SAK-28531 - Sitestats does not load with Tomcat 7.0.35 CLOSED

      SAK-23156 - IncompatibleClassChangeError from WebDAV LOCK operations giving 500 response code CLOSED

  2. Extract to /opt (symlink the apache-tomcat-7.0.x directory to tomcat after extracting)

    • Example (assuming you have saved the file as /opt/apache-tomcat-7.0.x.tar.gz)

    • Windows users should just rename the directory since they cannot symlink

  3. Modify conf/server.xml for international character support

    1. Add URIEncoding="UTF-8" to the Connector element

      • <Connector port="8080" URIEncoding="UTF-8" ...

  4. Set environment variable: CATALINA_HOME=/opt/tomcat

  5. Add $CATALINA_HOME/bin to PATH

  6. Setup the SETENV file in the tomcat/bin directory with JAVA_OPTS (from Install Java 1.7+)

    Populate Database With Demo Data

    Instead of starting with an empty database you can add the flag -Dsakai.demo=true in addition to the others shown here. During your first Tomcat launch it will populate your database with test data (students, courses, etc). Once the data has been created remove this flag for subsequent Tomcat launches. Be advised that this flag will not trigger on a database with data already in it so you must make this choice during the initial setup. It should also be noted that without this flag one will not be able to create any course sites in Sakai unless Academic Term, Subject, Course, and Section data is manually added to the "cm_" tables in the database.

     

    1. Mac/Linux: Create a file called setenv.sh with the following (alternately, you can put this into your .bashrc file so they're automatically executed):

      Tomcat 7 Mac/Linux

      Tomcat 8 Mac/Linux

    2. Windows(PC): Create a file called setenv.bat with the following:

      Tomcat 7 Windows

      Tomcat 8 Windows

  7. [OPTIONAL] Delete the default webapps from the webapps dir

    rm -rf webapps/*