HowTo: How to run multiple Wrapper instances on UNIX

Compatibility :	1.0.0
Editions :
Platforms :

The Wrapper has been designed to make it easy to run multiple instances on the same system without any special configuration. This relies on the individual applications being run each being in their own directory and/or having their own name. To avoid confusion, it best that they each have their own name even when running in different directories.

A typical running application that has been integrated with the Wrapper will have the following directory structure:

$APP_HOME/
  bin/
    wrapper
    myapp.sh
    myapp.pid
  lib/
    libwrapper.so
    wrapper.jar
    myapp-*.jar
  conf/
    wrapper.conf
  logs/
    wrapper.log

In this example, the myapp.sh is a copy of the shell script that ships in the Wrapper distribution as $WRAPPER_HOME/src/bin/App.sh.in (on older Wrapper versions, this file was named 'sh.script.in'). This script contains a block of variables, which should be set up for the application as follows:

# Application
APP_NAME="myapp"
APP_LONG_NAME="My Application"

# Wrapper
WRAPPER_CMD="./wrapper"
WRAPPER_CONF="../conf/wrapper.conf"

# Location of the pid file.
PIDDIR="."

# When installing on On Mac OSX platforms, the following domain will be used to
#  prefix the plist file name.
PLIST_DOMAIN=com.myco.myapp

When the script runs, any relative paths will be relative to the location of the shell script. (However, when the Wrapper itself is launched, it will set its working directory to that of the Wrapper binary.)

When the Wrapper is launched, it will write out a PID file named "$PIDDIR/$APP_NAME.pid" (in this case, myapp.pid). This file is used later by the shell script to tell whether or not the Wrapper process is still running. The $PIDDIR is by default in the same directory as the shell script.

Depending on how the shell script is configured, the Wrapper may also make use of one or more of the following files, using the same naming pattern:

• "$PIDDIR/$APP_NAME.anchor",
• "$PIDDIR/$APP_NAME.command",
• "$PIDDIR/$APP_NAME.status",
• "$PIDDIR/$APP_NAME.java.status",
• "$PIDDIR/$APP_NAME.anchor"

Some UNIX platforms also define a lock directory, "/var/lock/subsys". When that directory exists and is writable, the Wrapper will also write out a lock file: "/var/lock/subsys/$APP_NAME". Such platforms use this lock file to tell which services are currently running. As a rule, it is, thus, a good idea to make sure that you don't run more than one application with the same name, even if they are located in different directories. If you do, then the last one started will overwrite the lock file, and the first one to shut down will delete it. This will not affect the Wrapper's shell script, but could cause problems for other management software.

If you want to run two applications using the same physical Wrapper binary, they will both be running in the same working directory. This means that you will need to make sure that the two applications have different shell scripts, with different application names ($APP_NAME), and also use different wrapper.conf files. The contents of the configuration files also need to be checked to make sure that the two applications have their own log files, using the wrapper.logfile property.

It is also possible to make use of the wrapper.working.dir property in each configuration file to control where each application runs. If you take this route, please be sure to fully read the property documentation to save yourself some time.