Installing JS9

Summary for the Impatient

Retrieve and Unpack the Source Code Tar File

The current JS9 source tar file is available at:

    https://js9.si.edu
The source tar file will unpack into a js9-[version] directory with the usual tar command, e.g:
    tar xfz js9-[version].tar.gz
You also can clone JS9 from GitHub:
    git clone https://github.com/ericmandel/js9

Run JS9 using the file:// URI

Once the tar file is unpacked, you should be able to load any of the js9*.html web pages into your browser using the file:// URI. For example, if you unpacked the tar file into /Users/me on a Mac, then you can point your browser to:
    file:///Users/me/js9-[version]/js9basics.html
to see the basic JS9 demo page. You then can drag any FITS image file onto the JS9 display and view it, change contrast/bias, colormaps, scale, create regions, etc. Furthermore, if you load the imexam web page:
    file:///Users/me/js9-[version]/js9imexam.html
you can move a region around and run browser-based analysis as the region changes.

NB: The file://URI does not work in Google Chrome: Chrome doesn't permit a local HTML file to read other local files. The workaround is to start Chrome with the --allow-file-access-from-files switch:

    # Linux:
    chrome --allow-file-access-from-files
    # Mac:
    open /Applications/Google\ Chrome.app --args --allow-file-access-from-files
Firefox and Safari do not have this restriction.

If you just want to run JS9 in this simple way, you are done. However, you might want to edit the js9prefs.js file to set up default values for colormaps, scaling, etc. See: JS9 Site Preferences for a description of the available parameters.

Do You Want to Run JS9 as a Desktop Program from the Command Line?

JS9 can be used as a Desktop app: you can load images into the app's (Chrome) web page instead of using a browser. The JS9 Desktop app simply requires that you install Electron.js, which is described here:
  http://electron.atom.io
To install Electron, go to the release page: http://electron.atom.io/releases, choose the latest available release, and download the zip file for your platform. On a Mac, Electron.app should be installed in the /Applications folder; you will have to run it manually (from the Finder) the first time. On Linux, the electron program should be placed in your PATH. (Note that Electron requires a recent version of Linux: Ubuntu 12.04, Fedora 21, Debian 8. Thus, for example, it runs on CentOS 7 but not CentOS 6).

NB: It is important to note that Electron.js is not a web browser: the web pages you load are not sandboxed. Our JS9 Desktop application code takes additional precautions to enhance security by disabling node.js integration and Javascript eval in web pages. However, these precautions are likely to be insufficient to guard against malicious web pages. Therefore, it is critically important that you load only local or trusted remote web pages into the JS9 Desktop app. See: Electron.js security for more information.

Once the Electron app is installed, generate the JS9 quick-start files:

  ./mkjs9 -q
  Editing js9Prefs.json for Node.js helper ...
  Editing js9prefs.js for Node.js helper ...
  Generating js9 script for JS9 messaging and Desktop use ...

  If you plan to use Electron.app with JS9, consider codesign'ing it:

  sudo codesign --force --deep --sign - /Applications/Electron.app/Contents/MacOS/Electron/

  This will avoid repeated requests to allow incoming connections.
The mkjs9 script will create a js9prefs.js file (for the browser) and a js9Prefs.json file (for the JS9 helper), which you can edit to add preferred JS9 properties, as well as a js9 script to start the JS9 app. On a Mac, you probably will want to codesign the Electron.app application to avoid repeated requests about incoming connections (see example above).

Run the js9 script to start the app and load data files:

  js9 ~/data/casa.fits &
and then use the same script to interact with the JS9 page (or any other JS9-enabled web page):
  js9 cmap cool
  js9 regions circle
See: External Messaging for more details.

Do You Want to Install JS9 in a Web Server?

If you want to run JS9 in a "real" web server, build and install the JS9 tools and files using the standard GNU procedure:
  ./configure --with-webdir=[path] ... other switches ...
  make
  make install
At a minimum, you should run configure with the --with-webdir=[path] switch, which specifies the directory into which the JS9 web files (JavaScript, CSS, etc.) will be installed. We recommend that this directory only contain the installed JS9 files, i.e. that you install JS9 into its own self-contained directory. This will make upgrading to new versions much easier.

As described in Creating a JS9 Web Page, a few JavaScript and CSS files must be loaded into a JS9-enabled web page. Ordinarily this is done in the page's header, which typically will look something like this:

  <head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  <meta http-equiv="X-UA-Compatible" content="IE=Edge;chrome=1" >
  <meta name="viewport" content="width=device-width, initial-scale=1" >
  <link type="image/x-icon" rel="shortcut icon" href="./favicon.ico">
  <link type="text/css" rel="stylesheet" href="js9support.css">
  <link type="text/css" rel="stylesheet" href="js9.css">
  <script type="text/javascript" src="js9prefs.js"></script>
  <script type="text/javascript" src="js9support.min.js"></script>
  <script type="text/javascript" src="js9.min.js"></script>
  <script type="text/javascript" src="js9plugins.js"></script>
  </head>
