CISC 474 Spring 2005

Class Participation grade P02
Resin Installation Instructions

Set up Install Start Deploy Test

(CISC474 P02)

The following instructions will guide you through Resin installation and setup on jaguar.cis.udel.edu.

Acknowledgments: Emily Gibson, B.F. Caviness, Luis Mendes and Phill Conrad all contributed to this installation procedure. Questions should be directed to the discussion board on WebCT.

Important: Read this first!

These instructions assume that you are using csh or tcsh as your login shell. If you are using sh or bash, you may need to tailor these instructions to your particular shell. For example, the "setenv" command is specific to csh and tcsh; you may need to use the assignment operator and/or the "export" command with bash.

If you are bash user, or if you run into anything else that needs to be tweaked for specific environments, I invite you to start a discussion with your classmates on the discussion board in WebCT about what adjustments are needed to the generic directions below.

Environment Set Up

First login to jaguar.cis.udel.edu and set up a definition for the environment variable JAVA_HOME. Under csh/tcsh, this is done by editing your ~/.cshrc file. Add a definition for the following environment variable:
```
setenv JAVA_HOME /usr/local/j2sdk1.4.0_01
```
Resin will need this for installation.
For convenience, I recommend setting a RESIN_HOME variable to /usa/$USER/cisc474/resin-2.1.16/ (Yes, you don't have this directory yet, but you will create it in a later step.)
To have your .cshrc changes take effect in your current xterm, type:
```
% source ~/.cshrc
```

Installation and Set up

Create a cisc474 directory in your home directory, /usa/$USER (where $USER is your username). This is the directory where you will install Resin. Also create:
/usa/$USER/cisc474/public_html for your deployed web apps and
/usa/$USER/cisc474/web_dev for your development apps.
Download and extract the 2.1.16 version of resin in your /usa/$USER/cisc474/ directory.

Hints:

the "wget" command can be used at the Unix command line to download a file directly to jaguar. If you don't use that command, and if your web browser is not running on jaguar directly, you'll have to download the file, and then copy it over to jaguar. The "scp" command can be used to do a secure file copy (secure ftp).
If you don't know how to extract a gzipped tar file, read the man pages for gunzip and tar.

Edit the /usa/$USER/cisc474/resin-2.1.16/conf/resin.conf file:

Notice the sample database pool configuration. You will be modifying those values later this semester when you connect your resin setup with the mysql database.
Find the <http-server> tag. Change your <doc-dir> to:
```
<doc-dir>/usa/$USER/cisc474/public_html</doc-dir>
```
Find your http port number and fill in the <http-server> tag:
```
<http port='8xxx'/>
```
where '8xxx' is your port number.
Around line 250, find the following comment:
```
     
```
Right before this comment, paste the contents of this admin web-app. This will help you keep track of statistics about your deployed web applications.
For testing purposes, you can leave the rest of the example web applications in your resin.conf file. Once you have verified Resin is installed properly, you can remove the other web-app lines from your conf file (as well as the source files).

In your resin.conf file, find the lines like this:

<!--
     - The srun port, read by both JVM and plugin
     - 127.0.0.1 is the localhost
    -->
  <srun host='127.0.0.1' port='6802'/>

and change them to look like this (this comments out the "srun" XML tag)

  <!--
     - The srun port, read by both JVM and plugin
     - 127.0.0.1 is the localhost
<srun host='127.0.0.1' port='6802'/>
    -->

If you don't do this, you may run into errors with "6802" being a "port already in use" when you start up your server.

You are now ready to complete the installation and configuration of Resin by going into your resin directory and typing the following commands:

% ./configure

NOTE: Don't type "make" afterwards; just ".configure"

/usa/$USERNAME/cisc474/resin-2.1.16

/m/usa-linux/$USERNAME/cisc474/resin-2.1.16

Troubleshooting:

If the configure fails with an error message about JAVA_HOME, check the spelling of the changes you made to your startup files at an earlier step.
In general, run through all the steps from the beginning, checking each step, before reporting a problem to your TA or instructor.
Remember that changes to your .cshrc file don't take effect unless you log off and back on, or do a "source .cshrc".
Your .cshrc file may contain logic to detect which system you are on and run different commands. If you use Java on more than one ECL machine, Java may be in different places. Be sure to look for EVERY occurence of JAVA_HOME before setting the variable. Check the definition of the variable with the commmand
```
echo $JAVA_HOME
  
```

Starting & Stopping Resin

```
$RESIN_HOME/bin/httpd.sh start
```
```
$RESIN_HOME/bin/httpd.sh stop
```

Deploying Test Applications

If you recall, the original web application directory was set to /doc. Move the applications in your resin directory to your public_html directory:

% mv /usa/$USER/cisc474/resin-2.1.16/doc/* /usa/$USER/cisc474/public_html/

Once you have finished your test, you may remove any of the source files in your public_html directory that you like.

Testing Resin

Start Resin as stated above.
Open a web browser to http://jaguar.cis.udel.edu:8xxx/ where '8xxx' is your port number.
If your connection is refused, Resin is not setup correctly. Try stopping the server and executing $RESIN_HOME/httpd.sh without the word start to see any error messages.

Once you have your server running, leave it up

Note that throughout the course, your server should be left running when you log off.

For now, if jaguar is rebooted, you'll have to log back on and restart it.

A future homework assignment will involve writing a shell script and a cron job to automatically check periodically (say, every hour) to make sure your server is up, and restart it if needed, but for the time being, you'll have to do that manually. (If you don't know what a cron job is, look into it. :-) )

A hint: the "curl" utility was recently installed on jaguar; among other things, it can be used at the command line to attempt a connection to a web page, and report a status code depending on whether the URL is accessible or not.

Another hint: if you try this, beware the "sorcerer's apprentice" bug... don't create a script that would spawn other scripts, or attempt to fix a broken server in a tight loop indefinitely. If the server won't startup due to a configuration problem, it is better, after some reasonably number of attempts over some reasonable period of time, to just give up and send an email to someone (e.g. to you).

Due Date and Grading

By noon Thursday 2/24, for a "check" class participation grade, please either

have your server up and running OR,
if you are unable to do so due to technical problems, post a detailed description of what you ran into in the forum on WebCT.

Check-plus grading

"Check-plus" grading may be assigned for the first students who post particularly helpful items to the WebCT board (e.g. how to adapt the instructions for the bash shell, how to solve common problems, etc.).

Do be honest: I reserve the right to withhold check-plus grading if I suspect someone is manipulating the system (i.e. having their buddy create a fake problem so that they can post a clever answer.)

Check-minus grading

If you don't make a reasonable attempt at getting Resin installed by the deadline listed above, you might earn a check-minus instead of a check once you do get it running. To avoid that, either get it running by Thursday, or post a message to the WebCT discussion board with specific and detailed information about what problems you ran into.

Note that a zero on this assignment isn't really an option; you have to get this server running eventually in order to do future assignments.

Next Steps

In an upcoming class participation assignment or homework, you'll be asked to get the sample servlet from pp. 30-32 of your textbook up on your resin web site. So if you want to start on that, feel free.

Once that is done, you might also try your hand at the utility for automatically restarting your web server after a system reboot or server crash.

I advise holding off for now on the MySQL setup. We are still determining whether we are going to run one large MySQL configuration under the TA/Instructors account and create accounts for all of you (so MySQL would be running on only one port) or have each of you install your own MySQL installation. Though the latter would give you more experience, due to system load, I'm leaning towards the former. But until we determine that, it would be premature to get MySQL up and running.