Sakai 23 Install Guide (Source)

1.0 Install Prerequisites

To begin with the following items must be installed (you may skip any you all ready have installed).

1. Java 11

2. Git

3. Maven 3.8 or later

4. Tomcat 9

Sakai 23.0 was QA tested with Java 11.0.16.1 (Temurin), Maven 3.8.4, Tomcat 9.0.69

1.1 Verify/Install Java 11

The Java JDK 11, a.k.a Java 11, is the required version to use with Sakai 23. Do not attempt to use a lower or higher version. 

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. Example output:

java version "11.0.16.1" 2022-08-18 LTS
Java(TM) SE Runtime Environment 18.9 (build 11.0.16.1+1-LTS-1)
Java HotSpot(TM) 64-Bit Server VM 18.9 (build 11.0.16.1+1-LTS-1, mixed mode)

1.1.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.

 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.

 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 "Install Tomcat 9" section below for more details. 

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=es -Duser.region=ES

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

1.2 Install Git and/or local Github client 

The Sakai Community uses Github as its source control management (SCM) system. Use a reasonably current version of Git to get the source. Alternatively, you can obtain binary packages for Mac/Linux and Windows (Linux is more popular and gets the preponderance of QA testing, by far). Extract the distribution archive into your installation directory. 

https://github.com/sakaiproject/sakai

1.3 Install Maven 3 

The Apache Maven project management framework provides Sakai with "a set of build standards, artifact repository model and a software engine that manages and describes projects" (Better Builds, p. 22). As part of the installation process you will use Maven as a build tool in order to compile, test and deploy Sakai to a servlet container such as Apache Tomcat.

It is recommended to use Maven 3.8+.

You can download Maven at

http://maven.apache.org/download.html

Extract the distribution archive into your installation directory of choice, e.g. /usr/local/apache-maven-3.8.7. Confirm that you have installed the correct version of Maven and can start it by issuing mvn --version from the terminal. At this point your environment is prepared to build and deploy the Sakai source code.

mvn --version

Apache Maven 3.8.5 (3599d3414f046de2324203b78ddcf9b5e4388aa0)
Maven home: D:\opt\maven3
Java version: 11.0.16.1, vendor: Oracle Corporation, runtime: D:\opt\java11
Default locale: es_ES, platform encoding: Cp1252
OS name: "windows 10", version: "10.0", arch: "amd64", family: "windows"

1.3.1 Set Maven environment variables 

A number of environment variables must be set for optimal Maven performance. 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 your Maven environment variables via the GUI.

Set the MAVEN_HOME environment variable to point to the base directory of your Maven installation and add the Maven /bin directory to your PATH variable:

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

MAVEN_OPTS

Maven does not read JAVA_OPTS on start up, resulting occasionally in "Out of Memory" errors when building Sakai. To assure sufficient memory allocation during builds, you should add a MAVEN_OPTS environment variable as defined below. 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 MAVEN_OPTS via the GUI.

export MAVEN_OPTS='-Xms512m -Xmx1024m'

1.4 Install Tomcat 9

• Apache Tomcat - https://tomcat.apache.org/download-90.cgi

• Note: Always do a fresh install of Tomcat 9 and do not attempt to use OS-installed versions of Tomcat

• Note: Ubuntu if using the Tomcat distributed with ubuntu it is sandboxed by systemd and doesn't allow write access to sakai directories

  • see https://sakaiproject.atlassian.net/browse/SAK-45495

• 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 9.0.71\