User's Guide

Setting up Helma

Obtaining Helma

Helma can be obtained in various forms from http://www.helma.org. Recommended for beginners are the latest stable Helma-packages (either as .zip or .tgz), which also provide a number of demo applications, to demonstrate the power of Helma. Simply download that package, and unzip it anywhere on your disk.

As an alternative it is possible to download the Helma-source-package, and compile Helma on your own. Experienced users, who want to test the latest developments, might want to download a nightly snapshot of Helma ( http://adele.helma.org/download/helma/nightly/), or even fetch Helma (source) from the CVS repository ( http://helma.org/development/cvs/howto/).

Prerequisites

The only prerequisite to get Helma up and running is a Java Runtime Environment version 1.3 or higher. In order to use Helma's new image manipulation code a version 1.4.1 or higher is required. Sun's JRE 1.4.2 or 1.5 are recommended for production use anyways.

In order to generate JavaDocs or to compile Helma from source, a JDK is required.

General File Structure of Helma

After download and unzipping the Helma-package, you will find the following files and directories:

apps

The default directory for Helma to look for application source code.

lib

In this directory all standard Helma-libraries are stored, and loaded at startup.

lib/ext

A directory to place additional Java-libraries, which should be available in the scripting environment. This is also the put the JDBC-drivers.

licenses

A directory containing licenses of third-party-libraries, that are packaged together with Helma.

scripts

This directory contains useful scripts to run Helma as a service.

static

The default directory for Helma to look for static content.

launcher.jar

A helper Java-library, which is actually started by the start-scripts, and which takes care of the loading of all the other libraries.

apps.properties

This file defines the applications to be started and also contains certain properties for these applications.

server.properties

This file can contain server-wide settings.

hop.bat

A start-script for Windows-systems.

hop.sh

A start-script for Unix-based-systems.

The following directories will be created after starting Helma for the first time:

db

The default directory for Helma to keep its file-based XML-database.

log

The default directory for Helma to store its log-files.

If you downloaded the Helma-source-package, you will find the following additional directories:

build

Contains the Java build-tool ant, and build-settings to compile Helma from sources, which is done by calling '[HelmaHome]/build/build.sh jar' on Linux, resp. ' [HelmaHome]/build/build.bat jar' on Windows. You will probably need to set the variable JAVA_HOME within that script to the location of your installed JDK for this to work

classes

Contains the compiled Java-classes

docs

Contains the generated JavaDocs.

src

Contains the source code for Helma, i.e. the helma.jar.

Starting / Stopping Helma (Development Setup)

Helma can be started by executing hop.bat on Windows, respectively hop.sh on Unix-based systems. If java is not present at the command line, or JAVA_HOME is not set as a system variable, the start-script needs to be edited accordingly, i.e. the JAVA_HOME needs to be set to the java installation directory.

Helma will log its output by default to several files in the log-directory. For a development setup it is useful to have all output being directed to the standard output, i.e. the console. This is achieved by adding the line 'logDir = console' to the file [HelmaHome]/server.properties. Helma needs to be restarted for this change to be effective.

The default setting for Helma is to start a web server port listening on port 8080, which means that you should be able to access Helma after startup at http://localhost:8080/ and/or at http://127.0.0.1:8080/.

If you open the start-script in a text-editor, you will see several startup-options that can be specified for Helma:

HTTP_PORT

If this variable is specified Helma will start a web server listening on that port.

XMLRPC_PORT

If this variable is specified Helma will start a XML-RPC-server listening on that port. Just needs to be set, if you want to make certain functions callable via XML-RPC.

AJP13_PORT

If this variable is specified Helma will start a AJP13-listener on that port, which is just required to connect Helma to another Web Server via mod_jk. Port 8009 is the standard port for AJP13.

RMI_PORT

If this variable is specified Helma will start a RMI-listener on that port.

JAVA_HOME

As mentioned before, this can/should point to the base directory of the Java installation directory to be used. The start script will look for the directory 'bin' and a file named 'java' (resp. 'java.exe') in that directory.

JAVA_OPTIONS

Additional options that need to be passed to the Java Runtime Environment.

HOP_HOME

The home directory of Helma (where the libraries need to reside in a subdirectory named 'lib') can be set to something different than the directory of the start script.

OPTIONS

It is possible to set the location of the file server.properties to something different than the default, by specifying the '-f' option. Call 'java jar launcher.jar --help' for a complete list of Helma startup options.

It is possible to run multiple Helma instances on the same machine. You only need to take care that these instances all use separate ports, otherwise Helma will exit immediately with a "port is already in use" error. The same error will also appear if one of the ports is already in use by another application (e.g. port 8080 is also used by Tomcat by default). You will either have to change the conflicting port in your start-script, or close the other application first.

Stopping Helma is simply done by exiting the Helma process, which usually can be done by pressing Ctrl-C. Restarting Helma is a matter of stopping and starting Helma manually.

Also make sure that the user, under which Helma is run, has the necessary read-privileges for the lib- and apps-directory, and write-privileges for the log- and the db-directory.

Server Setup

As it has been demonstrated in the previous section, it is quite simple to get Helma up and running. To deploy Helma for production use (on a server), a number of additional tasks usually need to be performed.

Helma as Service on Linux

It is advisable to install Helma as a service on Linux, and have Helma being started and stopped automatically when the server is started and stopped.

This is achieved by copying the file [HelmaHome]/scripts/helma.conf to /etc/helma.conf, and [HelmaHome]/scripts/helma to /etc/init.d/helma (or to wherever the Linux-Distribution keeps its service-scripts). Make sure that the latter is actually executable (i.e. 'chmod u+x /etc/init.d/helma'), and that the settings in /etc/helma.conf are correctly configured (see that file for further documentation). Now it is possible to start/stop Helma via the command ' helma start', resp. ' helma stop'. Additional actions are ' helma restart', and ' helma reload'.

By copying the java-binary to something like 'javahop' (and adapt the JAVA_BIN-setting in /etc/helma.conf), it is possible to watch this process separately from other possible Java-processes that are active on that server.

It is also possible to run multiple Helma instances as separate services. You just need to copy the script-files to /etc/helma2.conf and /etc/init.d/helma2 and adapt the HELMA_CONFIG-setting in /etc/init.d/helma2 accordingly.

Depending on your Linux-Distribution you can automatically instruct your system to start and stop Helma when the server is being rebooted. On a Debian-System this is for example done by executing the command 'update-rc.d helma defaults'.

Important: If you decide to start any port (web, xml-rpc,..) below the number 1024, which are considered as 'privileged ports' under Linux, then you have to run Helma as the root user, otherwise these ports won't be accessible.

Helma as Service on Windows

In order to install Helma as a Service on Windows please refer to http://adele.helma.org/download/helma/contrib/hannes/helmaservice/.

Java Startup Options

If you want to use Helma's image processing capabilities on a Linux-Server without an X-Server (which is generally the case), you need to specify '-Djava.awt.headless=true' as a JAVA_OPTION.

Depending on the Java Runtime Environment it is also possible to specify a number of startup options in order to tweak performance. Probably most important is the assignment of the maximum (and minimum) memory size to be used by Helma, which is done by '-Xmx', resp. '-Xms'. Helma's powerful object caching mechanism can become quite memory-hungry, if cache size is set high. If you run Helma on a multi-processor-system you also might want to specify the garbage collector to something different than the default. '-XX:+UseParallelGC' might prove very effective in such a case.

Apache Setup (via mod_jk)

See the online-documentation for now: http://helma.org/docs/howtos/mod_jk/

FIXME

Include section on mod_ssl !

Tomcat Setup

See the online-documentation for now: http://helma.org/docs/howtos/lamtha/

FIXME

modGcj Setup

FIXME ??