Endymion Saké
Generalized Installation Guide

This page covers the basic steps necessary for installing the Saké framework using servlet containers that are not conformant with the 2.2 Servlet API specifications. If you are using a servlet container that supports current standards, then you can use the much simpler installation procedure outlined in our basic installation guide.

In order to install Saké under an older web server, you must first select and install a servlet runner. For Windows servers, we recommend the JRun servlet runner, from Allaire. For Unix platforms, including OSX, we recommend Jakarta Tomcat version 3.3.1. If you are able to use Tomcat then you should be reading the basic installation guide rather than this one.

Step 1: Add Saké jar files to your classpath
In order to configure older servlet containers to run Saké, you need to add the necessary Saké jar files to the Java classpath that your servlet container will use. Note that your system may actually have several different classpaths set, one for each different virtual machine that you have installed. The virtual machine that your servlet runner uses does not necessarily pay attention to the environment variable "CLASSPATH" for its classpath as you might expect. The most reliable way to specify the classpath that will be used when your servlet container starts servlets is to specify it using the administration or configuration mechanism provided by your servlet runner itself. That way your servlet runner will properly feed the correct classpath to whatever virtual machine it is configured to use.

Once you have familiarized yourself with how to configure the classpath that your particular servlet container will use, add an entry to that classpath for the jar file called "sake.jar" in the main "/sake/" directory of your Saké installation:

For example, if you have installed Saké under "c:\sake" (the default in Windows installations) then you will need to add the following to the end of your servlet runner's existing classpath:

Step 2: Tell Saké where it is located
When Saké runs, it needs to know where its own tree is located so that it can read its configuration files, fetch template files, store data, read and store user configuration information and other file system tasks. The location of the installation can be communicated to Saké in several different ways. From the most highly recommended to the least recommended:

Method 1: (highly recommended)
Saké can guess its own location if it is installed in a very simple location. If you are using a Windows machine and you have Saké installed in the default "c:\sake" or in "c:\classes\sake", you should not need to do anything more. Skip to the section "Testing your installation". If you are installing Saké on a Unix machine and your Saké tree is located either at "/bin/sake", "/usr/bin/sake", "/usr/local/bin/sake", or "/classes/sake", then your Saké installation should be able to locate itself by guessing and you can also skip ahead.

Method 2:
You can specify the location of your Saké installation via the Java system property "sake.localtreelocation". Set this property as an argument to your Java virtual machine by using the argument "-Dsake.localtreelocation". For example, in the case where Saké is installed under "c:\sake", pass the following parameter to your Java virtual machine at runtime:

-Dsake.localtreelocation="c:\sake"

Method 3: (least recommended)
If neither of the above methods works for some reason, a last-ditch possibility is to store a file in the root directory or the "/etc" directory of the disk that is the default disk for your Java virtual machine called "sake.ptr". This file should contain only one line, specifying the location of your Saké tree. For example, if your Saké tree is installed under the directory "f:\freakylocation", then you should have a file located at "c:\sake.ptr" that contains the following:

LocalTreeLocation = f:\freakylocation\sake

Step 3: Create a web server alias for Saké's template files
Strictly technically speaking, Saké should run at this point. (You can skip ahead to Step 4 if you are curious or impatient.) One critical component will be missing, however: images. In order for Saké to include images in its output, you need to provide a way for your web users to access the "/sake/templates/" directory via a web browser. By default, Saké assumes that the URL "/templates/" will refer to the templates directory in your Saké installation. If you are using a servlet runner that is embedded in a web server, the simplest way to make this happen is to create an 'alias' for your web server to map the templates directory correctly. If you are using Apache, for example, you can create an alias by adding the following line to the file "srm.conf" in Apache's "conf" directory.

This will alias the URL prefix "/templates/" to the location specified. When you type the URL "http://myserver/templates/" into your web browser, you should see a listing of the contents of the "/sake/templates" directory of your installation, specifically you should see a directory called "default".

If you are running a web server that will be dedicated to running Saké for evaluation purposes, the simplest way to set the template alias so that Saké is able to produce images is to set the main "/sake" directory of your Saké installation as the HTML root for your web server. This setting is sometimes referred to as your "document root". This is the mechanism used by the embedded server for quickly getting an evaluation installation up and running.

For instance, under Microsoft IIS you might create a new virtual server with the "Directory:" property set to "c:\sake" for a quick start. If you use the method of quickly evaluating Saké, please don't forget to create an actual alias to the template directory before your installation goes live and is exposed to the public. Exposing the entire tree to the world in this manner via HTTP is an enormous security hole that opens up all of your users' data to outside voyeurs.

Step 4: Testing your installation
Once your servlet container has been restarted, you should be able to access Saké applications. To test this, try to access Saké Mail with the URL "/servlet/com.endymion.sake.servlet.mail.MailServlet". Remember that if you are using JRun by itself without a web server, you will need to specify the port (JRun uses port 8000 by default). For example, to run Saké Mail using JRun alone, use the URL:

If you have JRun installed under your existing web server, such as Apache or Micrsoft IIS, then use the address and port of your web server as you normally would, for instance: