Skip to end of metadata
Go to start of metadata


This is a walkthrough for setting up a Sakai development environment on a laptop or desktop. These instructions will also work for setting up a development server though I suggest slightly beefier settings for memory. This is currently tailored for Sakai 2.9+. Once you have a Sakai development environment setup you should be able to program your own Sakai tools or modify existing tools.

Notes for developers using older versions of Sakai (2.8.x-)

Notes for windows users

  • change the "/" to "\" for all directory paths except those specified in the maven file
  • add the drive letter (C:) to your paths
  • use %VARIABLE% instead of $VARIABLE with environment variables
  • set your environment variables in Control Panel -> System -> Advanced -> Environment Variables

All of sakai and related programs should be installed in an opt directory which you will need full write access to, put this directory anywhere you want, this document will assume you have placed it in your root directory

  1. Install/Verify you have Java 1.7

    1. To check: Run java -version on the command line
    2. If not correct, download the J2SE SDK (make sure you get the JDK and not JRE) from:
    3. Install it (the SDK) to /opt/java
      • Note: Install the JRE to a different directory (probably the default, especially under windows) or you will have problems
    4. Set environment variable: JAVA_HOME=/opt/java
      • Mac users: JAVA_HOME=/Library/Java/Home
      • Windows users default: JAVA_HOME=C:\j2sdkXXX (where "XXX" is the version - for example "j2sdk1.7.0_11")
    5. Add $JAVA_HOME/bin to PATH
    6. Set JAVA_OPTS for tomcat in the tomcat/bin/setenv file (see Install Tomcat 7 / 8)

      export JAVA_OPTS="-server -Xmx1028m -XX:MaxPermSize=320m -Djava.awt.headless=true -Dsun.lang.ClassLoader.allowArraySyntax=true"
  2. Install/Verify you have MySQL 5.1 or later 

    • MySQL -
      • You should download the MySQL Community Server
      • NOTE: MySQL 5.5.x works but there are minor issues (mostly related to creating some profile 2 tables). If you already have 5.5 then you probably do not need to downgrade
    1. To check: Run mysql --help on the command line
    2. If not, download MySQL from:
    3. Custom install to /opt/mysql (options vary slightly based on operating system)
      • Linux users should install MySQL using a package or binaries if possible
      1. Choose standard configuration
      2. Install as a windows service (Windows only)
      3. Launch automatically (recommended)
        • If you choose not to do this, make sure that you startup MySQL each time before you try to run Sakai
      4. Include the bin directory in Path
      5. Don't use an anonymous account
      6. Set your root password to "mysqlpwd1"
    4. Update the mysql config file
      • For linux/OSX this is going to be: /etc/my.cnf
      • Windows: this file will be called my.ini and located in the dir you installed mysql into
      • MySQL provides a number of preconfigured option files that can be used as a starting point for configuration. Look for my-small.cnf, my-medium.cnf, my-large.cnf and my-huge.cnf.
      1. Add the following to the [mysqld] section

        default-storage-engine = InnoDB
        lower_case_table_names = 1
      2. OPTIONAL for 5.5: Add this to enable logging

  3. Setup Sakai DB (schema) and user

    1. Create the sakai database and sakai user (password=ironchef)
    2. Run the following from a command line prompt:

      mysql -uroot -pmysqlpwd1
      • Note: You can also do the following if you prefer to be prompted for the password: mysql -uroot -p
    3. Then run these commands from the mysql prompt (one command per line):

      create database sakai default character set utf8;
      grant all privileges on sakai.* to 'sakai'@'localhost' identified by 'ironchef';
      grant all privileges on sakai.* to 'sakai'@'' identified by 'ironchef';
      flush privileges;
    4. [Optional] Download and install mysql query browser
      2. You do not have to do anything with query browser now
  4. Download and setup Maven 2.2.x+ stable package

    1. Download Maven 2.2.X (minimum of 2.2.1) -
      • NOTE: some support exists for Maven 3 but there are a few things that do not work as of 6 Sep 2011
    2. Extract to /opt (should create apache-maven-2.X.X folder)
    3. Set environment variable: MAVEN2_HOME=/opt/apache-maven-2.X.X
    4. Add $MAVEN2_HOME/bin to PATH\
    5. Set the MAVEN_OPTS environment variable (in linux/OSX this is typically done in ~/.bash_profile)

      export MAVEN_OPTS='-Xms128m -Xmx796m -XX:PermSize=64m -XX:MaxPermSize=172m'

      • Adding -XX:+AggressiveOpts may speed up your builds depending on your OS, JVM, and system hardware
  5. Install/Verify you have Subversion

    1. To check: Run svn --version on the command line
      • Get the subversion binaries and not the source, if possible
      • If there are no binaries for your platform, get the source and use the configuration options --with-ssl and --with-libs
    2. Extract to /opt (should create subversion-1.2.3)
      • Windows users will want to rename the extracted directory
      • Unix users will probably want to use a package for their flavor
    3. Set environment variable: SUBVERSION_HOME=/opt/subversion-1.2.3
    4. Add $SUBVERSION_HOME/bin to PATH
  6. Download and setup tomcat 7.0.21+ (stable only)

    • Apache Tomcat -
    • 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)
    • 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-
      Download Tomcat 8 if you're using Sakai 11 -
      (The directions below are mostly the same for 7 or 8, but the 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 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/*

    Configure tomcat 7/8 to use the old tomcat 5.5 classloader dirs, this is not needed for the master branch of Sakai and Sakai 11.

    1. Edit conf/
      1. Add the following to the line that begins with "common.loader=..."

        • Tomcat 7

        • Tomcat 8

      2. Add the following to the line that begins with "server.loader=..."

      3. Add the following to the line that begins with "shared.loader=..."

    2. Create the directories

      mkdir -p shared/classes shared/lib common/classes common/lib server/classes server/lib

    Improve startup speed

    You can improve startup speed under both Tomcat 7 and Tomcat 8 significantly.

    Tomcat 7

    Edit the file conf/ and add the property to the bottom


    Tomcat 8

    Edit the file conf/context.xml and add this JarScanFilter block to the context


  7. Download and setup MySQL Connector/J stable

    1. Download connector for your version of MySQL
      1. If running mySQL 5.0-5.1
        Download version 5.0.8+ from
      2. If running MySQL 5.1+
        Download version 5.1+ from
      • NOTE: the version numbers do not directly align despite the way they appear to here
    2. Extract the file to /opt
    3. Copy mysql-connector-java-<version>-bin.jar to $CATALINA_HOME/common/lib
    4. Delete the extracted folder
  8. Use Subversion to download sakai code (Sakai 10 and earlier) or use Git/Github to download sakai code (Sakai 11 and later)

    1. Change to the /opt directory
    2. Checkout source from trunk (absolute latest stuff) or a release branch or tag:
      1. Trunk: svn checkout sakai-trunk
      2. 2.9.x Branch: svn checkout

        Alternative Sakai 2.9.x repository

        Should you run into errors related to missing dependencies when building source from the above repository with Maven (Step 11 below), attempt to checkout from instead

      3. If you want a version other than these, browse the tags and branches at
    3. Checkout will take about 5-10 minutes
    4. The directory created by subversion will be referred to as <sakai-src> directory (this could be whatever you want; above examples use 'sakai-trunk' and 'sakai-2.9.x')
  9. Setup file

    1. Create sakaidirectory in $CATALINA_HOME
      • $CATALINA_HOME should be /opt/tomcat if you have been following these instructions
    2. Copy the default config from to $CATALINA_HOME/sakai/
    3. Edit the file for a MySQL dev environment. Starting at the section marked # DATABASE:
      1. Set BaseDataSource username
        1. Set username@javax.sql.BaseDataSource=sakai
      2. Set BaseDataSource password
        1. Set password@javax.sql.BaseDataSource=ironchef
      3. Find the section: # HSQLDB settings and verify following lines are commented out

        # HSQLDB settings (DEFAULT)                                                                                                                               
        #validationQuery@javax.sql.BaseDataSource=select 1 from INFORMATION_SCHEMA.SYSTEM_USERS
        # Two hsqldb storage options: first for in-memory (no persistence between runs), second for disk based.
      4. Find the section: # MySQL settings and uncomment the 6+ lines in it

        # MySQL settings
        validationQuery@javax.sql.BaseDataSource=select 1 from DUAL
    4. Save the changes to the file


  10. Create maven settings.xml file

    1. Create a new xml file in your user home directory in the .m2 directory called settings.xml
    2. Add the following lines:
      • Note: Unfortunately, Sakai does not use the standard appserver.home so you have to specify a sakai.appserver.home
      • Note: The sakai.appserver.home must be C:\opt\tomcat for windows users
      • Note: Do not include trailing / or \ slashes in the directory paths
    • (optional) You can specify the tomcat home to be an environment variable like so:
    • (optional) Users who use a network proxy need to add the following to their file
      • If you do not use a username or password for your proxy just leave out those 2 lines
      • You only need the nonProxyHosts option if you have a local maven repo that does not require the proxy to be accessed
      • Note: Maven 2 doesn't support Microsoft's NTLN authentification scheme. If you connect to a proxy like ISA you will need to use a tool, such as to proxy your traffic
  11. Use Maven to build Sakai

    1. Open a command line shell
    2. Change directory to /opt/<sakai-src>
    3. Execute mvn clean install to build Sakai using maven
      • Note: The build will take an extra 5-10 minutes to download dependencies the first time
    4. Execute mvn sakai:deploy to deploy Sakai to your tomcat using maven
    5. Partial builds are supported by the maven2 build system
      You can now do a "mvn clean install sakai:deploy" from any subdirectory and build just that code
    6. Once you have downloded the jars you can run maven off-line with mvn -o clean install sakai:deploy
  12. Start Tomcat and check to make sure Sakai runs

    1. Start tomcat using $CATALINA_HOME/bin/startup

      Viewing an active launch log in Linux

      If you are in Linux you can view the activity log as its generated by using "# ./ run" from Tomcat's bin directory instead of This is helpful for viewing potential errors as they happen or to know if Tomcat has locked-up during a launch. A launch will have completed when "INFO: Server startup in xxxx ms" is displayed in the terminal.

    2. Allow 1 minute+ for tomcat to start up
    3. Open http://localhost:8080/ to verify tomcat is running
    4. Open http://localhost:8080/portal to verify sakai is running
    5. Login to sakai as username:admin, password:admin
    6. Shutdown Tomcat using $CATALINA_HOME/bin/shutdown
  13. Install Eclipse 3.2+ stable

    • Eclipse -
      • Note: If you already have eclipse 3.1.x installed, your best best is to start over with a fresh install rather than attempting to upgrade
      • Note: If you have not installed eclipse already, you should download the WebTools Platform: All-in-one package for Eclipse 3.3+ which includes Eclipse and all of the necessary webtools packages, this is much faster and easier than downloading them seperately, you can skip the WebTools step if you do this, here are instructions to install the Eclipse WebTools
    1. Download the newest stable version
    2. Extract the downloaded file to /opt
      • Windows users should extract to c:\
      • Mac users should use the installer and put it in Applications
    3. Run eclipse to verify it works (/opt/eclipse/eclipse)
      • Windows users: c:\eclipse\eclipse.exe to run eclipse
      • Note: If it does not work, there is probably a problem with your java install
    4. Set the memory settings for Eclipse
      • The default memory settings for Eclipse are much too low to handle the number of webapps in a full Sakai installation
      1. Shutdown eclipse if it is running
      2. Edit the eclipse.ini file in the directory you extracted/installed eclipse
      3. Change the settings from something like this:
        to something like this (leave any params that do not match these alone):
        • Windows users should not use notepad to edit this file, use wordpad or edit (command line)
        • Mac users will need to take additional steps to edit the eclipse.ini file
        1. Control-click on the Eclipse Application icon and select Show Package Contents
        2. Double-click on the Contents folder
        3. Double-click on the MacOS folder, the eclipse.ini file should be here
        4. Full path: eclipse/
    5. Set the JVM
      • The default JVM will be the one in the JRE, things will work better if you change this to the one in the J2SE
      1. Startup eclipse if it is not running
      2. Select Window -> Preferences -> Java -> Installed JREs
      3. Select the current installed JRE
      4. Click the Edit button
      5. Click Browse and navigate to the home directory of your JAVA installation (e.g. /opt/java)
      6. Click OK to save and then OK to Finish
        • Running Eclipse with a different JVM from the default
          Add -vm /opt/java/bin/java after the eclipse executable
        • You must include the full path to the java executable file
  14. Add subclipse to Eclipse

    1. Startup eclipse
    2. Select Help -> Software Updates
    3. Select Available Software, click Next
    4. Click Add Site
    5. Enter for the URL
    6. Click Finish
    7. Check the Subclipse box and click Next
      • Ignore the integrations unless you have a need for them, they can stop the install from working
    8. Accept terms, click Next, click Finish, click Install All
    9. Restart the workbench when asked
    • Add bin and target to global svn ignore in Eclipse (Optional)
      • This will keep you from committing bin and target directory files when you add projects to svn
      1. Click on Window -> Preferences
      2. Select Team -> Ignored Resources
      3. Click on Add Pattern and enter "bin"
      4. Click on Add Pattern and enter "target"
      5. Click on Add Pattern and enter "m2-target"
      6. Click on Apply and then OK
  15. Add Maven Eclipse Plugin to Eclipse

    1. Startup eclipse
    2. Select Help -> Software Updates
    3. Select Available Software, click Next
    4. Click Add Site
    5. Enter for the URL
    6. Click Finish
    7. Expand the Maven Integration for Eclipse update site
    8. Check the Maven Integration box and click Next
      • Ignore the optional parts unless you have a need for them
    9. Accept terms, click Next, click Finish, click Install All
    10. Restart the workbench when asked
  16. Add Lombok plugin to Eclipse [OPTIONAL]

    1. Shutdown eclipse
    2. Follow the steps on the page linked above
    3. Restart eclipse
    • NOTE: this is only required for certain parts of the code that use the lombok library (a limited set)
  17. Import Sakai source code into Eclipse

    1. [OPTIONAL] Run the following maven commands in your sakai-src root folder (e.g. /opt/cafe-2.5.x)
      This will clean out any eclipse files that are in there already:

    2. [OPTIONAL] Generate the eclipse files using maven (this is not required and not recommended)
      This will generate valid eclipse .project and .classpath files from the maven build

      • Special Case: If your workspace is in a different location, I've found that this option is needed passed to maven, otherwise the dependencies get incorrect.  -Declipse.workspace=..

        • Passing the full path to the local workspace or current directory might also work
      • If you are using the Maven Plugin for Eclipse then you should run this instead:

    3. Startup eclipse if it is not running
    4. Create a new workspace for Sakai
      1. Click on File -> Switch Workspace
      2. Enter "WS-Sakai" in place of the default "workspace" directory
      3. Click OK (eclipse will restart)
        • The following steps should be done in the WS-Sakai workspace
    5. Add Maven Repository libraries to classpath
      • NOTE: This is for backwards compatibility with projects using the M2_REPO variable so it can be skipped
      1. Select Window -> Preferences -> Java -> Build Path -> Classpath Variables
      2. Add MAVEN_REPO classpath variable with the path to the local maven repository (Sakai 2.4 or lower)
        • The path should be: $USER_HOME/.maven/repository
      3. Add M2_REPO classpath variable with the path to the local maven repository (Sakai 2.5 or higher)
        • The path should be: $USER_HOME/.m2/repository
    6. Switch to the Java perspective (Window -> Open Perspective -> Java)
      • Make sure you are in the package explorer
    7. Turn off Automatic builds
      • Select Project and uncheck Build automatically
    8. Select File -> Import -> Existing Projects into Workspace
      1. You can either import the entire sakai source tree (e.g. /opt/sakai-2.9.x) or selectively choose specific sub-projects you'll be working on (e.g. /opt/sakai-2.9.x/announcement) 
      2. Click Finish to import the selected projects
        • This will take awhile, probably 5+ minutes
      3. Clean all Sakai projects
        1. Select Project -> Clean
        2. Select Clean all projects
        3. Check Start a build immediately
        4. Click OK
      4. Build All (Project -> Build All)
        • There will be hundreds of warnings, do not worry about these
    9. Turn back on Automatic builds
      • Select Project and check Build automatically
      • Select project and then use the down triangle menu to add Filters (target, m2-target)
  • No labels


  1. Nice work here.

    Is discussion of a local svn repository discussed anywhere? After all the developer will be enhancing the value of Sakai to their local organization by modifying and adding to the source they've now exported and loaded into eclipse.

    Would be a shame not to have the local work under revision control.

  2. Complements to Aaron and contributers to this guide. Worked very well.

    Comments and minor nitpicks after after install:

    • for beginners, a separate page on what PATH is and on setting environmental variables might be helpful at lowering the barrier to installing (especially if using a new OS)
    • Instruction 2.3 (mysql install) - Mac Users installation issue – if you have already installed mysql 5.0 and need to use mysql 4.1, you will run into the error "you cannot continue. there is nothing to install". In my case, this was fixed by removing "mysql-standard-5.0.15-osx10.4-powerpc.pkg" and then installing (apparently mysql expects you to have only one version of mysql installed at a time).
    • Instructions 4.3, 5.3, and 6.7 fail if the user (a) has already installed or (b) chooses a directory other than what is given. Step 8 (svn checkout) and in particular 8.4 provides more flexible instructions.
    • Instruction 9.1 - as mentioned by other commenters - there was no mention of $TOMCAT_HOME before instruction 9.1 - this should be $CATALINA_HOME (or there should be an explicit instruction to set $TOMCAT_HOME).
  3. Question: Do we have to restart Tomcat each time we do a build?

    I am trying to develop a tool and even after using antiJARLocking="true"
    for Windows, I have to restart Tomcat in order to make my code work and
    it's taking me a long time to develop. Any suggestions?

  4. Hello,

    I have to make a new tool in Sakaï, and customizing a little Sakaï. I follow this instruction, but a I didn't understand very well the method of developpement...

    My source is in this location :

    Tomcat is here :

    I compile the code of Sakaï into Eclipse. But, how can I configure Eclipse to automatically deploy all sakai source into tomcat ? Is this possible ?

  5. Hi there - this is a great guide. Thanks very much to everyone who has contributed.

    I'm working on a project where some of these tools are required to be set up to run Sakai and others are not. When directing people to this site from my documentation, it'd be great to link them directly to the step they need instead of the top of the page. This can be done by placing anchors within the Wiki Markup. The anchors could then be referenced externally (or internally, say, for a table of contents or dependent steps) to jump to certain sections within the page.

    This is a pretty simple task and I'd be happy to do it if it's something the Programmer's Cafe WG finds useful and if I were given permissions to edit the page.


  6. Cool, I got it all to work but I had to add the M2_REPO variable instead of the MAVEN_REPO variable in instruction 17.3. The M2_REPO has to point to /opt/.m2/repository.

    Also you need one more project imported: cm-api


  7. Now, Db-impl, should be reconfiged to M2_REPO/commons-pool/commons-pool/1.3/commons-pool-1.3.jar


    1. This was reported as a bug in:
      Hopefully it will be fixed soon.

  8. And there is still another we should be careful.
    The jdk 1.6 seems not to be compatible with maven 2, use jdk 1.5 !

  9. Please clarify the following. At the top of this page, the text says
    "This is currently tailored for Sakai 2.3.x."

    But if you follow the link in Notes for developers using Sakai 2.4.x-, it says

    If you are developing for 2.5.x, please check out the current Development Environment Setup Walkthrough which covers the newer version of Sakai with the changes for maven 2.

    Confusing. Is that a broken link, or is this really for 2.5.x. I think the latter, but clarification/correction would be good.

    1. Yep, a typo. Thanks for pointing it out. I've updated the page.

  10. For Java developers on Windows who already have a lot of Java stuff installed on their machine (for example, Java 6, Tomcat 6.x, etc.) for other projects, you might find the following helpful. Create a separate Windows user account called Sakai, and remove Java, Tomcat, Maven, etc. environment variables from the system variables (if you defined them there). Instead make them user variables, and augment the system Path variable by including a user variable

    That way your Sakai account will use the correct configuration and you can continue to use Java 6, Tomcat 6.x, etc. for other work. I took this approach and it's working pretty nicely.

    Note that the JDK installer drops the java.exe, javaw.exe and javaws.exe executables in C:\WINDOWS\system32, and that segment appears early on the path. It appears that Windows puts the user-defined path segments after the system-defined path, and the system-defined path includes C:\WINDOWS\system32. I solved that by removing java.exe (along with the other two) from C:\WINDOWS\system32.

    Anyway hope somebody finds that helpful.

    (warning) Also, there appears to be an unstated dependency on the Eclipse part. Eclipse is complaining that site-manage-api needs cm-api.

  11. Unknown User (alanhoyle)

    There are a few minor errors in this, including the following:

    Step 1.6: should be moved into step 6, as we can't do it without having tomcat first.

    Step 10.1: Some flavors of Windows (XP at least) won't let you create or rename a directory that begins with a "." through the GUI. To get around this limitation, go out to a command line, change to the home directory (probably by running something like "cd c:\Documents and Settings\username") and run "md .m2" at the prompt. From there, you can go back into the GUI and work as normal.

    Step 14: Should say to download the "most recent WTP Release build." Having this specified would have saved me hours of frustration. More recent builds from the "Maintenance" or "Stable (Milestone)" sections don't include the "All-In-One" packages, and instead require manual installation of all the prerequisites.

    Step 15 and 16: Both of these installations have "Integrations" as part of the features they attempt to install if you try to install the whole thing by default. (AJDT and Mylyn for SpringIDE; Buckminster and Mylyn for Subclipse.) If you don't uncheck those "Integrations" boxes, Eclipse won't let you install the add-ons: the "Finish" button is disabled and an error message appears at the top of the window.

    Step 17.3.2: MAVEN_REPO is for Maven 1.x. Instead, one should create M2_REPO and set it equal to $USER_HOME/.m2/repository or

    Step 17.6.1: the path should be "/opt/<sakai-src>" or "/opt/cafe_trunk" not the 2.2 version.

    Step 17.6.3: One also needs to select "cm-api" in order to build.

    See you all in Newport Beach!

  12. Steps 1.6 and 6.8 have slightly different JAVA_OPTS, what about just refering 6.8 in 1.6 and not providing a value again.

    Step 2.1, mysql -V (or --version) has a cleaner output if you only want to know the MySQL version.

    1. it would also be very helpful if these memory-requests specified in JAVA_OPTS were given in the context of how-much-ram-the-example-server-has-available. for example, -Xmx2000m would be relatively meaningless on a 2gb server (who wants to use swap space to run your sakai? yikes!)

      • e.g. on a ##gb server, start with having your JAVA_OPTS include -Xmx####m and look for XXX behavior. adjust up if you see YYY, or down if you see ZZZ...
      • if your database is on the same server for a test-run, watch out for QQQ...

      simply saying "ask for this much ram" isn't all that helpful without a bit-o-context.

  13. at serensoft, we were experiencing lots of "java.lang.OutOfMemoryError: PermGen space" errors with sakai 2.5.x – until we added


    to JAVA_OPTS. the server is now very responsive – and no PermGen space errors, no restarts, in over a week, now. (smile)

    for now, our full JAVA_OPTS environment variable contains:


    1. in fact, we've had tomcat running at Serensoft for MONTHS at a time now, without any PermGen space errors. woo hoo!

      these days (knock on wood), the only time we restart it is after a svn install sakai:deploy as it's been rock solid

  14. On a Windows machine, I had issues with Maven 2. The problem was that there were spaces in the path to the repository. A bit of googling later, I found the solution: move the local repository.

    add "<localRepository>C:\maven2\repository</localRepository>" before <profiles> stanza

  15. Unknown User (

    Just a note re Eclipse 3.4, it's got WTP bundled already.

  16. For Eclipse 3.4 users doing software updates:
    1. WTP is already installed
    2. subclipse update selection should be made from the udate link given at:
    3. in springide update there is a dependency for eclipse 3.2; make sure you uncheck this.

  17. The m2eclipse plugin update site url is now:

    1. Looks like the m2eclipse plugin update site url is now:

  18. If on Windows, adding the -vm 'path/to/jdk' to the eclipse.ini file won't work properly, and you must create a shortcut to the eclipse.exe and add the -vm flag that way. Is this a bug? Ideally it should all be configured via the eclipse.ini. The m2eclipse plugi-in complains the loudest, that it can't find a JDK even though it may be apparently setup correctly.

    This is the target of my Eclipse shortcut in windows:

    C:\eclipse\eclipse.exe -vm C:\Java\jdk1.5.0_21\bin

    Also, Eclipse doesn't like spaces in the path to the JVM. So make sure you install ito somewhere without spaces. Watch out for the default, it's "Program Files", which Eclipse can't handle.

    1. Try adding the -vm and its parameter to the eclipse.ini file as two separate lines:
      C:/Program Files/Java/jdk1.6.0_14/bin/javaw.exe
      Probably this has to be at the beginning of the file (at least before any multi-line options like -vmargs).

      1. I had it on two lines and the m2eclipse still wouldn't recognise it. The only solution was reinstalling java to a location with no spaces. Didn't try at beginning of file though. Does that work?

        1. This is the eclipse.ini I use for Galileo Eclipse:

          1. Ok, I'm on Ganymede (3.4) so it might be different in that regard. Was it the same on 3.4 do you remember? In any case, I've moved back to my Mac now where it picks up the JDK properly.

            1. I'm not 100% sure of this, but I think it has been a similar setup for 3.4.

  19. I have followed these instructions and I already have working the environment. Just two things:

     - The m2eclipse doesn't work when doing mvn eclipse:m2eclipse.

    [INFO] ------------------------------------------------------------------------
    [INFO] Required goal not found: eclipse:m2eclipse in org.apache.maven.plugins:maven-eclipse-plugin:2.8

    -Subclipse needs JavaHL to work with Subversion and it's not included in Subversion 1.6.12, neither in subclipse 1.6.x. It seems that the only way to have JavaHL is compiling the source of Subversion with the --enable-javahl argument.

    A good tutorial about this:

  20. Wow!

    Excellent guide. Congratulations to the team.

  21. Note that you dont need the settings listed above for the ~/.m2/settings.xml file, which saves a step on new environments. You will need to specify the path to tomcat for your builds though via -Dmaven.tomcat.home=/path/to/tomcat/. Useful for dev environments that have multiple Sakai installs.

  22. I tried the instructions (checked out from the trunk) with tomcat7.0.29 initially. I got too many errors during deployment of war files. But I was able to get the webapp running in tomcat5.5.35. Does anyone have the trunk installed on tomcat7? My Java version is "1.6.0_24". Please advise.

    Some of the errors are shown below:

    INFO: Starting Servlet Engine: Apache Tomcat/7.0.29
    Aug 18, 2012 11:15:15 AM org.apache.catalina.startup.HostConfig deployWAR
    INFO: Deploying web application archive /Developer/apache-tomcat-7.0.29/webapps/access.war
    Aug 18, 2012 11:15:16 AM org.apache.catalina.core.ContainerBase addChildInternal
    SEVERE: ContainerBase.addChild: start:
    org.apache.catalina.LifecycleException: Failed to start component [StandardEngine[Catalina].StandardHost[localhost].StandardContext[/access]]
    at org.apache.catalina.util.LifecycleBase.start(
    at org.apache.catalina.core.ContainerBase.addChildInternal(
    at org.apache.catalina.core.ContainerBase.addChild(
    at org.apache.catalina.core.StandardHost.addChild(
    at org.apache.catalina.startup.HostConfig.deployWAR(
    at org.apache.catalina.startup.HostConfig$
    at java.util.concurrent.Executors$
    at java.util.concurrent.FutureTask$Sync.innerRun(
    at java.util.concurrent.ThreadPoolExecutor$Worker.runTask(
    at java.util.concurrent.ThreadPoolExecutor$
    Caused by: java.lang.NoClassDefFoundError: org/apache/commons/collections/ExtendedProperties
    at java.lang.Class.getDeclaredFields0(Native Method)
    at java.lang.Class.privateGetDeclaredFields(
    at java.lang.Class.getDeclaredFields(
    at org.apache.catalina.util.Introspection.getDeclaredFields(
    at org.apache.catalina.startup.WebAnnotationSet.loadFieldsAnnotation(
    at org.apache.catalina.startup.WebAnnotationSet.loadApplicationServletAnnotations(
    at org.apache.catalina.startup.WebAnnotationSet.loadApplicationAnnotations(
    at org.apache.catalina.startup.ContextConfig.applicationAnnotationsConfig(
    at org.apache.catalina.startup.ContextConfig.configureStart(
    at org.apache.catalina.startup.ContextConfig.lifecycleEvent(
    at org.apache.catalina.util.LifecycleSupport.fireLifecycleEvent(
    at org.apache.catalina.util.LifecycleBase.fireLifecycleEvent(
    at org.apache.catalina.core.StandardContext.startInternal(
    at org.apache.catalina.util.LifecycleBase.start(
    ... 11 more
    Caused by: java.lang.ClassNotFoundException: org.apache.commons.collections.ExtendedProperties
    at org.apache.catalina.loader.WebappClassLoader.loadClass(
    at org.apache.catalina.loader.WebappClassLoader.loadClass(
    ... 25 more

    1. I was able to get the application started on Tomcat 7 using the info at

  23. Shouldn't Maven version be updated?  According to the source install guide,  Maven 3.0 or later is the required for performing Sakai 2.9 builds.

    1. That's not actually true. I can and do sometimes build 2.9 with maven 2.2. Things work better with maven 3 but it is not required (as per the pom file): 


  24. I found these instructions to be problem-free until I got to step 17b.  If it's not recommended, does that mean the recommendation is not to do it?  Maybe it should be removed from the instructions.  In any event, the "eclipse:eclipse" goal doesn't work and it appears that the "eclipse:m2eclipse" goal will only work once the project is imported into eclipse.


    Also, the "Existing Projects into Workspace" import doesn't work, because the code checked out from the repository isn't an Eclipse project.  The import method that seems to be the correct choice is "Existing Maven projects".



  25. New to the community, have found this a great guide on getting setup. Thank you!

    Working with Maven 2.2.1, Tomcat 7.0.5, MySQL 5.1.5 in Unix environment (OS X 10.9). Running into 1 issue with building sakai 2.9.x (Step 11). Checked out however attempt to build, using mvn -Pcafe clean install, fails. '' can't be found in sakai-maven, sakai-maven2-snapshots or sonatype-nexus-snapshots

    [INFO] Unable to find resource 'org.sakaiproject.entitybroker:entitybroker-assembly:zip:tomcat-overlay:1.5.4-SNAPSHOT'

    Did some searching but couldn't find this artifact or any posts specifically related to this. Am I missing something?

    P.S: Please do let me know if this is the wrong forum for such requests for help (smile)

    1. Try Maven 3. Also dont user the -Pcafe, it might be out of date, just do a full build. On modern systems it should be quite fast.

      As for the best forum, try signing up to the sakai-dev list at and posting there.

      1. Thanks Steve ! Trying this with Maven 3 now. Can successfully 'clean' (without using cafe), but 'install'  target still failing for sakai 2.9.x. Will look more closely at the build failures & check the sakai-dev list.

    2. Just thought I'd leave a comment in case anyone else run into the same issue. Looks like sakai-2.9.x branch is missing a number of resources, probably moved. I was able to get the full source for 2.9.x from checking out 2.9.x-all instead ( and building all 'mvn clean install'. Thanks to Matthew's comment here that tipped me off to this.

  26. hello ;

    I use this document to install sakai for the first time , I don't have any experience with .

    after installation done and try to lunch sakai I had this tomcat issue

    HTTP Status 404 - /portal

    type Status report

    message /portal

    description The requested resource is not available.

    Apache Tomcat/7.



    I have sakai2.9.3

    tomcat 7.0.54

    maven 2.2.1


    any help will be thankful for .

    1. Have a good day,


      I have the same issue in ubuntu server with sakai 11 and I don't know how to solve it, I appreciate your help to solve this issue.



  27. Hello,

    in my case installing Lombok for normal Eclipse didn't work. As you can see, it is only supported for STS and JDS variants. I had good experiences with Lombok on IntelliJ though.

    Eclipse and variantsRun lombok.jar as a java app (i.e. doubleclick it, usually) to install. Also add lombok.jar to your project. Supported variants: Springsource Tool Suite, JBoss Developer Studio


  28. What is meant by down triangle


    1. I imagine that just means an icon of a triangle, with the point of the triangle facing down. Often used as an interface element to indicate a pop-down menu is available. 

  29. After import sakai project into eclipse not able to run.

    Does we need to import single each & every component one by one or can we import all at atime.

    On which project does we need to run.



  30. Maven 3 requires plugin versions to be provided in all pom files, but it seems like many of the pom files are missing plugin versions. I am getting many of these errors when I try to deploy:

    [WARNING] 'reporting.plugins.plugin.version' for org.apache.maven.plugins:maven-javadoc-plugin is missing. @ org.sakaiproject.userauditservice:userauditservice:10.0, /Users/chrismurphy/Internnection/Dev/plexus/Plexus/userauditservice/pom.xml, line 73, column 15

    I understand that I could go in and add version numbers to all of the pom files, but there are dozens of places to add version numbers to, so I was wondering if anyone else encountered this problem and found an easier solution?