Quick Start from Source
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.
- Git
- Apache Maven 3
- Java 1.8 (development kit to build from source)
- Apache Tomcat 8 (for Sakai 11 and 12)
- Apache Tomcat 9 (for Sakai 19)
- MySQL 5
- MySQL JDBC jar
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.
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' |
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
-
Copy your MySQL jdbc connector into CATALINA_HOME/lib directory
-
Create a directory CATALINA_HOME/sakai
-
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
[email protected]=sakaiuser
# Replace by whatever password you assigned to the sakaiuser in the database setup
[email protected]=sakaipassword
# use your sakaidatabase name in the URI that starts [email protected]= , below.
[email protected]=mysql
[email protected]=com.mysql.jdbc.Driver
hibernate.dialect=org.hibernate.dialect.MySQL5InnoDBDialect
[email protected]=jdbc:mysql://127.0.0.1:3306/sakaidatabase?useUnicode=true&characterEncoding=UTF-8
[email protected]=select 1 from DUAL
[email protected]=TRANSACTION_READ_COMMITTED
- 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>
-
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" ...
-
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.
-
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
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
Go to CATALINA_HOME/bin
*nix/Mac
./startup.sh
Windows
startup.bat
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!
-
Log in as instructor with password sakai . This works only if you included the -Dsaka.demo=true in your JAVA_OPTS.
-
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.
-
Click on the "Site Waffle" in the upper right hand side and click "Create New Site"
-
Choose "course site" for Academic term "Spring 2016" on the Create Site screen.
-
Pick any course section. Click continue.
-
Optional entries for Description and Short Description and choosing a language for the site.
-
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.
-
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.
-
Next page is the confirmation page. If you are happy with your settings, click "Create Site".
-
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.
- 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.
-
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.
-
Sakai is an Apereo project. The Apereo Foundation is a non-profit that depends upon institutional and individual memberships to be sustainable.