Also during startup, JS9 will asynchronously load the js9worker.js file in order to create a worker process and will load either the astroem.js file or the astroemw.js and astroemw.wasm files, depending on whether WebAssembly is supported on your browser.

Although none of these files are large, it always is worthwhile making downloaded files smaller to shorten the web page load time. One straight-forward way to do this, if you have control of the Apache web server, is to use the Apache rewrite capability to serve gzip'ed files in place of requested (uncompressed) files, if the former exist. Using this technique, your header can remain as shown above, but the Apache server will send gzip'ed versions when available. To do this, you can add code such as the following to the Apache httpd.conf:

  <IfModule mod_headers.c%gt;
    # turn on rewrite
    RewriteEngine on

    # Serve gzip compressed CSS files if they exist
    # and the client accepts gzip.
    RewriteCond "%{HTTP:Accept-encoding}" "gzip"
    RewriteCond "%{REQUEST_FILENAME}\.gz" -s
    RewriteRule "^(.*)\.css" "$1\.css\.gz" [QSA]

    # Serve gzip compressed JS files if they exist
    # and the client accepts gzip.
    RewriteCond "%{HTTP:Accept-encoding}" "gzip"
    RewriteCond "%{REQUEST_FILENAME}\.gz" -s
    RewriteRule "^(.*)\.js" "$1\.js\.gz" [QSA]

    # Serve gzip compressed wasm files if they exist
    # and the client accepts gzip.
    RewriteCond "%{HTTP:Accept-encoding}" "gzip"
    RewriteCond "%{REQUEST_FILENAME}\.gz" -s
    RewriteRule "^(.*)\.wasm" "$1\.wasm\.gz" [QSA]

    # Serve correct content types, and prevent mod_deflate double gzip.
    RewriteRule "\.css\.gz$" "-" [T=text/css,E=no-gzip:1]
    RewriteRule "\.js\.gz$" "-" [T=text/javascript,E=no-gzip:1]
    RewriteRule "\.wasm\.gz$" "-" [T=application/octet-stream,E=no-gzip:1]

    <FilesMatch "(\.js\.gz|\.css\.gz|\.wasm\.gz)$"%gt;
    # Serve correct encoding type.
    Header append Content-Encoding gzip
    # Force proxies to cache gzipped &
    # non-gzipped css/js files separately.
    Header append Vary Accept-Encoding
    </FilesMatch%gt;
  </IfModule%gt;

Note that the JS9 Makefile contains a rule called install-gzip which will install gzip'ed copies of several JS9 files along side the uncompressed versions:

  ./configure ...
  make
  make install
  make install-gzip

Do You Want to Configure Server-side Analysis or External Messaging?

JS9 supports server-side ("back-end") analysis on FITS data using a server-side helper. This capability allows you to execute virtually any command-line analysis program from JS9. The analysis command is run on the back-end server and results viewed on your web page. You can utilize 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 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.

In addition, JS9 supports command-line messaging between the shell and JS9, pyjs9 Python messaging between the Python and JS9, and also has large-file support via the use of representation files. These capabilities requires the configuration of a Node.js-based server-side helper.

You configure a JS9 helper by adding additional switches to the configure command, e.g.:

  # where to find cfitsio and install binaries, what sort of helper to build:
  ./configure  --with-cfitsio=[path_to_cfitsio] --prefix=$HOME --with-helper=nod
  make
  make install
See: Installing a Server-side Helper for details.

Build the JS9 System

Once you have decided on the configuration of your JS9 system, run configure to generate various build files:
  ./configure [your JS9 switches]

and then build the JS9 system using the make command:

   make

Finalize Your Site Preferences

The js9prefs.js file and js9Prefs.json file contain various default settings for JS9, e.g. default colormap and scale for image display. Feel free to edit this file to set up your own site-specific parameters. See JS9 Site Preferences for a description of the available parameters.

Install the JS9 System

When the build is completed, you can install the JS9 into your web tree:

    make install

The first time you install JS9, your preference files will also be installed. After that, the install command will not install these files in order to avoid overwriting custom files. You can explicitly re-install preference files using:

    make install-prefs
or simply copy them into the install directory. Clean up the build directory using the command:
    make clean

Optionally Install the JS9 Test Data Files

If you want to display our test data files in the JS9 demo pages, you must retrieve the JS9 data file tar file from the JS9 web site:

    https://js9.si.edu
and untar it into the JS9 web install directory. This will create sub-directories containing the image data. These data files also are available on GitHub:
    https://github.com/ericmandel/js9data
Last updated: August 23, 2017