PrepServer Installation Instructions

From RHESSI Wiki

Requirements

• Windows, Linux, Unix, or Mac OSX
• Sun (Oracle) Java 1.5+
• Tomcat 6
• IDL 7.0+
• Preferably Apache 2.2

Preparations

1. Create an unprivileged user and group, e.g. prepserver with group prepserver. Make prepserver available as $PREP_USER
2. Create a home directory for user prepserver
3. Set prepserver home directory to $PREP_SERVER (e.g. /home/prepserver, /usr/local/prepserver, C:\Programs\PrepServer, etc.)
4. Download prepserver.jar, prepserver.war, prepserver.libs.zip, prepserver.properties, re-startup.csh, and get_idl_path.pro to a temporary directory
5. Make sure that the Tomcat installation is available at $CATALINA_HOME

Installation (Mac/Unix/Linux)

PrepServer

1. Log in as prepserver
2. Create the following folders in $PREP_SERVER: lib, bin, logs, tmp
3. Copy prepserver.jar and prepserver.properties to $PREP_SERVER
4. Copy extract Java libraries from prepserver.libs.zip to $PREP_SERVER/lib
5. Copy re-startup.csh and get_idl_path.pro to $PREP_SERVER/bin
6. Check the #Configuration section

Tomcat

1. Log in as prepserver or as the appropriate Tomcat user
2. Copy prepserver.war to $CATALINA_HOME/webapps
   1. If necessary, deploy application prepserver.war manually (on some systems auto-deploy is disabled). This can be done by manually unzipping prepserver.war into $CATALINA_HOME/webapps
3. Check the #Configuration section

Standard Configuration

PrepServer

1. Edit $PREP_SERVER/prepserver.properties
   1. Set publishing.dir to the publicly shared folder in Tomcat (most likely something like $CATALINA_HOME/webapps/prepserver/public. Make sure that prepserver has read/write access to that folder).
   2. Set publishing.url to the web url under which the public folder from the step before is available (e.g. http://my.server.com:8080/prepserver/public).
2. Edit $PREP_SERVER/bin/re-startup.csh and make sure all Global Variables are set correctly.
3. On certain systems the IDL Pre-processing Server may experience an error because of the absence of an active X11 window. Make sure to check the #Troubleshooting section.
4. Test the installation by running $PREP_SERVER/bin/re-startup.csh as prepserver and checking the logs in $PREP_SERVER/logs. Also see PrepServer Maintenance and Diagnostic.
5. To start the PrepServer after a system reboot, add line to /_etc/rc.local (without the underscore, on Linux/Unix) or create a Launch Control startup item (Mac).
   1. rc.local
      1. Log in as root
      2. Add the line

         su $PREP_USER -c $PREP_SERVER/bin/re-startup.csh

   2. Launch Control
      1. Log in as root
      2. Download the file gov.nasa.prepserver.plist and copy it to /System/Library/LaunchDaemons
      3. Edit /System/Library/LaunchDaemons to fit your system. Please notice that this file comes with automatic restart of the PrepServer.
6. To reboot the PrepServer every day after an SSW update, create a CRON job (Linux/Unix) or a Launch Control startup idem (Mac).
   1. CRON job
      1. Log in as root
      2. Edit the crontab by typing

         crontab -e

         and adding

         6 * * * * su $PREP_USER -c $PREP_SERVER/bin/re-startup.csh # To restart the PrepServer at 6 am

   2. Mac (if using Launch Control):
      1. See previous instructions on Launch Control

Tomcat

There is no additional configuration necessary to run the PrepServer in standard mode. For Tomcat specific settings, please consult the Tomcat Documentation.

Optional Configuration

Apache - Tomcat - PrepServer

In the standard setup, Tomcat is directly visible from the Internet and thus the point of contact for PrepClients. In a more advanced scenario, Apache can be places in from of Tomcat, shielding it from direct access. All requests for pre-processing will be accepted by Apache and forwarded internally to Tomcat. This extended setup is accomplished by using jk_mod, a connector between Apache and Tomcat. See the connectors documentation.

prepserver.properties

The external user-defined configuration is done in the prepserver.properties file, which is located in the PrepServer base directory ($PREP_SERVER). Most configuration parameters have standard values and are set internally and automatically by the PrepServer.

PrepServer startup parameters

The following parameters can be specified in a startup script (e.g. re-startup.csh) to change certain behavior of the PrepServer.

java -cp $CLASSPATH -Dserver.id=1 ...PreprocessorIdlService

java -cp $CLASSPATH -Djava.io.tmpdir=$PREP_SERVER/tmp ...PreprocessorIdlService

export CATALINA_OPTS="-Xms1024m -Xmx1024m"

Troubleshooting

IDL Pre-processing Server breaks on startup

It seems as if some graphics libraries loaded by IDL required an active X11 window, even if no widgets are being created. Is the PrepServer started from an X11-less console it can happen that the absence of an active X11 window causes the libraries to break. The workaround is to create a Virtual Frame Buffer window and to set the DISPLAY variable in the re-startup.csh script to that DISPLAY. To create and test the solution, execute the below command as root. To make this a permanent solution, add the command to /_etc/rc.local (remove the underline).

Xvfb :7 -screen 0 800x600x8 2>/dev/null &

Note: Java should disallow opening IDL widgets that could block the PrepServer (waiting for user input). In addition to that, re-startup.csh is loaded in NOX (No X11) mode.

IDL message with % Attempt to call undefined procedure/function: 'XYZ'

This error message can be caused by the following:

• An IDL Pre-processing Service was not properly initialized (missing SSW paths, etc.). Check the logs to see if errors had occurred during startup.
• The IDL setup script on Windows was not properly configured (idl.startup, see #prepserver.properties).
• The IDL Pre-processing Service was not restarted after new routines were added to SSW. Restart the server and try again.