The server-side analysis capability is especially useful for archive centers, but also can be attractive to individual users who want to integrate their own data analysis programs into JS9. You configure a JS9 server-side helper by adding additional switches to the configure command described in Installing JS9.
JS9 supports two techniques for server-side analysis: you can use your own web server as the JS9 back-end helper using CGI calls, or you can run a separate Node.js-based server to process JS9 back-end requests. The Node.js server-side helper is faster and more flexible than the CGI helper (e.g., it supports messaging between the command line and the browser). However, it obviously requires installation of Node.js, and uses its own socket port to communicate with the outside world. You should decide which server-side helper to use before running configure. Please contact us if you want to discuss the issues.
When configuring server-side analysis, you add server-side analysis tasks to JS9 (or change the default analysis tasks) by adding or modifying json files in the analysis-plugins directory (and optionally, by adding wrapper files to the analysis-wrappers directory.) See Server-based Tasks for a description of how to configure server-side analysis tasks for your site.
[Esoteric note: one of the plug-in files in the analysis-plugins directory is the fits2png.json plugin. This file specifies the command line for the fits2png conversion program. If you wish to change that command line, it should be done before building the system, since the CGI processing script js9Helper.cgi is generated using this information.]
JS9 is built using the standard GNU ./configure; make; make install technique. When configuring server-side analysis, you will add switches to the configure command line. The most important of these switches are:
--prefix=[path] location to install the non-web programs and scripts --with-helper=[type] type of server-side helper: nodejs, get or post (for CGI)to specify the program install directory and the type of server-side helper you are using. Other important switches are:
--with-cgidir=[path] cgi install directory e.g. /var/www/public_html/cgi-bin --with-cgiurl=[url] cgi url relative to the web root, e.g. ./cgi-bin/js9 --with-cgixpath=[dirs] directories to add to cgi path --with-png=[path] directory containing lib/png e.g. /usr/local --with-cfitsio=[path] cfitsio directory for build e.g. /usr/local
Non-web files, programs, and scripts (e.g., js9helper and fits2png) will be installed in accordance with the --prefix=[dir] switch. The default is /usr/local.
If you want to utilize the Node.js-based helper, you do not have to add any special nodejs switches. If you want to utilize a CGI-based back-end, you must specify the --with-cgidir and --with-cgiurl switches on the configure command line. Optionally, you also can specify the --with-cgixpath switch if you want to add directories to the CGI path:
The build of the JS9 server-side tpos program (which converts FITS files to the JS9 representation file) requires the libpng library. If libpng is not already installed on your system, it is available at:
http://www.libpng.org/pub/png/libpng.htmlOf course, Linux users can install libpng in the "usual way", e.g. for CentOS:
sudo yum install libpng-develAny relatively modern version of the png library should suffice (subject to security fixes, etc.)
[Esoteric note: It sometimes happens that incompatible png versions 1.2 and 1.5 are installed on the same machine. This can lead to link errors if the include file from one version is used with the libraries from another. If this happens on your system, you can tell configure where to look for the libraries and include files of one version only using the --with-png=[dir] switch.]
The build of the JS9 tpos program also requires the cfitsio library (version 3.39 or later is preferred). Cfitsio is the de facto standard FITS library. It is available from NASA/HEASARC at the Goddard Space Flight Center:
http://heasarc.gsfc.nasa.gov/fitsio/fitsio.htmlTo tell configure where cfitsio libraries and executables are located, use the --with-cfitsio=[dir] switch, e.g. --with-cfitsio=/usr/local will find the cfitsio libraries in /usr/local/lib.
Deprecated: Instead of cfitsio, you can use the funtools, a FITS library and analysis package that was used in versions of JS9 prior to v1.3. It is available on the JS9 web site:
http://js9.si.edu
To tell configure where funtools libraries and executables are located, use the --with-funtools=[dir] switch, e.g. --with-funtools=/usr/local will find the funtools libraries in /usr/local/lib.
Example configure commands are shown below for a typical Linux Apache setup and for a personal Mac setup:
linux-cgi) ./configure --prefix=/soft/saord \ --with-helper=get \ --with-webdir=/var/www/htdocs/js9 \ --with-cgidir=/var/www/cgi-bin/js9 \ --with-cgiurl=./cgi-bin/js9 \ --with-cgixpath=/soft/saord/bin \ --with-cfitsio=/usr/local \ --with-png=/soft/saord/linux64 \ CC=gcc $* mac-nodejs) ./configure --prefix=$HOME \ --with-helper=nodejs \ --with-webdir=/Users/me/Sites/js9 \ --with-cfitsio=/usr/local \ CC=gcc $*In these examples, the JS9 web files (JavsScript, CSS etc.) will be installed in a js9 sub-directory of htdocs in the /var/www directory or in the Mac user's personal Sites directory. JS9 CGI files will be installed in a subdirectory of the cgi-bin directory. C programs and shell scripts will be installed in sub-directories of the user's home directory.
Once the configure arguments are set up, you run configure, etc. as described in the basic install instructions at: Installing JS9.
Some additional notes on getting the server-side helpers working are added below.
All JS9-specific CGI files and programs should have been built and installed during the standard configure, make, make install process. In particular, the globalOpts.helperType variable in the js9Prefs.json file should have a value of "get" (or you can use "post", if you reset the value manually. Not sure why you would do this but ...)
Of course, you must now ensure that your web server can run the js9Helper.cgi script successfully to execute JS9 CGI commands. Normal web debugging techniques come into play here: check the CGI section of your web server's configuration file and review the web access and error logs. If you continue to have problems, please let us know and we will try to help.
The Node.js server-side helper is noticeably faster than CGI. It also offers more power and flexibility, e.g., the node server supports external control of the browser from the command line via the js9 script and it's underlying js9Msg facility (see External Messaging with JS9 for more information). However, Node.js requires that you open another internet port to the outside world. Node is available at:
http://nodejs.org/Once Node.js is installed, you must start the server-side helper from the JS9 web install directory:
node js9Helper.js >& node.log &Unlike CGI, Node can be run as any user: it does not have to be run as the http daemon user. It certainly should not be run as root! We run it as a non-privileged user with sufficient permissions to run analysis programs. In any case, it should be run with its Unix PATH set to include the directory containing the JS9 helper program, as well as any analysis programs that will be executed by the JS9 server-side helper when requested by the client.
Clients will automatically connect to the Node.js helper when an image is loaded into JS9. The server-side helper listens on a port specified in the js9Prefs.json file by the globalOpts.helper.Port value. The default is 2718, but you can change this to any open port you like.
If you are running in a secure environment (i.e. your web pages use https protocol instead of http), then node server also must be run securely. This is because modern browsers block "active mixed content". To run the Node.js helper using https protocol instead of http, create a js9Secure.json file containing path names to your private key, certificate, and certificate authority files:
{ "key": "/path/to/private.key", "cert": "/path/to/server.certificate", "ca": "/path/to//certifcate.authority" }This file will reside in the directory in which the Node.js helper is started.
It is imperative that you keep your private key file secure! If this key is accessed by unauthorized parties, they can masquerade as your site. The standard recommendation is to change files permission so that only the Node.js user can read it:
chmod 400 private.keyand keep that user's password safe!
Also note that Node.js https support appears to missing a needed routine in v0.10. Please use v0.12 or above for https.