Deploying the Waterken^TM server

Checkout and build the source

If you're working in Eclipse, checkout the source using subclipse; otherwise, use the subversion command:

svn co https://waterken.svn.sourceforge.net/svnroot/waterken/server/trunk/waterken

Build the source, using the following instructions for your environment.

Windows

cd genkey
build the server using: ./buildAll.bat

Unix

cd genkey
build the server using: ./buildAll.sh

Following the checkout instructions creates an installation which is ready to be used. This default setup can be configured in various ways to match your desired deployment. This section explains the available configuration options. You can skip to the section on using the server if you're content to use the provided setup.

Java system properties

To bootstrap its configuration, the server needs to know the locations of the following folders:

config folder: holds configuration files, such as the SSL key pair
code folder: holds project specific Java class files
This folder is expected to contain an entry for each project. For example, in the default configuration, the code folder is the root folder of the Waterken server installation and it contains a sub-folder named example/bin/ for a project named "example".

By default, the server will assume the current working directory is the code folder. The config folder is then expected to be an immediate sub-folder named config/. This folder layout is the one created when you unpack the waterken-server distribution.

This default folder layout can be customized using Java system properties. A Java system property can be defined using a "-D" option to the java command used to start a JVM.

waterken.home: use the specified folder as the home folder (defaults to the current working directory)
waterken.config: use the specified folder as the config folder (defaults to the "config" sub-folder of the waterken.home folder)
waterken.code: use the specified folder as the code folder (defaults to the waterken.home folder)
waterken.bin: use the specified string as the extension to be added to a project name to get the name of the folder, or JAR file, containing the project's class files (defaults to "/bin/")

For example, the default values for these system properties are equivalent to the following explicit properties:

java -Dwaterken.home=. -Dwaterken.config=config -Dwaterken.code=.
     -Dwaterken.bin=/bin/ -jar serve.jar

config files

All remaining configuration is expressed by files in the config folder. The various *.json files in this folder are used to initialize the HTTP request routing code. For example, settings of interest include:

static web pages: The next.next.root setting of server.json sets the path to a folder containing files to be served, such as CSS files and Javascript. By default, this setting refers to the config/file/ folder created by the waterken-server distribution.
known MIME types: The mime.json setting provides an array of known MIME types consulted when serving static web pages.
vat: The vatRootFolder.json setting specifies the root folder for all persistent vats.
server ports: Service specific configuration options, such as the server port number, are specified in a corresponding configuration file. For example, the HTTP server port number is specified by the port member in the http.json file. See also https.json and dns.json.

Using the server

The server supports SSL, use of an HTTP proxy and can host two kinds of resources: files and Java objects. This section explains how to run the server and add resources.

Start the server

Once compilation is complete, the server can be run using the serve.jar command. For example,

java -jar serve.jar

If you are running on Unix, or another operating system that restricts use of well-known ports, the above command may fail under the default Waterken server configuration which uses the standard port number for the HTTPS service. You can configure this port number in the config/https.json file.

The Waterken server is designed as crash-only software, so there is no special user interface for stopping the server. Just kill the process, such as by hitting Ctrl-C from the command line.

Configure an HTTP proxy

If you are behind an HTTP proxy, you must provide its location to any command that requires network access. Each such command checks a set of Java system properties for proxy configuration information.

proxyHost: hostname of the proxy server
proxyPort: port number of the proxy server
proxySet: value is "true" when an HTTP proxy is configured

For example, to start the server using an HTTP proxy:

java -DproxyHost=proxy.example.com -DproxyPort=8088 -DproxySet=true -jar serve.jar

Configure an SSL key pair

The server's SSL key pair must be stored in the config/keys.jks file. This file is in the default format used by the JDK's keytool program. You can use any existing SLL key pair you have by loading it into the config/keys.jks file using the keytool program.

The server must be restarted to begin using a newly configured key pair.

Generate a hostname and corresponding SSL key pair

If you don't already have an SSL key pair, you can generate one using the genkey.jar command. This command will generate a new self-signed certificate for a sub-domain of yurl.net. The command will also register this newly generated hostname with the DNS nameserver for yurl.net. When the server is running, it will update this DNS record with your computer's current IP address. Run the genkey.jar command from the root directory of your installation:

java -jar genkey.jar

Since this command requires network access to contact the yurl.net nameserver, you will need to include your HTTP proxy location if you are behind an HTTP proxy. After the command has completed successfully, there will be a keys.jks file, as well as some new configuration files, in your config folder.

By default, the genkey.jar command generates a 1024 bit RSA key, which is thought to be comparable in strength to an 80 bit symmetric key cipher. You can specify a higher bit strength with an argument to the genkey.jar command. Specify 112 to get a 2048 bit RSA key, or 128 to get a 3072 bit RSA key.

Add served files

The content of any file under the config/file/ folder can be fetched using a URL whose path names the file. For example, your site's homepage is at config/file/index.html and can be fetched using the URL: <http://localhost:8080/index.html>.

By convention, the config/file/site/ folder is reserved for resources that are shared site-wide, such as stylesheets, images and Javascript code. This folder also provides the content served for HTTP error codes. For example, the config/file/site/404.html file provides the default content for any HTTP 404 error pages returned by the server.

Add a new vat

Persistent Java objects hosted by the Waterken server are grouped into collections, each of which is called a "vat". The persistent state of each vat is held in a sub-folder of the config/vat/ folder. You can create a new vat from the command line using spawn.jar:

java -jar spawn.jar example org.waterken.bang.DrumFactory bang

The above command enables execution of the Eventual#spawn(…) method from the command line. The last argument is the vat name and the second to last is the fully qualified name of the maker class used to construct the first application object in the new vat. The web-key for the created object is returned on the stdout of the spawn.jar command. The first argument to the spawn.jar command is the name of the project that defines the maker class.

Add a new project

Each vat is associated with a project, which determines the custom Java classes used in the vat, as well as the web page served for any web-key exported from the vat.

Configure project classes

When creating a new application, put your Java class files in a sub-folder of the code folder, using your project name for the sub-folder name. For example, the waterken-server distribution includes a sample application with project name "example" and corresponding class file folder example/bin/. To create a new application named "myProject", create a new folder at the same level as the existing example/ folder and put your class files in a bin/ sub-folder, so your classes are at myProject/bin/.

Configure project web page

Every web-key exported from a given vat references the same web page. This web page is stored in a sub-folder of the config/file/site/ folder, again named by the project. For example, the web page for the "example" project is at config/file/site/example/index.html. You can customize this web page for your own application by creating a corresponding entry for your project. For example, to setup the web page for the "myProject" application, copy the index.html file to a new folder at config/file/site/myProject/. You can also use other formats for your application's web page. The server only expects the application's web page to be in a file whose name starts with "index.", so a flash web page would be named index.swf.