4. Post-Installation Configuration
Prev |  | Next

## 4. Post-Installation Configuration

### 4.1. Create folder for properties file

Sakai runs with a default set of configuration 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.

### Choosing a different location for sakai.properties

You may find it preferable to store Sakai's configuration files outside of the Tomcat file hierarchy. In a development environment, for example, you may find yourself frequently blowing Tomcat away, and you'll likely want to avoid recreating the sakai folder and its contained file(s) 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:

    -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 the source under sakai-src/reference/docs/sakai.properties, while the properties file that the OOTB software uses as its default may be found in `sakai-src/kernel/component/src/config/org/sakaiproject/config/sakai.properties.`

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

### Learning more about sakai.properties

Settings in `sakai.properties` govern everything from setting your institution name to configuring your database. The essential settings for installation are covered here, but to find the most detailed documentation on the full variety of possible `sakai.properties` settings, look in sakai_properties.doc in subversion or `reference/docs/architecture/sakai_properties.doc` of the source archive.

### 4.3. HTTP proxy

In environments where local network policy or firewalls require use of an upstream http proxy / cache, Sakai needs to be configured to use this. Otherwise, components or services which use http requests, such as BasicNewsService for RSS feeds in the News tool, cannot retrieve data from the target URLs. RSS feeds then do not display in the news tool, and it is not possible to add new news channels.

This can be fixed by adding the following JAVA_OPTS arguments to the Sakai local startup script (e.g. `/etc/rc.d/sakai`), or to a Sakai startup script such as `startup.sh` or `catalina.sh`:

    export JAVA_OPTS="-DproxySet=true -DproxyHost=cache.some.domain -DproxyPort=8080"

You'll need to set additional JAVA_OPTS for memory tuning (see below), and the appropriate ones can simply be appended.

### 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, and this needs to be set in your `sakai.properties` file:

    smtp@org.sakaiproject.email.api.EmailService=some.smtp.org

To enable Sakai to receive mail you'll need to set the following:

    # 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 line 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 admins won't want to let Tomcat run with those permissions, 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. For example:

    smtp.port = 8025

### 4.5. JVM Tuning

The default Java virtual machine is not adequate to run an application of Sakai's size, and several JVM parameters must be increased to a certain threshold for Sakai to run, while some may be further adjusted for optimal performance on your machines.

### 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 the Programmer's Cafe on our Confluence wiki for more discussion of the 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. Since any given Sakai instance may be deployed for a variety of purposes - ranging from developers doing private testing to large-scale deployments - it's hard to recommend a single set of such options as the preferred ones for every case. We can, however, start with a bare minimum which will at least avoid "Out of Memory" errors, and be suitable for developer installs of the software:

    JAVA_OPTS="-server -Xms512m -Xmx768m -XX:PermSize=128m -XX:MaxPermSize=196m -XX:NewSize=192m -XX:MaxNewSize=384m"

This is an adequate - if minimal - starting point: it selects server mode, sets an adequate heap size, and sizes the permanent generation to accommodate more longer-persisting objects. These settings will allow things to be functional for testing and development, but will hardly be adequate for serving large numbers of concurrent users. A more suitable production environment on a 32-bit machine with multiple processors might use a set of options like:

    JAVA_OPTS="-server -Xms1500m -Xmx1500m -XX:NewSize=400m -XX:MaxNewSize=400m -XX:PermSize=128m
    -XX:MaxPermSize=196m -verbose:gc -XX:+PrintGCTimeStamps -XX:+PrintGCDetails -XX:+UseConcMarkSweepGC -XX:+UseParNewGC"

This is better: a larger heap size is set for smoother performance (we have found the best results when the min and max memory settings - Xms and Xmx, respectively - are set to be the same values), and garbage collection messages are turned on. Another important consideration is the ratio of NewSize to the size of the heap. We want as large a NewSize as we can fit in the total heap, while keeping the total heap significantly bigger than NewSize in order for Java to properly garbage collect. The last two arguments above can produce a performance improvement if you have two or more processors on your machine, however your performance will be better if you don't include them for single-processor machines.

As you can see, there's a lot to think about here, and in practice each implementing institution uses their own particular JAVA_OPTS that they've settled on for their deployment and hardware, and they often use more option arguments than we've shown here. This discussion is meant only as a head start, and there is no replacement for doing your own testing.

Once you set JAVA_OPTS Tomcat will see this environment variable upon startup and use it. Instead of putting this in an environment variable you might create your own startup script to do so.

### JVM Tuning of Tomcat as a Windows Service

Windows users that have installed Tomcat as a service may set most Java options through the Tomcat service manager GUI, but not all of them are as straightforward as inclusion in a single environment variable.

To achieve the equivalent of the "-server" option, for example, you'll need to change the Java Virtual Machine path from `[..]\bin\client\jvm.dll` to `[..]\bin\server\jvm.dll`. Then be sure to put the remaining JAVA_OPTS on separate lines in the Java Options field of the GUI. e.g.:

    -Xmx512m
    -Xms512m
    -XX:PermSize=128m
    -XX:MaxPermSize=128m

Finally, clear out the Initial Memory Pool and Maximum Memory Pool values, as those might conflict with the options you're putting in the Java Options field. Then click Apply, restart the service, and double-check the service manager to verify that the values have changed.

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

Windows: | bin/startup.bat
Mac/*nix: | bin/startup.sh

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 the Troubleshooting section) for any errors and stack traces. If the gateway page does come up, log in with the default admin account (the username and password are both 'admin'). If you can log in without errors you should be able to stop Tomcat and proceed with Database configuration, if needed.

Windows: | bin/shutdown.bat
Mac/*nix: | bin/shutdown.sh

Prev |  | Next
3. Build and Deploy | Home | 5. Database Configuration