Campus Project Files

##Version 1.3 (28/07/2009)
These instructions are created to add the Welcome Application to Sakai 2.5.5 over Windows, Mac OS X or Linux

I. Installation Demo Sakai

1) Download Demo version of sakai version 2.5.5 (http://source.sakaiproject.org/release/2.5.5/)

2) Unzip on directory "sakai-demo-2.5.5". You don't unzip to a sakai-demo-2.5.5 folder because the zip file already contains a sakai-demo-2.5.5 folder (you could also remove the sakai-demo-2.5.5 directory from the zipfile). You have to overwrite the "sakai-demo-2.5.5" folder.

II. Installation Gateway + OkiBus Server + Components
FILE GatewaySakai_OkiBusServer_Components-Sakai-1.3.zip


3) Unzip GatewaySakai_OkiBusServer_Components-Sakai-1.3.zip and Copy in your directory where unziped "sakai-demo-2.5.5"

4) When asks you Replace you have to Accept All

5)Database configuration
	By default is configured to use HSQLDB (http://hsqldb.org/), it database is only for testing. 
	For production enviroment we recomend to use MySQL or Oracle to install it follow these instructions

	See Chapter 4 on
		http://confluence.sakaiproject.org/display/DOC/Configuration+%282.5%29

6) Change directory to sakai-demo-2.5.5.

7) Start up tomcat:

<windows>

      start-sakai.bat

<mac, linux>

      ./start-sakai.sh

To Remote Debug you have to execute listening on port 8000
<windows>

      start-sakai-debug-mode.bat

<mac, linux>

      ./start-sakai-debug-mode.sh

8) Logs from the sakai-demo-2.5.5. The logs are in the "logs" folder.  Tomcat's catalina.out has the most interesting entries.

9) Accessing Sakai. Once your Sakai is started, open a browser and enter the following URL:

http://localhost:8080/portal

10) Log in in Sakai

One user account is included in the demo, the administrator's account.  Log in using user id "admin" and password 
"admin".

New user accounts can be created from the admin's User tool, or using the "new account" link on the Sakai gateway 
site.

You may want to change the default language for Sakai. To change it and put in English version to follow this manual you have to use Preferences Tool. The Preferences tool allows you to customize features within Sakai. It allows you to change how you receive notifications from your sites, organize your site tabs, and change the current time zone and language.

First of all you have to go "Administration Workspace" and create a page in Site "!admin". 
Click on button "Pages", then "New Page". Fill the field title (for example "Preferences").
Click on button "Tools" -> "New Tool" and select "Preferences Tool (sakai.preferences)" and click "Save" button.

To use the preferences tool you have to refresh the page or click on tab "Administration Workspace", and you will see in left menu the "New Page".

This will change the language in which Sakai system text (buttons, links, etc) is presented. Note that text added by users (announcements, resources, etc) will be in the original language in which it was added. The Discussion and Private Messages tool is also not affected by this setting.

Click the Language action beneath the title bar.

Select your language from the list.

Click Update Preferences to make the change. If you do not see an immediate change, refresh your browser.


11) Create a new "course"

	a) Go to "Administration Workspace" and "Worksite Setup"
	b) "New" -> select "course website" and Academic Term. Push button "Continue"
	c) Then click on the link "Add a course(s) and/or section(s) not listed above..."
	d) Click on the link "Still cannot find your course/section?"
	e) Fill all fields like this 
		Subject: Example
		Course:  Exa
		Section: 01
		Authorizer's username: admin
	f) Class Information, you have to enter basic information about class site, is not necessary.
	g) Select default "tools". Is not needed you can push "Continue".
	h) Make sure Publish site is checked and push "Continue".
	i) Last step is a Confirmation of your new site and push "Request site"

12)Then click on "Administration Workspace"->"Sites" and locate the course who title starts with 
"Example_Exa_01", click on this "Site id" (this "Site Id" will be used on step 41).

13)Go down and click on button "Pages"

14)Click on "New Page" link (under "Sites")

15)We'll create a new page with a Gateway Test. Fill title Page, for example, "Test Campus Tool"

16)Click on button "Tools"

17)Add a new Tool clicking link "New Tool"

18)Select "Eina test Campus (cat.campus.tool.test.TestTool)"

19)Go bottom of page and click "Save"

20)On top blue row (blue as default if you don't change the template) click on tab starting with "Example_Exa_01_"

As an admin user sometimes you will lose this link, then you have to do:

	a)Go "Administration Workspace"
	b)Go "Worksite Setup"
	c)Click over your course

21)On the left menu you have every page. Click on "Test Campus Tool" to start the test. This test require be admin user. You have to pass all Tests. You have to get:

Test Completed


After that you can test a Eina Welcome Campus (cat.campus.tool.test.WelcomeTool). Go "Worksite Setup", select site id starting "Example_Exa_01", create a new page adding a tool Eina Welcome Campus (cat.campus.tool.test.WelcomeTool).

In your tomcat folder <tomcat_folder>/sakai/osid_config with these 2 files
	-cat.campus.tool.test.WelcomeTool_inst.properties
		This file should be empty
	-cat.campus.tool.test.WelcomeTool_app.properties 
		This file has to have this content:
			lang_welcome_java=en_welcome


22)Now we will test with an internal and external application, to do deploy in course starting title "Example_Exa_01" and create 
four new pages: 
First to put the installer tool (the title will be "Installer Tool").
Second to use the new local application (the title will be "Local Application"). 
Third to use the new remote application (the title will be "Remote Application"). 
The last one is to use the remote php application (the title will be "Remote PHP Application"). 

To create each page you have to:

	a) Go to "Administration Workspace" 
	b) Click on "Sites" (on left menu)
	c) Click on "Site id" of the course before created
	d) Click on "Pages" button
	e) Click "New Page" link
	f) Fill the title for each page ("Installer Tool" and "Remotes Applications")
	g) Click on "Save" button.
	

III.Installation welcomeJavaApp on the same server
FILE WelcomeJavaApp-Sakai-1.3.zip

23)Unzip "WelcomeJavaApp-Sakai-1.3.zip" in your directory where unziped "sakai-demo-2.5.5"

24) When asks you Replace you have to Accept All

25)Add "Campus installer Tool" to page "Installer Tool"

	a) Select the page "Installer Tool" from pages of "Example_Exa_01_Academic Course"
	b) Click "New Tool"
	c) Select  "Campus installer tool (campus.installer)"
	d) Click "Save"

"Campus installer Tool" lets to install an applications.

26)Stop sakai-demo-2.5.5:

<windows>

      stop-sakai.bat

<mac, linux>

      ./stop-sakai.sh


27)Start up tomcat client:

<windows>

      start-sakai.bat

<mac, linux>

      ./start-sakai.sh

28)Go to "Example_Exa_01_Academic Course", page "Installer Tool"
Fill all the fields with these values

	//Application Name to Install
	App Name: 	welcomelocal
	//Application Version to Install
	Version: 	1
	//URL to Install the new application
	Install URL: 	http://localhost:8080/welcomeApp/install.jsp
	//URL to Execute in the new application
	Execute URL: 	http://localhost:8080/welcomeApp/index.jsp
	//It's identified the webapps of launcher
	Launcher Relative URL: /CampusLauncherJava/launcher/launcher.jsp

29)Click button "Install"

30)Then you have to wait to see the "Result of appInstaler"

31)If everything is ok you will see

welcomelocal: Install page

Success!

Installation completed

32)Stop sakai-demo-2.5.5:

<windows>

      stop-sakai.bat

<mac, linux>

      ./stop-sakai.sh

33)Start up sakai-demo-2.5.5:

<windows>

      start-sakai.bat

<mac, linux>

      ./start-sakai.sh

34)Add Tool "Campus welcomelocal-1 (welcome-1)" to page "Internal Applications"

	a) Select the page "Internal Applications" from pages of "Example_Exa_01_Academic Course"
	b) Click a "New Tool"
	c) Select  "Campus welcomelocal-1 (welcomelocal-1)"
	d) Click "Save"

35)welcomelocal Application will be installed and click "Continue"

36)Go to "Administration Workspace" 

37)Add user Teacher and Student

	a)Go Administration Workspace
	b)On the left menu click on "Users"
	c)Click "New User"
	d)Fill

	For user Teacher:
		User Id: jeff

		First Name: jeff

		Last Name: jeff

		Email: jeff@jeff.edu

		Create New Password: jeff

		Verify New Password: jeff

		Type: PERSON

	For user Student:
		User Id: tom

		First Name: tom

		Last Name: tom

		Email: tom@tom.edu

		Create New Password: tom

		Verify New Password: tom

		Type: PERSON

	Modify Type of "admin" user to PERSON. Select "admin" user from list and edit.

38)Assing roles on course:

	a)Go Administration Workspace
	b)On the left menu click on "Worksite Setup"
	c)Check on checkbox of "Example_Exa_01_Academic Course"
	d)Click "Edit" 
	e)Click "Add Participants"
	f)On textarea under "Username(s)" write
		jeff
		tom
	g)In "Participant Roles" choose "Assign each participant a role individually"
	h)Select "Instructor" role for "jeff" and "Student" role for "tom", click "Continue".
	i)Dont't send email and click "Continue"
	j)Click "Finish" button

39)Log out Sakai

40)Log in as jeff (Instructor role in "Example_Exa_01_Academic Course")

41)Go on top menu "Example_Exa_01_Academic Course" and click on "Internal Application" to execute the application

Then you'll see:
Welcome teacher!

If you can't see on top menu "Example_Exa_01_Academic Course" go to "My Workspace", click on "Worksite Setup" and then over "Example_Exa_01_Academic Course"

IV.Remote WelcomJavaApp + OkiBusClient + Components
FILE WelcomeJavaApp_OkiBusClient_Components_VersusSakai-Sakai-1.3.zip

42)To install a remote application you need to use other tomcat. You have to download a tomcat 5.5 from http://tomcat.apache.org/download-55.cgi. This tomcat will be "tomcat-client". The tomcat-client runs on port 8081 (the port of 
sakai-demo-2.5.5 is 8080).

43)You have to overwrite all files unzipped from "WelcomeJavaApp_OkiBusClient_Components_VersusSakai.zip"-

44)Start up tomcat client (scripts set enviroment variables to connect via Webservices with Sakai):

<windows>

      start-tomcat-client-sakai.bat

<mac, linux>

      ./start-tomcat-client-sakai.sh

To Remote Debug you have to execute listening on port 8001
<windows>

      start-tomcat-client-debug-mode-sakai.bat

<mac, linux>

      ./start-tomcat-client-debug-mode-sakai.sh

45)Logs from the tomcat-client. The logs are in the logs folder.  Tomcat's catalina.out has the most interesting entries.

46)Accessing tomcat-client. Once your tomcat-client is started, open a browser and enter the following URL:

http://localhost:8081/

(you can see "It works..." if is ok)

47)If tou are not logged like "admin". Only "admin" roles can install applications.
	a)Log out Sakai
	b)Log in as admin 


48)Go to "Example_Exa_01_Academic Course", page "Installer Tool"
Fill all the fields with these values

	//Application Name to Install
	App Name: 	welcomeremote
	//Application Version to Install
	Version: 	1
	//URL to Install the new application
	Install URL: 	http://localhost:8081/welcomeApp/install.jsp
	//URL to Execute in the new application
	Execute URL: 	http://localhost:8081/welcomeApp/index.jsp
	//It's identified the webapps of launcher
	Launcher Relative URL: /CampusLauncherJava/launcher/launcher.jsp

49)Click button "Install"

50)Then you have to wait to see the "Result of appInstaler"

51)If everything is ok you will see

welcomeremote: Install page

Success!

Installation completed

52)Stop sakai-demo-2.5.5:

<windows>

      stop-sakai.bat

<mac, linux>

      ./stop-sakai.sh

53)Start up sakai-demo-2.5.5:

<windows>

      start-sakai.bat

<mac, linux>

      ./start-sakai.sh

54)Log in as "admin" and add Tool "Campus welcomeremote-1 (welcomeremote-1)" to page "Remotes Applications"

	a) Select the page "Remote Applications" from pages of "Example_Exa_01_Academic Course"
	b) Click a "New Tool"
	c) Select  "Campus welcomeremote-1 (welcome-1)"
	d) Click "Save"

55)welcomeremote Application will be installed and click "Continue"

56)Log out Sakai

57)Log in as jeff (Instructor role in "Example_Exa_01_Academic Course")

58)Go on top menu "Example_Exa_01_Academic Course" and click on "Remote Applications" to execute the application

Then you'll see:
Welcome teacher!

If you can't see on top menu "Example_Exa_01_Academic Course" go to "My Workspace", click on "Worksite Setup" and then over "Example_Exa_01_Academic Course"

V.Remote WelcomPHPApp + OkiBusClient + Components
FILE WelcomePHPApp_OkiBusClient_Components_VersusSakai-Sakai-1.3.zip

59)To install a remote application you need to use Apache. To Windows and Mac we recomend to use Xampp and to Linux you can install from your distribution. In order to coexist with others Aplications on Apache we will define a virtual host on port 83 (Information of Virtual Host at the end of this document). The file "vhost_WelcomePHPApp_OkiBusClient_Components.conf" will be found in zip file,  and is a template, you have to change <folder> for the real path.
To include this file you have to edit configuration file of Apache2 (httpd.conf or apache2.conf) and add this line:

Include <folder_to_unzipped_vhost>/vhost_WelcomePHPApp_OkiBusClient_Components.conf.

60)Restart Apache

61)Go to http://localhost:83

(you can see "It works..." if is ok)

Test Client Configuration:

It's very important to test if configuration of Client is correct. The page will show:
-Classes of include_path are correct.
	-ComponentsPHP classes.
	-OkiBusPHPClient classes.
	-PHP_OSID_2.0 classes.
	-PHPUtils classes.
-Classes loaded via configuration file are correct.
	-Classes of OkiBusPHPClient Implementation of ComponentsPHP.
	-Classes of SOAP from OkiBusPHPClient.
