Instructions for DEVise/JavaScreen/Peptide-CGI Installation $Id: bmrb_mirror_instructions,v 1.7 2007/06/21 17:04:42 wenger Exp $ * INTRODUCTION This file contains instructions for installing the DEVise-related software at BMRB mirror sites. Note: the DEVise/JavaScreen software is designed to be untarred into a directory that you use for configuration and testing, and then installed into other directories for the "production" system once the configuration is correct. This way, when you need to install a new version, you can untar the new version in a new directory, copy over the configuration settings from your previous version, test that everything is okay, and then install over the top of the existing "production" version. This allows upgrades with the minimum change of taking down the "production" system. * OVERALL INSTALLATION You can install DEVise separately from the rest of the BMRB mirror site; however, some of the DEVise-related configuration depends on where you will be installing the BMRB mirror files. Whether you install DEVise before or after the rest of the mirror site, it's best to test the DEVise-related software by itself, and then in combination with the NMR Browser. There are five main parts to the DEVise-related mirror installation: - Demo area skeleton - DEVise itself - JavaScreen - Peptide-cgi - ChemShift The parts should be installed in that order. * FILES To get the distribution files, go to: ftp://ftp.cs.wisc.edu/pub/devise Then go to the directory containing the most recent DEVise distribution. The directory is of the form Devise-x.x.x, where x.x.x is the DEVise version. (At the time of writing, the most recent version is 1.9.0.1.) You should get the following files: - Devise-x.x.x-demo.tar.gz - Devise-x.x.x-linux-intel*.tar.gz or Devise-x.x.x-solaris-sparc.tar.gz, depending on your machine architecture - Devise-JavaScreen-x.x.x.tar.gz (note that the JavaScreen version is different from the corresponding DEVise version; DEVise and JavaScreen tar files located in the same ftp directory are compatible) - peptide-cgi_x.x.tgz (where x.x is the peptide-cgi version) - Optionally, ChemShift_x.x.x.tgz * USERS You should have to do very little, if any, of the installation process as root. It's probably best if you create a "normal" user to do all of the installation, and if you run into places that need root permission, simply manually create the required directories as root (you may want to do a chown on them, to the user doing the installation). The JavaScreen processes do *not* have to run as root, and in fact should not, for security. Basically, the DEVised processes run to support the JavaScreen need read permissions in the demo area, and write permission in the .tmp directory within the demo area session directory. The web server user needs write permission in the peptide-cgi dynamic_data and dynamic_sessions directories. * DEVISE DIRECTORY It's probably best, but not totally necessary, to create a top-level devise directory to hold all of the installation files. (Note that DEVise no longer has to be installed in the specific /p/devise directory.) When you're done untarring the tarballs, , you should get a directory structure that looks something like this: - devise - bin - ChemShift (optional) - doc - JavaScreen - peptide-cgi_x.x.x - README - tcl - cache - demo - dyn_lib - lib - public - run - tk The actual installation scripts will then install a separate "production" copy of the software. (The demo area you create by untarring the demo tarball is the "production" demo area, though.) * DEMO AREA INSTALLATION The DEVise demo area contains DEVise session, schema, and data files. There are a few sessions already set up that you can use for testing; Peptide-CGI will eventually create new sessions and data in directories that are linked into the demo area. To install the demo area skeleton, simply untar the Devise-x.x.x-demo.tar.gz file in an appropriate directory. Note that this file untars simply as demo/..., not devise/demo/... * DEVISE INSTALLATION First, untar the appropriate Devise-x.x.x-.tar.gz file. If you're not sure which Devise file is appropriate for your platform, please contact the DEVise Development group (devise-sup@cs.wisc.edu). To make sure that DEVise itself runs properly, go to the run directory, and run the script devise. When DEVise starts up, select Open from the Session menu, and then select one of the DEVise session (*.ds) files. When you open the session file, one or more windows with graphs should be displayed. You should also run the script devise.ldemo to make sure that the demo area skeleton works correctly. If DEVise core dumps on startup, especially on Linux, try getting rid of the dyn_lib directory. Sometimes having it helps, sometimes it doesn't. You may also want to try linking in different versions of the libraries in the dyn_lib directory. Note: in the current form of the distribution, DEVise itself is not configured to be installed other that as part of the JavaScreen installation. This limitation should be removed in the near future. * XVFB INSTALLATION Note that for the JavaScreen to work, you must have Xvfb (X virtual frame buffer) installed on the machine on which the JSS and DEViseds will run. You can find sources, and executables for various architectures, on the web. It doesn't matter where you install Xvfb, since you will edit the config file to indicate the path to the executable. You should try running the following command to make sure that Xvfb works on your system: Xvfb :1 -screen 0 1280x1024x8 On some systems (especially some Linux systems) you may have to add the arguments '-fp "unix/:-1"' to enable Xvfb to find the fonts it needs. On Fedora Core 6, this should be '-fp "unix/:7100"'. * JAVASCREEN INSTALLATION First, untar the Devise-JavaScreen-x.x.x.tar.gz file. You MUST untar this file in the same directory where you untarred the DEVise distribution file (because the JavaScreen distribution relies on relative links to some of the DEVise files). (Note that the JavaScreen version no longer matches the DEVise version.) Change to the JavaScreen directory, then copy the appropriate Makefile.config.* file to Makefile.config, and edit Makefile.config appropriately. CONFIG.txt has detailed explanations of all of the configuration parameters. Note that you will have to change the INSTALL_HOST variable. Make sure that your Makefile.config defines ERROR_EMAIL (for example, 'ERROR_EMAIL = zoo@bmrb.wisc.edu'). (This is the user who will get email warnings in the case of JSPoP errors being detected.) Once you've finished editing Makefile.config, run the command 'make -f Makefile.setup clean setup'. You can test the JavaScreen as follows: - Run the command 'restart_jspop test 1'. (Note that running the JSPoP with the ID 'test' avoids conflict with any production JSPoP running as 'regular' on the same machine.) - This should start the following processes: - java jspop - java jss - Xvfb - devised - Then run 'js -cmdport6266' (you need to specify a cmdport of 6266 to connect with a JSPoP running as test. You should be able to open a session file in the JavaScreen. - Run 'kill_jsall' to kill off the JavaScreen processes before doing the actual install. To do the actual installation, perform the following steps: - If you are installing a new version of the JavaScreen in place of an older version, if possible do the installation when no user is actually connected to the JSPoP. You can find out what users are connected by looking at the jspop.out.regular log file in the logs directory of the previously-installed version. - If you are installing a new version of the JavaScreen in place of an older version, it's a good idea to send an email to any known users that the JavaScreen will be unavailable for a short period of time. - If you are installing a new version of the JavaScreen in place of an older version, you MUST kill all of the processes of the old version before doing the installation. Do this by going to the directory where the old version is installed, and running the command kill_jsall Make sure you've killed everything off -- run 'ps' and make sure there are no jspop, jss, or devised processes running. - Run the command: make -f Makefile.setup install This will do the actual installation into your selected directory. - Edit your crontab file to create a cron job that automatically checks the JSPop. Look at the supplied cron_entry.* files, especially cron_entry.tuna, for examples. The cron job should cd to the directory where the JavaScreen is installed, and then run "./run_check regular 4". After installing the cron job, you should get an email stating that no jspop process was found; after that, the JavaScreen-related processes should be running (see the list of processes above). Note that you may need to edit the paths in run_check according to the details of your installation. - Edit your crontab file to create a cron job that generates JavaScreen usage statistics once a week, by cd'ing to the directory where the JavaScreen is installed and running scripts/get_stats_bmrb. Look at cron_entry.tuna for an example. - Once you've installed the JavaScreen, make sure that the servers have restarted correctly. You MUST have a jspop process, a jss process, and at least one devised process. You should also run the 'check_connect' command. If all of the necessary processes are running, this will output 'OK'. Any other output means that something is not working correctly. The final check is to actually run the JavaScreen applet on your web site. You can do this via the NMR Data Browser or the jsa.html web page. * JAVASCREEN CLIENT-ONLY INSTALLATION It is now possible to do a JavaScreen client-only installation for cases where only the client software has been updated since the last installation. First, perform the steps in the previous section through "you can test the JavaScreen as follows". To do the actual client-only installation, perform the following steps: - Run the command: make -f Makefile.setup client_install This will do the actual installation into your selected directory. That's it! * PEPTIDE-CGI INSTALLATION Untar the peptide-cgi_x.x.tgz in an appropriate directory. Then see the INSTALL_NOTES.txt file in the peptide-cgi directory for configuration and installation instructions. * CHEM_SHIFT INSTALLATION If you are going to support the chemical shift reference visualizations, you need to install ChemShift. (Note that this is optional -- Peptide-CGI will work, and will generate the other visualizations, without ChemShift.) To install ChemShift, create a ChemShift directory, cd to that directory, and untar the ChemShift_x.x.x.tgz file. Then follow the instructions in INSTALL_NOTES.txt. * CONCLUSION After all of this has been done, you should be able to access DEVise/JavaScreen visualizations via the NMR Browser.