Glenn R. Golden, May 14, 2005
This document covers how Sakai is configured. There are two different types of
configuration in Sakai, configuration of components, and general configuration, used by tools and other parts of the system. Configuration is initially set by files in the Sakai code base. Additional and override configuration values can be specified in configuration files location on the Sakai application server in the Sakai home location.
Component Configuration
Sakai's components are configured using the Spring bean definition property elements in the components.xml files. All configuration values for a component are specified in this way, and have a matching setter method to accept the values in the java class.
Sakai ships with default configuration values for all properties.
You may of course modify these before you deploy your Sakai instance by editing the components.xml files, but this becomes hard to maintain as the Sakai code base changes.
Instead, Sakai provides ways to override the configuration values. Files located in the Sakai home directory on the application server are read by Sakai to do this.
Sakai Home
To establish a Sakai home directory on your application server, you must modify the java
startup command by providing a
-Dsakai.home=/...
value. Specify the complete path to the folder in which Sakai configuration files and other files can be found. This should be read and writable by the Sakai code.
If this is not done, the default value of /usr/local/sakai/ will be used.
sakai.properties
The file called sakai.properties located in the Sakai home folder is used to
provide the overrides to the property settings of the components. Any component
property may be specified in this file. If specified, the value in this file will override the
value found in the components.xml file.
This is a standard java properties file. Each non-comment line is interpreted as:
key=value
To override a component's property, form a key with the property name, followed by the "@" character, followed by the component's bean id, fully dotted. (Read this as
"property 'at' bean"). Then specify the value to use.
For example, the SMTP server used for outgoing email in Sakai can be set by including this line in the sakai.properties file:
smtp@org.sakaiproject.service.framework.email.EmailService=234.434.23.111
This works to override the value from the email service's entry in the
components.xml file:
<bean id="org.sakaiproject.service.framework.email.EmailService" class="org.sakaiproject.component.framework.email.BasicEmailService" init-method="init" destroy-method="destroy" singleton="true"> <property name="smtp"><null/></property> <property name="logger"> <ref bean="org....Logger"/></property> </bean>
Additional properties can be set in this way, but these must have corresponding setter methods in the class.
Note, the format of the keys in this file is different from the Spring format to
accommodate our dotted bean ids.
Other Configuration
Some parts of Sakai that are not components need configuration, such as the Portal and Tools. These make use of the ServerConfigurationService to find
configuration values. The ServerConfigurationService is configured, just like
other components, in the components.xml file, but with a Properties property.
Here's an example:
<bean id="org.sakaiproject.service.framework. config.ServerConfigurationService" class="org.sakaiproject.component.framework.config. BasicConfigurationService" init-method="init" destroy-method="destroy" singleton="true"> <property name="properties"> <props> <prop key="serverId">localhost</prop> <prop key="serverUrl">http://localhost:8080</prop> <prop key="serverName">localhost</prop> <prop key="gatewaySiteId">!gateway</prop> ...
We need a way to override and add new configuration values to this Properties to make them available to Sakai's non-component parts.
To do this, we can enter simple keys in the sakai.properties file. These are keys
that are just the property name that the code is asking the ServerConfigurationService for, not the '@' format used to override a
component property.
For example, to set the server id, enter this in the sakai.properties:
serverId=mongoose Because these keys do not have the '@' character, they are not confused with the component property overrides, and can be included in the same file.
New properties can be added in this way. These will be available from the
ServerConfigurationService.
Multiple Configuration Files
It is convenient to have more than one configuration file, especially in a clustered deployment over may application servers. One properties file can hold the values that are common to the installation. This file would be the same on each app. server. The other file could hold only those values specific to the local app. server, and be different on each server.
A second file called local.properties can be placed into the Sakai home folder to
hold those values that are different on each application server, leaving the
sakai.properties to hold the values in common.
Values in the local.properties will override those in the sakai.properties.
Pull Configuration
The sakai.properties (and local.properties) support an additional form of
configuration for component properties. Instead of specifying a default value in the components.xml file, and then overriding that value in the sakai.properties
file, you can specify a placeholder in the components.xml property definition, like
this:
<bean ...>
<property
name="checkEvery"><value>${session.check}</value></property>
</bean>
Then you can define session.check in your sakai.properties file:
session.check=30
This value will be used anytime the placeholder ${session.check} is found in the
bean definitions.
None of the standard Sakai components are defined with a placeholder, but you can use it for additional components.
Change In Practice
Sakai components used to look to the ServerConfigurationService in their
init() methods to override selected configuration parameters. We no longer do this.
Instead, all parameters of all components are subject to override using the
sakai.properties file.
The components.xml bean definitions for components in older versions of Sakai
were incomplete. They are no longer so. Instead every possible value is specified, some with the <null/> value. This makes it clearer what properties are available for overriding.