Sakai Logo

4. Post-Installation Configuration

This section of the Installation Guide describes basic configuration details. For a more exhaustive treatment of Sakai configuration, refer to the Full Configuration area of the "Documentation" space on Confluence.

4.1 Create sakai folder for properties files


Sakai runs with a default set of properties for its various components.  To override them you'll want to specify them in a sakai.properties file which should be located in $CATALINA_HOME/sakai by default.  This directory is not created by maven, so you'll have to do so manually.  Once this directory is created, there are several *.properties files you can place inside which can override default properties. 

Choosing a different location for the properties files
You may find it advantageous to store sakai's configuration files outside of the Tomcat file structure. In a development environment, for example, you may find yourself frequently blowing Tomcat away, and you may wish to avoid recreating the sakai folder and its contained properties files each time.

To accomplish this, you need only modify the java startup command (or the JAVA_OPTS environment variable) to set the system property sakai.home, e.g.:

-Dsakai.home=/path/to/desired/sakai/home/

You'll need to make sure that this location is readable and writable to Tomcat.

4.2 The sakai.properties file


The main configuration file for Sakai is called sakai.properties, and you can either create it from scratch or copy in a known working copy. A sample sakai.properties file which self-documents many of the standard properties in its comments can be found in:
sakai-src/docs/sakai.properties

sakai.properties can define two different types of settings.  The first type sets those values that are made available to the running code from the Sakai configuration service.  A line of sakai.properties sets this sort of value if it has the form: 

name=value

The second type of sakai.properties setting overrides the configuration defaults of individual sakai components.  These defaults are set in the components.xml file of any particular component, and so this configuration can in principle be achieved by also editing a large number of components.xml files (one for each component), but it's a best practice to keep all configuration changes in sakai.properties.  Override settings have the form:

name@component-name=value

New value settings can be freely added to the sakai.properties file, since any component property can in principle be overridden here, and so any sample sakai.properties will show only a small fraction of all the possible settings.

4.3 Personalizing Sakai

Sakai has a number of places where your institution names, service names, and the host name of your service are used. These can be configured in sakai.properties:
# identify your application server with a short name,
unique among the servers in your cluster.

# choose a server id even if you are running a single app server
serverId=localhost # the URL to the server, including transport, DNS name, and port, if any serverUrl=http://localhost:8080 # the DNS name of the server serverName=localhost

# the URL to send folks to after they logout loggedOutUrl=http://localhost:8080/portal # some fill-ins for the css/vm ui (Worksite Setup, Digest Service, Email notification, Worksite Setup, Contact Support, Portal) ui.institution = Your Institution
ui.service = SakaiOrWhatever #copyright text to appear in the bottom area of each web page. bottom.copyrighttext=(c) 2003, 2004, 2005 sakaiproject.org. All rights reserved. # links placed on the bottom nav - set the .count to the number of items, then add each item bottomnav.count = 2 bottomnav.1 = <a href="https://localhost/portal/site/!gateway">Gateway</a> bottomnav.2 = <a href="http://sakaiproject.org/cms" target="_blank">The Sakai Project</a>
You can add more or other links to the bottom navigation bar by setting the proper bottomnav.count value and adding bottomnav.N values (1 through the number of links).
User Presence Enabled by Default
User presence is on automatically in this release, although it has not been in recent releases. If you do not wish to use it at your institution, you must explicitly turn it off in sakai.properties:
# to enable presence display in the portal
display.users.present=true

4.4 Email Configuration

Sakai needs to be set up for two email functions: receiving email sent to Sakai sites, and sending out email notifications.

For sending mail Sakai needs the address (name or IP) of an SMTP server that will accept mail from Sakai. This needs to be set in your sakai.properties file:

smtp@org.sakaiproject.service.framework.email.EmailService=some.smtp.org

To enable Sakai to receive mail there are a few settings needed in the sakai.properties file:

# dns addresses used for incoming email
	
smtp.dns.1 = 255.255.255.1
smtp.dns.2 = 255.255.255.2
# SMTP port on which our SMTP server runs. Default is 25. #Recommend running on 8025, and using a standard mailer on 25 to forward mail to Sakai.
smtp.port = 25

# flag to enable or disable our SMTP server for incoming email (true | false)
smtp.enabled = true

To disable the SMTP server for incoming email, use this in sakai.properties:

smtp.enabled = false

Sakai's SMTP server is 'James,' and to run with the above configuration which runs James on the standard SMTP port 25 you must be running with admin privileges. Most production folks don't want to let Tomcat run with that, and would rather run a standard mailer like postfix on port 25 and configure it to forward requests to Sakai. You might also already have a mailer service running on port 25 (Linux usually has it running by default), and so you'd want to change the James port simply to avoid a conflict. You'll typically want to run James on another, non-restricted port, then.  For example:

smtp.port = 8025

4.5 JVM Tuning

The Java virtual machine's configuration is very important to tune for best performance in any production environment, and some of Sakai's tools may not operate with the memory alloted by the default JVM.
Disclaimer
JVM tuning is, as a general rule, something of a black art, and we recommend that you take the time to experiment with different memory and garbage collection settings and see what works best in your environment. We can make some minimal recommendations that should serve as a foundation for further experimentation and testing, but the following details are however offered only as samples or suggestions, and we recommend that you consult a systems administrator or local Java guru before making any such changes to a production system. See Sun's Tuning Garbage Collection documentation for more details.

The standard way to control the JVM options when Tomcat starts up is to have an environment variable JAVA_OPTS defined with JVM startup options.  One such set of options might be:

JAVA_OPTS=-server -Xms512m -Xmx512m -XX:PermSize=16m -XX:MaxPermSize=128m
-verbose:gc -XX:+PrintGCDetails -XX:+PrintGCTimeStamps

This is a fairly good starting point: it selects server mode, sets a larger heap size for smoother performance, sizes the permanent generation to accommodate more longer-persisting objects, and turns on garbage collection details. We have found the best results when the min and max memory settings (Xms and Xmx, respectively) are set to be the same values. 512 megs is not too much memory for Sakai; 1 gig is even better.

Tomcat will see this environment variable and use it. Instead of putting this in an environment variable, you might modify the $CATALINA_HOME/bin/catalina.bat or $CATALINA_HOME/bin/catalina.sh file to automatically set these values during startup.

JVM Tuning in Windows XP
Windows users may set Java options in a "Tomcat Properties" dialog. But you may find that the permanent generation settings mentioned above will not work appropriately if set in the Java Options: field of the dialog window. That's because these settings have their own fields in the properties GUI, under the headings Initial Memory Pool and Maximum memory pool, respectively.

4.6 Test Sakai

At this stage your installation of Sakai has not yet been configured to use your preferred database (it will use its own HSQLDB by default), but you should now be able to bring it up as a working web application by simply starting Tomcat, and it can be helpful at this point to know if any problems exist before you try to connect it to another database. Tomcat will take a minute or so to start up, depending on the speed of your machine, and it's a good idea to watch the Tomcat log as it comes up to catch any errors (see Troubleshooting).

From $CATALINA_HOME you can start up Tomcat with the command:

OS Sample Output
Windows:
bin\catalina.bat start
Mac/*nix:
bin/catalina.sh start

Once Tomcat has loaded the Sakai application (again, this can take a minute or so) point your browser to

http://localhost:8080/portal

If the gateway page does not come up, check the Tomcat logs (see Troubleshooting ).  If the gateway page does come up, log in with the default admin account:
 username = admin, password = admin.  
If you can log in without errors you should be able to stop Tomcat and proceed with Database configuration, if needed.

OS Sample Output
Windows:
bin\catalina.bat stop
Mac/*nix:
bin/catalina.sh stop