-Context parameters.
	-Test if contexts params are the same in OkiBusPHPServer.

Acces:

http://localhost:83/testClientClasses/testClasses.php

If anything is wrong will show you in red color. Fix these errors before continue.
If everything goes fine it will display a line in red: "Error 0 class not found"

62)If tou are not logged like "admin". Only "admin" roles can install applications.
	a)Log out Sakai
	b)Log in as admin 

63)Go to "Example_Exa_01_Academic Course", page "Installer Tool"
Fill all the fields with these values

	//Application Name to Install
	App Name: 	welcomeremotephp
	//Application Version to Install
	Version: 	1
	//URL to Install the new application
	Install URL: 	http://localhost:83/WelcomePHPApp/install.php
	//URL to Execute in the new application
	Execute URL: 	http://localhost:83/WelcomePHPApp/index.php
	//It's identified the webapps of launcher
	Launcher Relative URL: /LauncherPHP/launcher/launcher.php

64)Click button "Install"

65)Then you have to wait to see the "Result of appInstaler"

66)If everything is ok you will see

welcomeremotephp: Install page

Success!

Installation completed

67)Stop sakai-demo-2.5.5:

<windows>

      stop-sakai.bat

<mac, linux>

      ./stop-sakai.sh

68)Start up sakai-demo-2.5.5:

<windows>

      start-sakai.bat

<mac, linux>

      ./start-sakai.sh

69)Log in as "admin" and add Tool "Campus welcomeremotephp-1 (welcomeremotephp-1)" to page "Remotes Applications"

	a) Select the page "Remote PHP Application" from pages of "Example_Exa_01_Academic Course"
	b) Click a "New Tool"
	c) Select  "Campus welcomeremotephp-1 (welcome-1)"
	d) Click "Save"

83)welcomeremotephp Application will be installed and click "Continue"

84)Go to "Administration Workspace" 

85)On left menu click on "Realms"

86)Search your site on list (last page) "site/" and "Site id" from step 11 and click.

87)Click on Role "Instructor"

88)And check viewingTeacherMessage and click "Save"

89)Click on Role "Student"

90)And check viewingStudentMessage and click "Save"

91)Log out Sakai

92)Log in as jeff (Instructor role in "Example_Exa_01_Academic Course")

93)Go on top menu "Example_Exa_01_Academic Course" and click on "Remote PHP Application" to execute the application

Then you'll see:
Welcome teacher!

If you can't see on top menu "Example_Exa_01_Academic Course" go to "My Workspace", click on "Worksite Setup" and then over "Example_Exa_01_Academic Course"

------------------------------------------------------------------------------------------------

Stopping the demo
-----------------------------------------------------

1) stop tomcat:  

<windows>

      stop-sakai.bat

<mac, linux>

      ./stop-sakai.sh


Data from the demo
-----------------------------------------------------

The data is stored in a HypersonicSql database located:

sakai-demo-2.5.5/sakai/db/sakai.db.*

Objects created and modified in runs of the Sakai demo will persist through server restarts.

HSQL is not appropriate for running Sakai in any sort of production or even medium to large scale demonstration and evaluation environments.  For these, we recommend MySql or Oracle.


Not in the demo
-----------------------------------------------------

1) email detection in Sakai (i.e. mail sent to the Sakai server) is not enabled.

2) email from Sakai (i.e. mail sent from Sakai) is not configured.

This requires providing Sakai with an SMTP server to use. If you want to do this, you can edit the sakai.properties found in sakai-demo-2.5.5/sakai and add:

	smtp@org.sakaiproject.email.api.EmailService=<SMTP>

where <SMTP> is replaced with the name or ip address of an SMPT server that will accept mail from your Sakai app server.


Problems getting started
-----------------------------------------------------

1) Sakai's Tomcat will run on port 8080, and also make use of ports 8005 and 8009.
   If another process is running on any of these ports, Sakai will not start up.

2) Sakai's Tomcat will find itself relative to the startup directory.  Always start it from the sakai-demo-2.5.5 folder.
   If you have an environment variable CATALINA_HOME set to another Tomcat, this will interfere with Sakai's startup.



Stopping the tomcat-client
-----------------------------------------------------

1) stop tomcat:  

<windows>

      stop-tomcat-client.bat

<mac, linux>

      ./stop-tomcat-client.sh

-----------------------------------------
Virtual Host
The term Virtual Host refers to the practice of running more than one web site (such as www.company1.com and www.company2.com) on a single machine. Virtual hosts can be "IP-based", meaning that you have a different IP address for every web site, or "name-based", meaning that you have multiple names running on each IP address. The fact that they are running on the same physical server is not apparent to the end user.

More information in http://httpd.apache.org/docs/2.0/vhosts/