Set up multiple Sakai versions

Setting up multiple Sakai versions

We've all had to maintain an older version of a product in production and attempt to upgrade to the latest, greatest.
Here are some tips and tricks for setting up and developing with multiple versions of Sakai on your desktop.

This document assumes that you already have a working version of Sakai on your desktop. The following steps corresponds to those on Development Environment Setup Walkthrough. Most of the tools needed should already be installed.

If you are installing a single instance of sakai on your desktop, please follow the steps in the Development Environment Setup Walkthrough.

Notations

<Sakai Version> is the version of Sakai

Verify you have Java 1.5
1. To check: Run java -version on the command line
Verify you have MySQL 4.1
1. To check: Run mysql --help on the command line
Setup Sakai DB (schema) and user
1. Create a new database instance relating to the sakai version. ex. sakai25
2. The user and password can be the same(user=sakai and password=ironchef)
3. Run the following from a command line prompt:
```
      mysql -uroot -pmysqlpwd1
```
4. Then run these commands from the mysql prompt (one command per line):
```
      create database sakai25 default character set utf8;
      grant all privileges on sakai.* to 'sakai25'@'localhost' identified by 'ironchef';
      flush privileges;
      quit
```
Download and setup Maven 2.0.6+ stable package
1. if your current version of sakai is using Maven 1.0.x, then follow the steps in the Development Environment Setup Walkthrough.
Verify you have Subversion
1. To check: Run svn --version on the command line
setup tomcat 5.5.17+ (stable only)
1. It is recommended that after the initial setup of tomcat, that a clean copy of tomcat be created.
2. Hopefully there is a clean copy of tomcat on your desktop.
3. If so copy this to /opt and rename it to identify the sakai version ex. /opt/tomcat-5.5_25
  otherwise, download install the same version of tomcat and set up base on the instructions in Development Environment Setup Walkthrough.
4. Remove all sakai subdirectories under components, webapps, shared, common
5. This allows a developer to return to initial setup if the tomcat get trashed....
Setup MySQL Connector/J stable
1. This should already be set up
Use Subversion to download sakai cafe trunk
1. follow the instructions in the Development Environment Setup Walkthrough.
Setup sakai.properties file
1. Copy the sakai directory from the current tomcat copy the the new tomcat created in step 6.
2. Make any modification to this sakai.properties file for this version.
3. change the data base instance to point to the one created in step 3.
  Example
  
  url@javax.sql.BaseDataSource=jdbc:mysql://127.0.0.1:3306/sakai25?useUnicode=true&characterEncoding=UTF-8
Create maven settings.xml file
1. Create a new xml file for this Sakai Version in your user home directory in the .m2 directory called settings25.xml
  - Note: This is probably c:\documents and settings\<username> in Windows
  - Download a sample settings.xml file (setup for windows users)
2. Add the following lines pointing to tomcat created in step 6:
  Example
  
  <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-5.5_25</appserver.home>
  <maven.tomcat.home>/opt/tomcat-5.5_25</maven.tomcat.home>
  <sakai.appserver.home>/opt/tomcat-5.5_25</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 <Sakai Version> for windows users
  - Note: Do not include trailing / or \ slashes in the directory paths
Use Maven to build Sakai
1. follow the instructions in the Development Environment Setup Walkthrough.
Create batch files to start, stop, and debug tomcat
1. For Windows users, create a directory and add this to your path. ex. C:\bat
  - Note: Remove any references to the existing $CATALINA_HOME from the path, it may cause confusion in the scripts
2. From your $CATALINA_HOME/bin directory, copy startup.(bat-sh) to /bat
3. Rename it to startup <Sakai Version> .(bat-sh) ex. startup25.bat
4. Edit startup<Sakai Version>
5. Add the following lines:
```
   set JAVA_OPTS=-server -XX:+UseParallelGC -Xmx768m -XX:MaxPermSize=160m -Djava.awt.headless=true
   set cd=c:\opt\tomcat-5.5-<Sakai Version>
   set CATALINA_HOME=%cd%
   
```
6. Then from your $CATALINA_HOME/bin directory, copy shutdown.(bat-sh) to /bat
7. Rename it to shutdown <Sakai Version> .(bat-sh) ex. shutdown25.bat
8. Add the following lines:
```
   set cd=c:\opt\tomcat-5.5-<Sakai Version>
   set CATALINA_HOME=%cd%
   
```
9. Repeat these steps for the current tomcat instance
Start Tomcat and check to make sure Sakai runs
1. Start Tomcat
2. Open a command line shell
3. Change directory to /bat
4. Type startup <Sakai Version> .(bat-sh) ex. startup25.bat
5. Allow 1 minute+ for tomcat to start up
6. Open http://localhost:8080/ to verify tomcat is running
7. Open http://localhost:8080/portal to verify sakai is running
8. Login to sakai as username:admin, password:admin
9. Shutdown Tomcat using by typing shutdown <Sakai Version> .(bat-sh) ex. shutdown25.bat
Install Eclipse 3.2+ stable
1. This should already be set up.
2. Otherwise, follow the instructions in the Development Environment Setup Walkthrough. for more info
  - 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 separately, you can skip the WebTools step if you do this, here are instructions to install the Eclipse WebTools
