As mentioned, RIFE is built on the Java platform which means that you need to install a JDK to develop and run RIFE applications. Java can be downloaded from http://java.sun.com/.

You also need a web server with servlet support and for this tutorial we have chosen Jetty, which is easy to setup and use. You can download it from the Jetty web page at http://jetty.mortbay.com/.

RIFE itself can be downloaded from the RIFE site at http://rifers.org/downloads. There are a few different packages to choose from.

When setting up a new web application, the base package is a good starting point, since it contains the RIFE framework together with the necessary files for getting started with a web application. The directory structure in the zip file is only a recommendation, and you can change it to your liking. However, keeping the web.xml file in the recommended location makes it possible to package this directory as a war file easily and deploy it on any servlet engine. The jar file, on the other hand, contains just RIFE, which is convenient when upgrading RIFE in an existing application.

We'll set up a web application directory tree in our home directory, starting with Jetty

mkdir ~/tutorial
cd ~/tutorial

jar xf {download directory}/jetty-{version}.zip

Now we need to setup our test application in the webapps subdirectory:

cd jetty-{version}
cd webapps

After that we unpack the RIFE distribution and set up the base directories for the web application:

jar xf {download directory}/rife-base-{version}.zip

mv rife-base-{version} my-application
cd my-application

cd WEB-INF

mkdir classes
cd classes

mkdir rep
mkdir sites
mkdir elements
mkdir templates

So far so good! It's probably a good idea to copy this whole directory hierarchy so that you can start over from a fresh setup after doing some experimenting, or just to have a boiler-plate application to start new projects from. For example:

cd ../../..
cp -r my-application ../../blueprint

Now we can start filling in the bits and pieces that are needed to create a very simple RIFE application. But first, we'd like to take the opportunity to explain a bit more about web applications and RIFE.

If you look at the contents of the RIFE zip file, you see that it contains the Java classes for RIFE along with a file called web.xml. Applications that are packaged this way can be used directly with any application server, by just dropping the file into the right directory.

The only thing missing from the zip file an actual implementation of a web application, which you'll soon be able to write yourself.

But first it's time to try out a finished RIFE application, and we'll use an example from the examples package that can be downloaded from the RIFE site. The package contains a number of examples that are ready to run and test. To try out the first example, a simple "Hello World" application, take the following steps:

First, go back into the webapps directory and unpack the examples there.

cd ~/tutorial

jar xf {download directory}/rife-examples-{version}.zip
cd rife-examples-{version}

Install RIFE into the web application's lib directory. We'll download the jar file from the RIFE site and put it in the right directory:

mkdir 01_helloworld/WEB-INF/lib
cp ROOT/WEB-INF/lib/rife-{version}.jar 01_helloworld/WEB-INF/lib/
mv 01_helloworld ../jetty-{version}/webapps/

Now we can start the application and test it!

cd ~/tutorial/jetty-{version}

java -jar start.jar

You will see an exception when you start Jetty because the my-application web application is missing required files. We will add those later. The important part now is to look at the hello world example.

To try out the example, point your web browser to the location: http://localhost:8080/01_helloworld/home, which should show a "Hello world." message.

The following section will walk you through this example and explain the different parts.