If you're working in Eclipse, checkout the source using subclipse; otherwise, use the subversion command:
Build the source, using the following instructions for your environment.
- cd genkey
- build the server using: ./buildAll.bat
- 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.
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.
- use the specified folder as the home folder (defaults to the current working directory)
- use the specified folder as the config folder (defaults to the "config" sub-folder of the waterken.home folder)
- use the specified folder as the code folder (defaults to the waterken.home folder)
- 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
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
- known MIME types
mime.jsonsetting provides an array of known MIME types consulted when serving static web pages.
- 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
portmember in the http.json file. See also https.json and dns.json.
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.
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.
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.
- hostname of the proxy server
- port number of the proxy server
- 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
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.
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
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.
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:
By convention, the
config/file/site/ folder is
reserved for resources that are shared site-wide, such as stylesheets, images
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.
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
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.
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.
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/.
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.