/
Development Environment Setup Walkthrough

Development Environment Setup Walkthrough

Jan 16, 2019

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.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 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

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 -Dcom.sun.management.jmxremote -Dsun.lang.ClassLoader.allowArraySyntax=true"

  2. Install/Verify you have MySQL 5.1 or later 

    • MySQL - http://www.mysql.com
      • 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
innodb_file_per_table
character-set-server=utf8
collation-server=utf8_general_ci
lower_case_table_names = 1

      2. OPTIONAL for 5.5: Add this to enable logging

        log_output=FILE
log=/tmp/mysql-query.log
slow-query-log=1
long_query_time=1
slow_query_log_file=/tmp/mysql-slow-query.log
expire_logs_days=5

  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 -u root -p

      • 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'@'127.0.0.1' 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.2.x+ stable package

    1. Download Maven 2.2.X (minimum of 2.2.1) - http://maven.apache.org/download.html
      • 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
      • 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

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

  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 http://dev.mysql.com/downloads/connector/j/5.0.html
      2. If running MySQL 5.1+
        Download version 5.1+ from http://www.mysql.com/downloads/connector/j/
      • 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 https://source.sakaiproject.org/svn/sakai/trunk/ sakai-trunk

      2. 2.9.x Branch: svn checkout https://source.sakaiproject.org/svn/sakai/branches/sakai-2.9.x/

      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

    2. Copy the default config from default.sakai.properties to $CATALINA_HOME/sakai/sakai.properties

    3. Edit the sakai.properties 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) #vendor@org.sakaiproject.db.api.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 # Two 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 and uncomment the 6+ lines in it

        # MySQL settings vendor@org.sakaiproject.db.api.SqlService=mysql driverClassName@javax.sql.BaseDataSource=com.mysql.jdbc.Driver hibernate.dialect=org.hibernate.dialect.MySQL5InnoDBDialect 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

    4. Save the changes to the sakai.properties 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: 
      <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

  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

    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 - 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

  14. Add subclipse to Eclipse

  15. Add Maven Eclipse Plugin to Eclipse

  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