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.

Notes for developers using Sakai 2.4.x-

Developers who are using Sakai 2.4.x or lower should use the Development Environment Setup Walkthrough (2.2.x-2.4.x)

Notes for developers using Sakai 2.9.x+

Developers who are using Sakai 2.9.x or higher (trunk after Sept 2011) should use the Development Environment Setup Walkthrough

Notes 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

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

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

Install/Verify you have Java 1.5
1. To check: Run java -version on the command line
2. If not correct, download the J2SE SDK from:
  - Sakai 2.7.x or less: http://java.sun.com/j2se/1.5.0/download.jsp
  - Sakai 2.8 or higher: http://www.oracle.com/technetwork/java/javase/downloads/index.html
  - Mac OS X users will have Java 1.5 or 1.6 by default
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.5.0_11")
5. Add $JAVA_HOME/bin to PATH
6. Set JAVA_OPTS for tomcat in the tomcat/bin/setenv file (see Install Tomcat 5.5)
```
JAVA_OPTS='-server -Xmx964m -XX:MaxPermSize=172m -Djava.awt.headless=true'
```
  - These settings are for developers
  - More info on JVM server settings: Sakai Admin Guide - JVM Tuning
Install/Verify you have MySQL 4.1
- MySQL - http://www.mysql.com
  - Some have reported that MySQL 5.0.x works just fine as well. If you already have this version, there's likely no point in downgrading to 4.1.*.
1. To check: Run mysql --help on the command line
2. If not, download MySQL from:
  - http://dev.mysql.com/downloads/
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 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"
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
Download and setup Maven 2.0.6+ stable package
- Maven - http://maven.apache.org/
1. Download Maven 2.2.X (minimum of 2.0.10) - http://maven.apache.org/download.html
2. Extract to /opt (should create maven-2.X.X folder)
3. Set environment variable: MAVEN2_HOME=/opt/maven-2.X.X
4. Add $MAVEN2_HOME/bin to PATH\
5. Set the MAVEN_OPTS environment variable
  MAVEN_OPTS='-Xms256m -Xmx796m -XX:PermSize=64m -XX:MaxPermSize=136m'
  - Adding -XX:+AggressiveOpts may speed up your builds depending on your OS, JVM, and system hardware
Install/Verify you have Subversion
- Subversion - http://subversion.tigris.org/
1. To check: Run svn --version on the command line
  - http://subversion.apache.org/packages.html
  - 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
Download and setup tomcat 5.5.17+ (stable only)
- Apache Tomcat - http://tomcat.apache.org/
- Note: Always do a fresh install of Tomcat
- 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 5.5.18\
1. Download tomcat 5.5 - http://tomcat.apache.org/download-55.cgi
  - 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
2. Extract to /opt (symlink the apache-tomcat-5.5.x directory to tomcat after extracting)
  - Windows users should just rename the directory since they cannot symlink
3. Download the java 1.4.2 compat patch (compat.zip)
  - NOTE: You should NOT install this patch if you are using Sakai 2.4 or higher
4. Extract the files to the same location as tomcat itself
5. Modify conf/server.xml for international character support
  1. Add URIEncoding="UTF-8" to the Connector element
    - <Connector port="8080" URIEncoding="UTF-8" ...
6. Set environment variable: CATALINA_HOME=/opt/tomcat
7. Add $CATALINA_HOME/bin to PATH
8. Setup the SETENV file in the tomcat/bin directory with JAVA_OPTS (from Install Java 1.5+)
  1. Mac/Linux: Create a file called setenv.shwith the following:
    export JAVA_OPTS="-server -XX:+UseParallelGC -Xmx768m -XX:MaxPermSize=160m -Djava.awt.headless=true -Dhttp.agent=Sakai -Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false -Dsun.lang.ClassLoader.allowArraySyntax=true"
  2. Windows(PC): Create a file called setenv.batwith the following:
    set JAVA_OPTS=-server -XX:+UseParallelGC -Xmx768m -XX:MaxPermSize=160m -Djava.awt.headless=true -Dhttp.agent=Sakai -Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false -Dsun.lang.ClassLoader.allowArraySyntax=true
Download and setup MySQL Connector/J stable
- Mysql Connector J - http://www.mysql.com/products/connector/j/
1. Download connector for your version of MySQL
  1. If running mySQL 4.1
    Download version 3.1.12+ from http://dev.mysql.com/downloads/connector/j/3.1.html
  2. If running MySQL 5.0.x
    Download version 5.0.4+ from http://dev.mysql.com/downloads/connector/j/5.0.html
2. Extract the file to /opt
3. Copy mysql-connector-java-<version>-bin.jar to $CATALINA_HOME/common/lib
4. Delete the extracted folder
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
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

Create maven settings.xml file

Create a new xml file in your user home directory in the .m2 directory called settings.xml
- Note: This is probably c:\documents and settings\<username> in Windows
- Download a sample settings.xml file (setup for windows users)

Add the following lines:

<settings xmlns="http://maven.apache.org/POM/4.0.0"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                      http://maven.apache.org/xsd/settings-1.0.0.xsd">
  <profiles>
    <profile>
      <id>tomcat5x</id> 
      <activation>
        <activeByDefault>true</activeByDefault> 
      </activation>
      <properties>
        <appserver.id>tomcat5x</appserver.id> 
        <appserver.home>/opt/tomcat</appserver.home> 
        <maven.tomcat.home>/opt/tomcat</maven.tomcat.home> 
        <sakai.appserver.home>/opt/tomcat</sakai.appserver.home> 
        <surefire.reportFormat>plain</surefire.reportFormat>
        <surefire.useFile>false</surefire.useFile>
      </properties>
    </profile>
  </profiles>
</settings>

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:
```
      <maven.tomcat.home>${env.CATALINA_HOME}</maven.tomcat.home>
```
(optional) Users who use a network proxy need to add the following to their file
```
...
  <proxies>
     <proxy>
        <active>true</active>
        <protocol>http</protocol>
        <host>www.your.proxy.host</host>
        <port>80</port>
        <username>your_username</username>
        <password>your_password</password>
        <nonProxyHosts>localhost</nonProxyHosts>
     </proxy>
  </proxies>
</settings>
```
- 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 http://ntlmaps.sourceforge.net/ to proxy your traffic

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
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
Install Eclipse 3.2+ stable
- Eclipse - http://www.eclipse.org/
  - 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 http://www.eclipse.org/
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:
    -vmargs -Xms40m -Xmx256m
    to something like this (leave any params that do not match these alone):
    --launcher.XXMaxPermSize 256M -vmargs -Xms128m -Xmx1024m -XX:+UseParallelGC
    - 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/Eclipse.app/Contents/MacOS/eclipse.ini
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
- More Eclipse tips here: Eclipse notes
Add Eclipse Web Tools Project (WTP)
- Web Tools Project - http://www.eclipse.org/webtools/
- NOTE: Installing the all-in-one-package or manually installing are far more reliable and definitely recommended over using the updater method (the last one)
- NOTE: Only install released versions, the development versions tend to be unstable and buggy
1. WebTools Platform: All-in-one (fastest, recommended)
  - This should only be used if you do not already have Eclipse installed
  1. Go to eclipse downloads
    - Older versions at WTP downloads
  2. Click Eclipse IDE for Java EE Developers and choose a download mirror
  3. Extract the package to whereever you want to install eclipse (normally your drive root /eclipse)
  4. Adjust the config as indicated in Install Eclipse 3.2+
  5. Startup Eclipse
2. Manual installation (faster)
  - http://www.eclipse.org/webtools/downloads/
  1. Download WTP 1.5.x (Eclipse 3.2) or 2.0.x (Eclipse 3.3) to your desktop
  2. Shutdown Eclipse
  3. Extract the package to your Eclipse installation directory
  4. Startup Eclipse
3. Install using the Eclipse updater (somewhat easier but not recommended)
  1. Start eclipse
  2. Select Help -> Software Updates -> Find and Install
  3. Select Search for new features to install, click Next
  4. Choose the Eclipse.org Update Site (or The Eclipse Project Updates) and click Finish
  5. Select WTP 0.7 (or newer)
    - Note: If it is not listed, use the following update URL: http://download.eclipse.org/webtools/updates/
  6. Click Select Required
  7. Click Next and follow installation instructions
  8. Accept terms, click Finish
  9. Click Install All
  10. Restart the workbench when asked
Add subclipse to Eclipse
- Subclipse - http://subclipse.tigris.org/
1. Startup eclipse
2. Select Help -> Software Updates
3. Select Available Software, click Next
4. Click Add Site
5. Enter http://subclipse.tigris.org/update_1.6.x 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
Add Maven Eclipse Plugin to Eclipse
- Maven Plugin for Eclipse - http://m2eclipse.codehaus.org/
1. Startup eclipse
2. Select Help -> Software Updates
3. Select Available Software, click Next
4. Click Add Site
5. Enter http://m2eclipse.sonatype.org/sites/m2e 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
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:
```
mvn eclipse:clean
```
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
```
mvn eclipse:eclipse
```
  - 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:
    mvn eclipse:m2eclipse
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)

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

Information

Setup Sakai DB (schema) and user

Download and setup Maven 2.0.6+ stable package

Use Subversion to download sakai cafe trunk

Setup sakai.properties file

Use Maven to build Sakai

Start Tomcat and check to make sure Sakai runs

Add Eclipse Web Tools Project (WTP)

Add subclipse to Eclipse

Add Maven Eclipse Plugin to Eclipse