Configuring the Waterken^TM server

Setup

When the waterken-server distribution is unpacked, it 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 provided 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/

holds configuration files, such as the SSL key pair

code/

holds project specific Java class files

This folder is expected to contain an entry for each project. For example, the Waterken server includes a project named "example", so the code/ folder includes a sub-folder named example/bin/.

By default, the server will assume the current working directory should be used as the code/ folder. The other folders are then expected to be in immediate sub-folders. 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/")

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:

www/ folder

The next.next.next.root setting of server.json provides the path to a folder containing files to be served, such as CSS files and Javascript. By default, this setting refers to the www/ folder created by the waterken-server distribution.

known MIME types

mime.json provides an array of known MIME types to be consulted when serving files from the www/ folder.

vat/

vatRootFolder.json specifies the root folder of 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 shows how to configure the server and add new resources.

Build the server

The Waterken server is primarily intended for use by developers, so the waterken-server distribution is a source-only distribution which must be compiled before the server can be executed. The source distribution includes Eclipse project files, and also includes a shell script for compilation from the command line. The build.sh script should work on either Unix or Cygwin.

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 www/ folder can be fetched using a URL whose path names the file. For example, your site's homepage is at www/index.html and can be fetched using the URL: <http://localhost:8080/index.html>.

By convention, the www/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 www/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 vat/ folder. You can create a new vat from the command line using spawn.jar:

java -jar spawn.jar example org.waterken.bang.Main test

The above command enables execution of the Publisher#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 www/site/ folder, again named by the project. For example, the web page for the "example" project is at www/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 www/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.