Add Eclipse Web Tools Project (WTP)
1. This should already be set up
Add subclipse to Eclipse
1. This should already be set up
Add SpringIDE to Eclipse
1. This should already be set up
Import Sakai source code into Eclipse
1. Startup eclipse if it is not running
2. Create a new workspace for the new Sakai Version
3. Click on File -> Switch Workspace
4. Enter "WS-Sakai*<Sakai Version>*" ex. WS-Sakai25 in place of the default "workspace" directory
5. Click OK (eclipse will restart)
- The following steps should be done in the WS-Sakai workspace
1. Add Maven Repository libraries to classpath
2. Select Window -> Preferences -> Java -> Build Path -> Classpath Variables
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
4. Switch to the Java perspective (Window -> Open Perspective -> Java)
  - Make sure you are in the package explorer
5. Turn off Automatic builds
  - Select Project and uncheck Build automatically
6. Select File -> Import -> Existing Projects into Workspace
7. Enter the full path to the sakai source directory for the root directory
  - This should be /opt/cafe-2.2.x if you followed the steps in this document
8. Click Deselect All to unselect all projects
9. Select the following projects (you only need most of the APIs, a few utils, and all of the db projects)
  alias-api
  announcement-api
  archive-api
  authz-api
  component-api
  content-api
  courier-api
  cm-api
  db-api
  db-impl
  db-util
  entity-api
  email-api
  event-api
  jsf
  message-api
  master
  site-api
  site-manage-api
  tool-api
  user-api
  user-util
  util-api
  util-util
  velocity
  - NOTE: You can just import all the projects also, this tends to work fine for me
10. Click Finish to import the selected projects
  - This will take awhile, probably 5+ minutes
11. Create a working set for Sakai (optional)
- You do not have to create a working set, these are here in case you want to
1. Switch to the Java perspective
2. In the Package Explorer pane click the drop-down arrow menu and choose Select Working Set
3. Click the New button from the Select Working Set Dialog window
4. Choose Java for the Working Set Type and click Next
5. Enter Sakai as the name for your Working Set
6. Select the imported Sakai projects and click Finish
7. Build Sakai in Eclipse
  - Initially you will get build failures on almost every Sakai project, this is because they are building in the default order and their dependencies are in a different order, this has been partially addressed in Sakai 2.2
8. Clean all Sakai projects
9. Select Project -> Clean
10. Select Clean all projects
11. Check Start a build immediately
12. Click OK
13. Build All (Project -> Build All)
  - Do this if using working sets:
    Build the Sakai working set (Select Project -> Build Working Set -> Sakai)
  - Repeat this step until no errors remain (should be no more than 3-4 times)
  - There will be hundreds of warnings, do not worry about these
14. Turn back on Automatic builds
  - Select Project and check Build automatically

Setting up multiple Sakai versions

Verify you have Java 1.5

Verify you have MySQL 4.1

Setup Sakai DB (schema) and user

Download and setup Maven 2.0.6+ stable package

Verify you have Subversion

setup tomcat 5.5.17+ (stable only)

Setup MySQL Connector/J stable

Use Subversion to download sakai cafe trunk

Setup sakai.properties file

Create maven settings.xml file

Use Maven to build Sakai

Create batch files to start, stop, and debug tomcat

Start Tomcat and check to make sure Sakai runs

Install Eclipse 3.2+ stable

Add Eclipse Web Tools Project (WTP)

Add subclipse to Eclipse

Add SpringIDE to Eclipse

Import Sakai source code into Eclipse