A server framework for stateful, sessionful applications in the web

General Information

This page describes Elko release 1.0, dated 24-August-2009.

Elko is a Java-based server framework for building stateful, sessionful applications in the web. It is especially suited to applications that require realtime interaction among multiple clients, such as realtime text chat or multiplayer games, or that have a strong "push" component wherein the server needs to initiate much of the interaction, such as service monitors or realtime auctions.

The authoritative source and documentation for Elko is maintained at:


Background and theory are discussed in a series of three Habitat Chronicles blog posts:

Part I: The Life, Death, Life, Death, Life, Death, and Resurrection of The Elko Session Server
Part II: Against Statelessness (or, Everything Old Is New Again)
Part III: Scale Differently

Elko is open source software, under the MIT license.

Bug reports, flames, questions and other feedback should be directed to:


What's Here

There are a couple of different pieces you can download:

  • Java source tarball: http://www.fudco.com/software/elko/elko-source-1.0.tar.gz

    To build the source distribution directly, you will also need the jdep utility and GNU Make. Note that most people doing Java development these days use one of the several popular Java IDEs and/or Ant, but at the moment there's no support for these; I'm an old time Unix/emacs guy and never had much use for such newfangled contraptions (especially Ant, yuck). However, the Java source tree is structured in the conventional way and the classes have no external dependencies outside the normal class libraries that are part of the standard JDK, so you should just be able to import the source tree into your favorite IDE and press the build button.

  • Documentation: http://www.fudco.com/software/elko/elko-documentation-1.0.tar.gz

    The documentation is also readable directly on the web at http://www.fudco.com/software/elko/doc

  • A precompiled .jar file: http://www.fudco.com/software/elko/elko.jar

    Note that elko.jar is also included in the source distribution, so you probably won't need this. Unless you really know what you're doing (and presumably you don't since I've just released this code!), the .jar file isn't much use without the rest of the source distribution anyway, as the latter contains various configuration files and utility shell scripts that you'll really want to have to actually use the thing. However, I'm providing elko.jar separately in case somebody has trouble building from source or if they mess theirs up somehow.

  • The whole magilla: http://www.fudco.com/software/elko/elko-full-1.0.tar.gz

    This is simply the source and the documentation bundled together into a single tarball for your downloading convenience.

All the Java code works on any standard, reasonably current JVM, though I can't speak to edge cases such as gcj. The various shell scripts do assume a Unix shell environment, but Cygwin will suffice and they are not deeply essential anyway.

What's Not Here

In the interest of getting this code out to some folks who are interested in it now, I'm releasing this stuff absent a few pieces that would be nice to have for the package to be a complete, one-stop shopping exercise for building the kinds of apps it is designed to support. So prospective users of this could should be forewarned that they'll still need to fill in a few things.

In particular:

  • There's very little here at the moment on the client side. There do exist client apps that make use of this platform, but I don't have access to any of that code at the moment. For now this is left as an exercise for the developer.

  • The web directory in the source distribution contains a simple test client (courtesy of Doug Crockford) that you can load directly into your web browser from a file to exercise the platform, but if you try to serve this client up over the web you'll likely get blocked by the (insert appropriate expletive here) "same origin" rules. To serve regular web pages and access an Elko Context Server from the same domain, you'll need to configure a reverse proxy, such as Apache's mod_proxy, or go through a smart router or web server load balancer that can do URL-based HTTP connection routing.

  • Although there is fairly extensive documentation, most of it is of the "deep internals" variety. In particular, key gaps in the documentation include:

    1. An overview of how to think about and write applications in this framework in general.
    2. A more detailed explication of the application object model, with particular emphasis on how to create and populate contexts that do interesting things.
    3. Technical details on how to program and configure your own application code on the server side.
    4. A discussion of the server scaling model and how to make use of the constellation of different server types to achieve massive scalability.

It is my hope and intention to fill these lacunae over the next few months, but life being what it is I can't make any promises.

Chip Morningstar (chip@fudco.com)