Sakai 2.x install guide (demo)
1.0 Get the demo
sakai-demo/sakai/db/sakai.db.*
. Second, certain features such as e-mail and search are disabled.Installing the Sakai Demo involves only a few steps. The most technically challenging aspect of a demo install is making sure that your Java environment is compatible with Sakai.
The latest Sakai fdemo archive is available at http://source.sakaiproject.org/release/.
Once you have downloaded the archive, choose a location to unpack the files (your home directory is fine). When unpacked you will see a directory named sakai-src. Unix/Mac users should make sure that they have write permissions to the Tomcat servlet container files and directories before proceeding or startup permission errors may occur.
2.0 Verify/Install Java 1.6
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.
3.0 Start/Stop Tomcat
You can start Tomcat by running the appropriate start batch/shell script file from the root Tomcat directory:
Unix/Mac:
start-sakai.sh
Windows:
start-sakai.bat
Once Tomcat has loaded the Sakai application (again, this can take a couple of minutes) point your browser to
This will bring you to the Sakai gateway site from which you can create new accounts and log in to the system. If the gateway page fails to load, check the Tomcat logs for any errors and stack traces. If the gateway page does come up, log in with the default admin account (the username and password are both 'admin'). If you can log in without errors Sakai is alive and well.
Stopping Sakai involves shutting down Tomcat by running the appropriate stop batch/shell script file from the root Tomcat directory:
Unix/Mac:
stop-sakai.sh
Windows:
stop-sakai.bat
4.0 Explore Sakai
The Gateway Page
Once Tomcat has started successfully, you should be able to direct your browser to its gateway page at http://localhost:8080/portal (or replace 'localhost' with the name of the server where it's installed). From the gateway page you can create new accounts or browse for public site content. You could start by creating a new account, but that can also be done as an admin, and since the admin functions are needed to allow this account the right permissions, it's just as well to start by logging in as the admin user. Sakai's out-of-the-box admin account is simply named 'admin' (with password also 'admin'), so use those credentials to log in.
My Workspace
Every user on the system - including the admin - has a private site called My Workspace. It's the landing point upon logging in, and it's the first site tab visible at the upper left. Running vertically along the left-hand side of the screen are links to the various different tool pages within a given site, and the admin's My Workspace has a different set of such options here than most (each different type of account can be configured to have a different set of tools in its My Workspace by altering a template - see below).
Other Sites
Each new (accessible) site becomes visible as a tab along the top, to the right of My Workspace. For most users, they initially only have access to one site - their My Workspace. The admin user is a little different, in that it has access to two. The second admin site (which you can enter by clicking on its tab) is entitled Administration Workspace which, strangely enough, looks exactly the same as the admin My Workspace. It is.
Why the redundancy? Because you'll likely want to make these admin tools available to a particular user who doesn't have access to the admin's My Workspace (no one has access to other people's My Workspace on the system). To allow anyone access to the admin tools, you need only add them to the list of users of the Administration Workspace, and then promote them in the site to the "admin" role.
Admin Tools
Creating Users
The first thing you may want to do is to change the admin password to something secure, and to start creating a few sample users on your system. You can do both of those tasks through the Users tool on the left. To change the admin user's password, simply click on the 'admin' username in the list of users, and edit the fields on the subsequent page. To create users, click on the New User action link at the top of the tool page.
Creating Sites
If you're itching to create your first worksite, you may be tempted to dive directly into the Sites tool. That would probably be a mistake. The Sites tool is a powerful way to construct an entire site from the ground up, with fine-grained control over its every page, tool, and configuration detail. But this flexible power comes with a price, making for an intimidating interface and epic-scale workflow. The Sites tool is therefore best used as a way to tweak an existing site after the fact, once the standard pieces have been more expediently assembled.
The best way to start creating sites, therefore, is to use the Worksite Setup tool. Click on the New link at the top of the tool page, and then, for simplicity's sake, choose the Project site type, which will allow you to avoid issues of academic term, etc., that are provoked by a "course" site - issues which are probably unnecessary if you just want to start playing with the tools. Either type of site will serve, however: both types of sites have all the tools available to them.
Step through the remaining site creation pages, making your preferred selections. Be sure to click the Create Site button at the end of the process. After doing so, you should see the site title visible as a new tab along the top of the screen.
Adding Users to Sites
Since you set this site up as an admin, the admin is technically the owner of this site, and its only member at first. If you want to add other sample users to this site in different roles, you can do so through the Site Info tool of the site itself.
Click on the tab of your new site (which should now be visible) to enter it, and then click on the Site Info link along the left hand side. Site Info has a number of site maintainer functions available as action links across the top, and Add Participants is the one that will allow you to connect other users to the site. These users will of course need to have been previously created.
As long as we're here in Site Info, it's worth pointing out that the Edit Tools link at the top will allow you to remove and add tools from the site.
Experimenting with Tools
You may have noticed an extra tool appear in your site - one which you didn't explicitly choose - labeled Help. This tool provides online documentation of the various bundle tools, and other facets of the system. This should be your companion as you learn more about the software's functionality.
This Help tool is also reached in a context-sensitive way by clicking on the question mark icons at the upper right of any particular tool frame. Clicking on those question marks will open up the precise content of the tool you happen to be in at the time.
At some later point, when you become comfortable with the standard tools, you may wish to see other, more experimental tools that are available for Sakai. The Sakai distribution includes provisional tools that are still maturing, but can already serve needs in innovative ways that the standard ones do not. These extra tools require additional steps to enable, so that system users will not stumble across them inadvertently if that's not desired, but you are encouraged to evaluate them for your own deployment.
Where to Learn More
About the Project
The sakaiproject.org site offers the best background and orientation to the project and its goals, but chances are you've already seen it. For more particular information on the progress and roadmaps of certain tools or other initiatives, see the relevant Confluence spaces.
Community Participation
The Sakai Community provide email forums on a variety of topics. The lists are open, however, they do reject all non-member email, so you need to join a list before you can post to it, though you can still access its archives.
The four main Sakai community lists are:
Announcements (announcements@apereo.org) - items of community-wide interest in Apereo, including Sakai (receive newsletters; learn about conferences and deadlines; follow general progress on upcoming releases; participate in calls for community input). A low-volume, read-only list, which everyone should join.
Building Sakai (sakai-dev@collab.sakaiproject.org) - designing, developing, testing, and documenting Sakai (learn about the technical details of building tools or integrating services; find guidelines for design and development of tools and services; locate technical specifications; learn about plans for future releases). For designers, programmers, developers, and quality assurance.
Pedagogy (pedagogy@collab.sakaiproject.org) - teaching and learning, collaboration, and other uses of Sakai (learn about best practices; share experiences; connect with user communities with similar interests, K-12, Higher-Ed, Portfolios). For teachers, staff, students, researchers, instructional designers, instructional technologists and end-user support staff.
Deploying Sakai (production@collab.sakaiproject.org) - implementing, installing, configuring, and supporting Sakai (find release documentation; learn about performance tuning; browse suggested hardware and software configurations; share examples of training, tutorial and support materials). For sysadmins, DBAs, and technical support staff.
There are also a variety of smaller, topic-specific working groups that use email lists, which you may also find of interest as you get more involved with the community.
To join a Sakai mailing list point your browser to:
http://collab.sakaiproject.org/mailman/listinfo/
and join the lists that interest you. You will be asked to fill out a short form (username, password) and you can select whether or not to receive each list post individually (default) or batched in a daily digest. Once you have submitted your request you will be sent a confirmation email with a short set of instructions for confirming your subscription request.
About Technical Matters
Reference materials for various technical issues are best found in Sakai's subversion repository (where these installation documents are also stored) or in the project's Confluence wiki. The docs in subversion can be found in the reference module, e.g. https://source.sakaiproject.org/svn/reference. See in particular the docs/architecture folder contained there, which contains a wide-ranging collection of technical white papers.
The Confluence wiki is a more informal source of information, but also valuable and broader in scope. New developers in particular should visit the Programmer's Cafe. You are encouraged to create an account there and participate.
But often the most incisive information comes from direct interaction with your peers. As mentioned above, the Collab Server is the place to go for this. For technical questions the best (and most active) such group is DG: Development, also commonly referred to by its alias, "sakai-dev."