Instructions for DEVise/JavaScreen/Peptide-CGI Installation $Id: bmrb_mirror_instructions,v 1.2.8.4 2003/04/04 17:42:36 wenger Exp $ * CONTENTS This file contains instructions for installing the DEVise-related software at BMRB web sites. * OVERALL INSTALLATION Installation of the DEVise-related software should be done after installing the rest of the web site mirror, so that you can test the software after it is installed. There are four main parts to the DEVise-related mirror installation: - Demo area skeleton - DEVise itself - JavaScreen - Peptide-cgi 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.7.4.) You should get the following files: - demo.tar.gz - JavaScreen.tar.gz - linux-intel.tar.gz, solaris-intel.tar.gz, or solaris-sparc.tar.gz, depending on your machine architecture - peptide-cgi_x.x.tgz (where x.x is the peptide-cgi version) * USERS You should have to do very little, if any, of the installation process as root. Because the current schema requires that some files be in the /p/devise directory, you will probably have to create that directory as root. There may be a few things you'll have to do as root, simply because of file and directory permissions. However, none of the installation inherently requires root permissions. 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 /p/devise and its subdirectories, and write permission in /p/devise/session/.tmp. The web server user needs write permission in the peptide-cgi dynamic_data and dynamic_sessions directories. * DEMO AREA INSTALLATION At the present time, the demo area skeleton must be installed in /p/devise. (We hope to fix that limitation soon.) To install the demo area skeleton, simply create a /p/devise directory. Then go to that directory and untar the demo.tar.gz file. * DEVISE INSTALLATION Note: the linux-intel distribution may not work on versions of Linux other than RedHat 7.2. If you have a different version of Linux, and experience problems, please contact the DEVise Development group (devise-sup@cs.wisc.edu). We are working on a fix for this problem. First, untar the linux-intel.tar.gz, or solaris-sparc.tar.gz file. To make sure that DEVise itself runs properly, go to the run directory, and run the script devise.loc. 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. 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. * JAVASCREEN INSTALLATION First, untar the JavaScreen.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). Then copy the appropriate Makefile.config.* file to Makefile.config, and edit Makefile.config appropriately. 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.) After doing this, run the command 'make -f Makefile.setup clean setup'. You can test the JavaScreen as follows: - Run the command 'restart_jspop'. - This should start the following processes: - java jspop - java jss - Xvfb - devised - Then run js. 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 cding 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 soemthing 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. * PEPTIDE-CGI INSTALLATION See the INSTALL file in the peptide-cgi directory for installation instructions. * CONCLUSION After all of this has been done, you should be able to access DEVise/JavaScreen visualizations via the NMR Browser.