PrepServer Installation Instructions

From RHESSI Wiki

(Difference between revisions)
Jump to: navigation, search
(Initial Release)
m (Finished startup parameters section)
 
(8 intermediate revisions not shown)
Line 25: Line 25:
# Log in as ''prepserver'' or as the appropriate Tomcat user
# Log in as ''prepserver'' or as the appropriate Tomcat user
# Copy ''prepserver.war'' to ''$CATALINA_HOME/webapps''
# Copy ''prepserver.war'' to ''$CATALINA_HOME/webapps''
-
## If necessary, deploy application ''prepserver.war'' (some systems auto-deploy is disabled)
+
## 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''
# Check the [[#Configuration]] section
# Check the [[#Configuration]] section
-
== Configuration ==
+
== Standard Configuration ==
=== PrepServer ===
=== PrepServer ===
# Edit ''$PREP_SERVER/prepserver.properties''
# Edit ''$PREP_SERVER/prepserver.properties''
-
## 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.
+
## 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).
## 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'').
## 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'').
# Edit ''$PREP_SERVER/bin/re-startup.csh'' and make sure all ''Global Variables'' are set correctly.
# Edit ''$PREP_SERVER/bin/re-startup.csh'' and make sure all ''Global Variables'' are set correctly.
-
# On certain systems the IDL Pre-processing Server may experience an error because of the absence of an active X11 window. See the [[#Troubleshooting]] section.
+
# 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.
# 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]].
# 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]].
-
# To start the PrepServer after a system reboot, add line to ''/_etc/rc.local'' (Linux/Unix) or create a ''Launch Control'' startup item (Mac).
+
# 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).
## rc.local
## rc.local
### Log in as root
### Log in as root
-
### Add the line ''su $PREP_USER -c $PREP_SERVER/bin/re-startup.csh''
+
### Add the line <source lang="bash">su $PREP_USER -c $PREP_SERVER/bin/re-startup.csh</source>
## Launch Control
## Launch Control
### Log in as root
### Log in as root
Line 47: Line 47:
## CRON job
## CRON job
### Log in as root
### Log in as root
-
### Edit the crontab by typing ''crontab -e'' and add ''6 * * * * su $PREP_USER -c $PREP_SERVER/bin/re-startup.csh''
+
### Edit the crontab by typing <source lang="bash">crontab -e</source> and adding <source lang="bash">6 * * * * su $PREP_USER -c $PREP_SERVER/bin/re-startup.csh # To restart the PrepServer at 6 am</source>
## Mac (if using Launch Control):
## Mac (if using Launch Control):
### See previous instructions on ''Launch Control''
### 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 [http://tomcat.apache.org/tomcat-6.0-doc/index.html 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 [http://tomcat.apache.org/connectors-doc/ 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.
 +
 +
{| border="1" cellspacing="0" cellpadding="5" align="left" width="100%"
 +
! style="background:#efefef;" | Property
 +
! style="background:#efefef;" | Mandatory
 +
! style="background:#efefef;" | Purpose
 +
! style="background:#efefef;" | Standard Value
 +
! style="background:#efefef;" | Example
 +
|-
 +
| publishing.dir || X || Defines where the web server public directory is located. All raw and pre-processed data are stored in this directory and made available to internal prep-servers as well as external users. || N/A || publishing.dir=file:///Applications/tomcat6/webapps/prepserver/public
 +
|-
 +
| publishing.url || X || This parameter defines under what base URL the raw or pre-processed data will be published. || http://127.0.0.1:8080/prepserver/public || publishing.url=http://my.service.com:8080/prepserver/public
 +
|-
 +
| idl.startup || Windows only || In order for the pre-processing servers to enable themselves for SSW IDL, they need to execute this initialization script. || file:///C:/ssw/gen/idl/ssw_system/idl_startup_windows.pro || idl.startup=file:///C:/ssw/gen/idl/ssw_system/idl_startup_windows.pro
 +
|-
 +
| mgmt.rmi || || This parameter specifies on what server the management service runs. || rmi://127.0.0.1:1099/PreprocessorManagementService || mgmt.rmi=http://my.service.com:1099/PreprocessorManagementService
 +
|-
 +
| pojo.rmi || || This parameter specifies on what server the pojo service runs (generally same server as mgmt.rmi). || rmi://127.0.0.1:1099/PreprocessorPojoService || pojo.rmi=http://my.service.com:1099/PreprocessorPojoService
 +
|-
 +
| media.rmi || || This parameter specifies on what server the media service runs (generally same server as mgmt.rmi). || rmi://127.0.0.1:1099/PreprocessorMediaService|| media.rmi=http://my.service.com:1099/PreprocessorMediaService
 +
|}
 +
 +
