Skip to content

Quick Start from Source

Jump to bottom Edit New page
Kunal Jaykam edited this page Jan 20, 2022 · 86 revisions

Sakai quick start source install

Scope

This tutorial is designed to get you up and running quickly compiling from source code and with a MySQL database with a very basic OOTB (out of the box) Sakai. It does not include additional configurations you may need like:

  • Oracle database, if you use this instead of MySql. Oracle and MySQL are the supported databases
  • Adding an email server, to take advantage of the notification features of Sakai
  • Configure logging
  • Customizing Sakai's skin
  • Reviewing the many options available in Sakai, documented in the default.sakai.properties file.
  • Setting file storage. By default, files are stored in the database, but best practice is to store files on your file system.
  • Locking down Sakai from a security perspective
  • Integrating with your authentication system
  • Integrating with your Student Information System (SIS), if applicable
  • Scaling your system for production level requirements.
  • Load balancing if using more than a single application server
  • And more.

Software prerequisites

Important notes: For your first installation, keep it simple and use versions of these software packages as close as possible to the version used to build our nightly qa servers.

Technical environment for nightlies:

  • (Common) Java 1.8.0_171, maven-3.6.1 (though maven-3.3.9 should also work), and either mysql 5.6.39 or Oracle SE One 12.1.0.2.v11 (12C)
  • (11, 12) Apache Tomcat 8.5.31
  • (19) Apache Tomcat 9.0.8

There is a known issue with versions of Sakai 11 before 11.4 when using a version of Tomcat later than 8.0.34. MariaDB connector tends not to work when paired with MySQL.

Set Environment variables

For *NIX one typically modifies a startup file like ~/.bash_login. Mac standard is .bash_profile. For Windows typically in Control Panel -> System -> Advanced -> Environment variables.

Set JAVA_HOME, MAVEN_HOME, and CATALINA_HOME (i.e Catalina is used for Tomcat settings and logs).

Add JAVA_HOME/bin, MAVEN_HOME/bin, and CATALINA_HOME/bin to PATH.

Set MAVEN_OPTS. Feel free to allocate more memory to Maven, but not any less.

Variable *Nix/Mac Windows
JAVA_HOME export JAVA_HOME=path-to-java JAVA_HOME=path-to-java
MAVEN_HOME export MAVEN_HOME=path-to-maven MAVEN_HOME=path-to-maven
CATALINA_HOME export CATALINA_HOME=path-to-tomcat CATALINA_HOME=path-to-tomcat
PATH export PATH=$PATH:$JAVA_HOME/bin:$MAVEN_HOME/bin:$CATALINA_HOME/bin ;C:\path-to-java\bin;C:\path-to-maven\bin;C:\path-to-tomcat\bin
MAVEN_OPTS export MAVEN_OPTS='-Xms512m -Xmx1024m -Djava.util.Arrays.useLegacyMergeSort=true' MAVEN_OPTS='-Xms512m -Xmx1024m -Djava.util.Arrays.useLegacyMergeSort=true'

Database Configuration

Create a database to hold Sakai data. Use UTF8 and default collation.

Give it any name you wish. Grant privileges to a user account. Give the user account any name you wish. In this example we will name the database, sakaidatabase and the user sakaiuser and the password sakaipassword.

mysql> create database sakaidatabase default character set utf8;
Query OK, 1 row affected (0.00 sec)

mysql> grant all on sakaidatabase.* to sakaiuser@'localhost' identified by 'sakaipassword';
Query OK, 0 rows affected (0.00 sec

mysql> grant all on sakaidatabase.* to sakaiuser@'127.0.0.1' identified by 'sakaipassword';
Query OK, 0 rows affected (0.00 sec)

mysql> flush privileges;
Query OK, 0 rows affected (0.00 sec)

mysql> quit

Tomcat Configuration

  1. Copy your MySQL jdbc connector into CATALINA_HOME/lib directory

  2. Create a directory CATALINA_HOME/sakai

  3. In CATALINA_HOME/sakai create an empty local.properties or a sakai.properties file. local.properties and sakai.properties serve the same purpose. local.properties takes precedence over sakai.properties if they both exist.

Add these lines to your local.properties or sakai.properties file:

## MySQL settings
# Replace by whatever username you assigned in the database setup
username@javax.sql.BaseDataSource=sakaiuser
# Replace by whatever password you assigned to the sakaiuser in the database setup
password@javax.sql.BaseDataSource=sakaipassword

# use your sakaidatabase name in the URI that starts url@javax.sql.BaseDataSource= , below.

vendor@org.sakaiproject.db.api.SqlService=mysql
driverClassName@javax.sql.BaseDataSource=com.mysql.jdbc.Driver
hibernate.dialect=org.hibernate.dialect.MySQL5InnoDBDialect
url@javax.sql.BaseDataSource=jdbc:mysql://127.0.0.1:3306/sakaidatabase?useUnicode=true&characterEncoding=UTF-8
validationQuery@javax.sql.BaseDataSource=select 1 from DUAL
defaultTransactionIsolationString@javax.sql.BaseDataSource=TRANSACTION_READ_COMMITTED
  1. Modify CATALINA_HOME/conf/context.xml to improve startup speed.

Within the <Context> label add one of the following, depending which version of Sakai you're working on.

<JarScanner>
    <!-- This is to speedup startup so that tomcat doesn't scan as much -->
    <JarScanFilter defaultPluggabilityScan="false" />
</JarScanner>

  1. Modify CATALINA_HOME/conf/server.xml for international character support (Sakai is internationalized and has 20 languages available). Add URIEncoding to the Connector element. <Connector port="8080" URIEncoding="UTF-8" ...

  2. Create an executable setenv.sh file in the CATALINA_HOME/bin directory for *nix/Mac. Create an executable setenv.bat file in the CATALINA_HOME/bin directory for Windows.

  3. Add JAVA_OPTS to the setenv file.

Note: the sakai.demo parameter is optional. It is included in this example because it creates a set of default accounts including instructors, students, and rosters, making it easy to set up new course sites, useful for testing.

*nix/Mac

export JAVA_OPTS='-server -Xms512m -Xmx1024m -XX:PermSize=128m -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 -Djava.util.Arrays.useLegacyMergeSort=true -Dsakai.demo=true'

Windows

set JAVA_OPTS=-server -Xmx1028m -XX:MaxMetaspaceSize=512m -Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false -Djava.awt.headless=true -Dcom.sun.management.jmxremote -Dsakai.demo=true

Compile Sakai Source code

git clone https://github.com/sakaiproject/sakai.git
cd sakai && git checkout 11.2

This will get you the latest community supported maintenance release, Sakai 11.2 .

First compile the master project.

cd master
mvn clean install

Expected result: Build successful

Then compile and deploy Sakai to Tomcat

cd ..
mvn clean install sakai:deploy -Dmaven.tomcat.home=$CATALINA_HOME -Djava.net.preferIPv4Stack=true -Dmaven.test.skip=true

Expected result: Build successful

Start up Sakai

Go to CATALINA_HOME/bin

*nix/Mac

./startup.sh

Windows

startup.bat

Test that your startup is successful

Go to CATALINA_HOME/logs

Check the catalina.out log. As the system is starting up, it will be logging messages. Notice if there are any errors.

Expected Result: system started up in xxxxx seconds

If system startup is successful, go to your browser and visit http://localhost:8080

Expected Result: Apache Tomcat page. Tomcat is running

Then visit http://localhost:8080/portal

Expected Result: Sakai comes up!

Making your first course site in Sakai

  1. Log in as instructor with password sakai . This works only if you included the -Dsaka.demo=true in your JAVA_OPTS.

  2. You will be presented with a brief tutorial. If this is your first time using Sakai, it is probably worth going through. It will take just a few minutes. It's a brief tutorial, not comprehensive.

  3. Click on the "Site Waffle" in the upper right hand side and click "Create New Site"

Sakai Site Waffle

  1. Choose "course site" for Academic term "Spring 2016" on the Create Site screen.

  2. Pick any course section. Click continue.

Course sections

  1. Optional entries for Description and Short Description and choosing a language for the site.

  2. Choose tools to include in your site. You might want to start with Announcements, Assignments, Calendar, Forums, Gradebook, Lessons, Resources and Test & Quizzes. They are among the most popular. Click continue.

  3. The default is to publish your site, which means that students can see it. It's very common to choose "Leave as Draft" so that you can configure your site for the students before displaying it to them. The rest of the default access settings are the most common and for now you might not want to change them. Click Continue.

  4. Next page is the confirmation page. If you are happy with your settings, click "Create Site".

  5. There are several options to navigate to your site. If you don't find those options you can always go back to the Site Waffle. If you do that you may notice a star next to the site name. Click the star to highlight it. See what happens.

Star your site to have it show on the top menu bar

  1. Go and play! Play around with the different tools and options. A comprehensive up-to-date help system is available wherever you see the question mark.

Sakai Help

  1. If you have questions our Community email lists are a great place to start. You can search archives on the web or subscribe. The two most popular are sakai-user for questions on using Sakai and sakai-dev for technical questions. There is also a sakai-production list for questions on configuring Sakai for real-world use. See our complete list of communication options.

  2. Sakai is an Apereo project. The Apereo Foundation is a non-profit that depends upon institutional and individual memberships to be sustainable.

All test servers are listed on Sakai Nightly

Add a custom sidebar
Clone this wiki locally