Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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.59+. Once you have a Sakai development environment setup you should be able to program your own Sakai tools or modify existing tools.

Note
titleNotes for developers using older versions of Sakai (2.48.x-)
Note
titleNotes for windows users
  • change the "/" to "\" for all directory paths except those specified in the maven build.properties 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
Info

Zach Thomas has created a screencast which walks developers through setting up their Sakai 2.5 development environment
http://aeroplanesoftware.com/wordpress/wp-content/uploads/2008/01/developing-for-sakai-getting-started960x540.mov
http://aeroplanesoftware.com/wordpress/wp-content/uploads/2008/02/developing-for-sakai-setting-up-eclipse960x540.mov

Tip

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.

    5

    7

    Include Page
    BOOT:Install Java 1.57+BOOT:
    Install Java 1.57+
  2. Install/Verify you have MySQL

    4

    5.1 or later 

    Include Page
    BOOT:Install MySQL 45.1BOOT:
    Install MySQL 45.1
  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:

      No Format
      
      mysql -urootu root -pmysqlpwd1p
      
      
      • 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):

      \
      No Format
      
      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'@'127.0.0.1' identified by 'ironchef';
      flush privileges;
      quit
      
      Wiki Markup
    4. [Optional\] Download and install mysql query browser
      1. http://dev.mysql.com/downloads/query-browser/1.1.html
      2. You do not have to do anything with query browser now
  4. Download and setup Maven 2.

    0

    2.

    6

    x+ stable package

    Include Page
    BOOT:Install Maven 2.2+BOOT:
    Install Maven 2.2+
  5. Install/Verify you have Subversion

    Include Page
    BOOT:Install SubversionBOOT:
    Install Subversion
  6. Download and setup tomcat

    5

    7.

    5

    0.

    17

    21+ (stable only)

    Include Page
    BOOT:Install Tomcat 5.5BOOT:Install Tomcat 5.57 / 8
    Install Tomcat 7 / 8
  7. Download and setup MySQL Connector/J stable

    Include Page
    BOOT:Install Mysql Connector 3.1BOOT:5+
    Install Mysql Connector 3.15+
  8. Use Subversion to download sakai

    cafe trunk

    code (Sakai 10 and earlier) or use Git/Github to download sakai code (Sakai 11 and later)

    1. Change to the /opt directory
    2. svn checkout Checkout source from trunk (absolute latest stuff) or a release branch or tag:
      1. Trunk: svn checkout https://source.sakaiproject.org/svn/
      cafe
      1. sakai/trunk/
      cafe_trunk
      1. If you want a version other than this one, browse the tags and branches at  sakai-trunk
      2. 2.9.x Branch: svn checkout https://source.sakaiproject.org/svn/

        cafe/subversion will create a "trunk" directory for you,
        you can use any directory name you like, just add a name after the checkout location:
        svn checkout

        sakai/branches/sakai-2.9.x/

        Tip
        titleAlternative 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 https://source.sakaiproject.org/svn/

        cafe

        sakai/

        trunk

        branches/

        cafe-trunk

        sakai-2.9.x-all instead

      3. If you want a version other than these, browse the tags and branches at https://source.sakaiproject.org/svn/sakai/
    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 sakai.properties file

    1. Create sakaidirectory in $CATALINA_HOME
      • $CATALINA_HOME should be /opt/tomcat if you have been following these instructions
      • Note: There were previously two configuration files, sakai.properties and placeholder.properties. These have now been combined into sakai.properties. You can attempt to manually combine the two files from a previous version, but it's better to start with the sample included with the sakai source in the reference directory.
    2. Copy sakai.properties from <sakai-src>/reference/docs Copy the default config from default.sakai.properties to $CATALINA_HOME/sakaiNote: This file may not be in your checkout if you have acquired one of the older versions of cafe - you can fetch it manually from here /sakai.properties
    3. Edit the sakai.properties file for a MySQL dev environment. Starting at the section marked # DATABASE CONFIGURATION:
      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 comment out 7+ lines in it

        settings and verify following lines are commented out

        No Format
        # ## HSQLDB settings -(DEFAULT) on by default
                                                                                                                                    
        #vendor@org.sakaiproject.servicedb.frameworkapi.sql.SqlService=hsqldb
        #driverClassName@javax.sql.BaseDataSource=org.hsqldb.jdbcDriver
        #hibernate.dialect=org.hibernate.dialect.HSQLDialect
        #validationQuery@javax.sql.BaseDataSource=select 1 from INFORMATION_SCHEMA.SYSTEM_USERS
        # twoTwo hsqldb storage options: first for in-memory (no persistence between runs), second for disk based.
        #url@javax.sql.BaseDataSource=jdbc:hsqldb:.mem:sakai
        #url@javax.sql.BaseDataSource=jdbc:hsqldb:file:${sakai.home}/db/sakai.db
        
      4. Find the section:

        ##

        # MySQL

        settings

        settings and uncomment the 6+ lines in it

        No Format
        # ## MySQL settings
        - make sure to alter as appropriate
        vendor@org.sakaiproject.db.api.SqlService=mysql
        driverClassName@javax.sql.BaseDataSource=com.mysql.jdbc.Driver
        hibernate.dialect=org.hibernate.dialect.MySQLDialectMySQL5InnoDBDialect
        url@javax.sql.BaseDataSource=jdbc:mysql://127.0.0.1:3306/sakai?useUnicode=true&characterEncoding=UTF-8
        validationQuery@javax.sql.BaseDataSource=select 1 from DUAL
        defaultTransactionIsolationString@javax.sql.BaseDataSource=TRANSACTION_READ_COMMITTED
        
      • Note that this line may be incorrect in the default file, it should read as shown:
        No Format
        
        vendor@org.sakaiproject.db.api.SqlService=mysql
        
    4. Save the changes to the sakai.properties file

       

  10. Create maven settings.xml file

    Include Page
    BOOT:Maven 2.x settings.xml fileBOOT:
    Maven 2.x settings.xml file
  11. Use Maven to build Sakai

    1. Open a command line shell
    2. Change directory to /opt/<sakai-src>
    3. Execute mvn -Pcafe clean installinstall to build Sakai using maven
      • Note: The build will take an extra 5-10 minutes to download dependencies the first time
    4. Execute mvn -Pcafe sakai:deploy to deploy Sakai to your tomcat using maven
    5. Unlike in maven1, the maven2 Sakai plugin downloads automatically (this allows you to deploy the parts of projects to the right locations in tomcat)
    6. 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
    7. 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

      Tip
      titleViewing an active launch log in Linux

      If you are in Linux you can view the activity log as its generated by using "# ./catalina.sh run" from Tomcat's bin directory instead of startup.sh. 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

    Include Page
    BOOT:Install Eclipse 3.2+BOOT:
    Install Eclipse 3.2+
  14. Add

    Eclipse Web Tools Project (WTP) Include PageBOOT:Install Eclipse WTPBOOT:Install Eclipse WTP

    Add subclipse to Eclipse

    Include Page
    BOOT:Install SubclipseBOOT:
    Install Subclipse
  15. Add Maven Eclipse Plugin to Eclipse

    Include Page
    BOOT:Install Maven Eclipse PluginBOOT:
    Install Maven Eclipse Plugin
  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

    Include Page
    BOOT:Import Sakai source into EclipseBOOT:
    Import Sakai source into Eclipse