=== 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.
 +
{| border="1" cellspacing="0" cellpadding="5" align="left" width="100%"
 +
! style="background:#efefef;" | Service
 +
! style="background:#efefef;" | Property
 +
! style="background:#efefef;" | Mandatory
 +
! style="background:#efefef;" | Purpose
 +
! style="background:#efefef;" | Standard Value
 +
! style="background:#efefef;" | Example
 +
|-
 +
| PreprocessorIdlService || server.id || || This property assigns an id to the IDL Pre-processing Server. This id is used in logging and identification. || A randomly generated UUID || <source lang="bash">java -cp $CLASSPATH -Dserver.id=1 ...PreprocessorIdlService</source>
 +
|-
 +
| PreprocessorIdlService  || java.io.tmpdir || || This property overwrites the standard Java temporary directory (the working directory for the PrepServer) || The standard Java temporary directory || <source lang="bash">java -cp $CLASSPATH -Djava.io.tmpdir=$PREP_SERVER/tmp ...PreprocessorIdlService</source>
 +
|-
 +
| Web Front-end || log.dir || || This variable is set inside Tomcat and passed on to the Web Front-end. It's purpose is to change the default logging directory for the WebServiceAccessLogger.log || The ''logs'' directory for Tomcat || Run this command before starting Tomcat: <source lang="bash">export CATALINA_OPTS="-Xms1024m -Xmx1024m"</source>
 +
|}
 +
== Troubleshooting ==
== Troubleshooting ==
-
Xvfb :7 -screen 0 800x600x8 2>/dev/null &
+
=== 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).
 +
<source lang="bash">Xvfb :7 -screen 0 800x600x8 2>/dev/null &</source>
 +
'''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.

Latest revision as of 15:42, 8 September 2010

Contents

Requirements

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.

Property Mandatory Purpose Standard Value Example
publishing.dir X Defines where the web server public directory is located. All raw and pre-processed data are stored in this directory and made available to internal prep-servers as well as external users. N/A publishing.dir=file:///Applications/tomcat6/webapps/prepserver/public
publishing.url X This parameter defines under what base URL the raw or pre-processed data will be published. http://127.0.0.1:8080/prepserver/public publishing.url=http://my.service.com:8080/prepserver/public
idl.startup Windows only In order for the pre-processing servers to enable themselves for SSW IDL, they need to execute this initialization script. file:///C:/ssw/gen/idl/ssw_system/idl_startup_windows.pro idl.startup=file:///C:/ssw/gen/idl/ssw_system/idl_startup_windows.pro
mgmt.rmi This parameter specifies on what server the management service runs. rmi://127.0.0.1:1099/PreprocessorManagementService mgmt.rmi=http://my.service.com:1099/PreprocessorManagementService
pojo.rmi This parameter specifies on what server the pojo service runs (generally same server as mgmt.rmi). rmi://127.0.0.1:1099/PreprocessorPojoService pojo.rmi=http://my.service.com:1099/PreprocessorPojoService
media.rmi This parameter specifies on what server the media service runs (generally same server as mgmt.rmi). rmi://127.0.0.1:1099/PreprocessorMediaService media.rmi=http://my.service.com:1099/PreprocessorMediaService

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.

Service Property Mandatory Purpose Standard Value Example
PreprocessorIdlService server.id This property assigns an id to the IDL Pre-processing Server. This id is used in logging and identification. A randomly generated UUID
java -cp $CLASSPATH -Dserver.id=1 ...PreprocessorIdlService
PreprocessorIdlService java.io.tmpdir This property overwrites the standard Java temporary directory (the working directory for the PrepServer) The standard Java temporary directory
java -cp $CLASSPATH -Djava.io.tmpdir=$PREP_SERVER/tmp ...PreprocessorIdlService
Web Front-end log.dir This variable is set inside Tomcat and passed on to the Web Front-end. It's purpose is to change the default logging directory for the WebServiceAccessLogger.log The logs directory for Tomcat Run this command before starting Tomcat:
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:

Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox