Development Environment Setup Walkthrough (2.5.x-2.8.x)

Information

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

1. Install/Verify you have Java 1.5

2. Install/Verify you have MySQL 4.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:

      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'; flush privileges; quit

   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.6+ stable package

5. Install/Verify you have Subversion

6. Download and setup tomcat 5.5.17+ (stable only)

7. Download and setup MySQL Connector/J stable

8. Use Subversion to download sakai cafe trunk

   1. Change to the /opt directory

   2. svn checkout https://source.sakaiproject.org/svn/cafe/trunk/ cafe_trunk

      1. If you want a version other than this one, browse the tags and branches at https://source.sakaiproject.org/svn/cafe/

      2. 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 https://source.sakaiproject.org/svn/cafe/trunk/ cafe-trunk

   3. Checkout will take about 5-10 minutes

   4. The directory created by subversion will be referred to as <sakai-src> directory

9. Setup sakai.properties file

   1. Create sakai directory 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 to $CATALINA_HOME/sakai

      • Note: 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 https://source.sakaiproject.org/svn/reference/trunk/docs/sakai.properties.
        Make sure you get the sakai.properties for the version of Sakai you are using (e.g. Sakai 2.4.x):
        http://source.sakaiproject.org/svn/reference/branches/sakai_2-4-x/docs/sakai.properties

   3. Edit the sakai.properties file for a MySQL dev environment. Starting at the section # 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

         ## HSQLDB settings - on by default #vendor@org.sakaiproject.service.framework.sql.SqlService=hsqldb #driverClassName@javax.sql.BaseDataSource=org.hsqldb.jdbcDriver #hibernate.dialect=org.hibernate.dialect.HSQLDialect #validationQuery@javax.sql.BaseDataSource=select 1 from SYSTEM_USERS # two hsqldb storage options: first for in-memory (no persistence between runs), second for disk based #url@javax.sql.BaseDataSource=jdbc:hsqldb:. #url@javax.sql.BaseDataSource=jdbc:hsqldb:${sakai.home}/db/sakai.db

      4. Find the section: ## MySQL settings and uncomment the 6+ lines in it

         ## 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.MySQLDialect 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:

        vendor@org.sakaiproject.db.api.SqlService=mysql

   4. Save the changes to the file

10. Create maven 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 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 -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

    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

14. Add Eclipse Web Tools Project (WTP)

15. Add subclipse to Eclipse

16. Add Maven Eclipse Plugin to Eclipse

17. Import Sakai source code into Eclipse