:: :: microarrays.org

The AMAD Install Guide

J.DeRisi - December 1999

Platform and Recommended Machine Configuration

This guide covers the installation of the AMAD database for the Linux operating system with the Apache webserver. Note that AMAD may be installed on any web server capable of running PERL scripts, including Windows machines and Macintoshes.

The recommended Linux configuration is listed below:

Processor: Pentium III 450Mhz or faster
Memory: 128Mb or more
Storage: 12Gb or greater
OS: RedHat Linux 6.0 or higher
WebServer: Apache 1.3 or higher (standard with RedHat 6.1)

Having said this, I have successfully installed and run AMAD using a bare minimum configuration consisting of a Pentium I (166Mhz) with 40Mb of RAM and 2Gb of hard drive space. Thus, if you are willing to sacrifice speed and storage capacity, it is likely that could obtain such a machine for <$500.

Several vendors now ship computers with Linux pre-installed, including Dell Computers (www.dell.com) and the Linux Store (www.thelinuxstore.com) (Contact Paul Larson at 1-800-217-9035 x1038). A computer with the above configuration should cost less than $1200. Buying a computer with Linux preinstalled can take some of the potential headache away that comes with installing Linux yourself. However, installing Linux yourself is a good learning experience, especially for those with little or no unix skills, and imparts a better understanding of the OS. Therefore, you might consider installing Linux on a machine for which you already own. Note that this will wipe out any existing data on the hard drive, as well as any other OS (like Windows). The latest distribution of RedHat Linux comes with a very nice graphical install program that makes this task significantly more simple. In addition, there are now dozens of books available describing the install process and general use of Linux. When installing Linux yourself, make sure to install the Apache web server package. If you have a machine running RedHat Linux and you are unsure whether apache is installed, type on the command line:

rpm -q apache

If the response comes back something like:

apache-1.3.9-4

you have apache installed on your machine. (Note that the version numbers may be slightly different.) To know whether apache is actually running or not, type:

ps -aux

Several of the many lines that scroll by should like:

nobody 1231 0.0 0.0 2888 0 ? SW Dec28 0:00 [httpd]

The [httpd] indicates that apache is running. If there are no processes running as "httpd" and you have apache installed, then it is a simple matter to add this service to the list of startup services, so that it will automatically come on when you boot the machine. You can manually start apache by simply typing "httpd."

Grab the tar file

From this point on, it is assumed you have a machine with Linux successfully installed, and that you have root access. That is, you can login under the user name "root" which, by definition, gives you control over all aspects of the machine. Make sure you have configured the network settings correctly. Keep your IP number, assigned to you by your network administrator, or domain name handy, as you will be needing it to complete the AMAD installation.

AMAD can be downloaded from www.microarrays.org as a single .tar file. "tar" stands for Tape Archive, and is so named after the unix program "tar", originally written to create tape backups of unix based machines. The ".Z" on the end of the tar file indicates the file was passed through a compression filter to reduce the file size.

Pre-installation Preparation

If you are unfamiliar with unix style operating systems, the subject of permissions is an important cencept to understand. I highly recommend picking up one of the hundreds of how-to books for Linux, to thoroughly understand how file permissions operate. Nevertheless, here is a short description. Every file and directory has a set of permissions associated with it. These govern who may read, write to, or execute a given file or program. To display the permissions for a listing of files in any given directory, use the command "ls -l" An example of the output looks like:

drwx------ 2 joe joe 1024 Aug 21 21:10 nsmail

-rwxrwxr-x 1 joe dbusers 322 Nov 8 02:38 test3.pl

The set of 10 characters on the left hand side indicate the permissions, and the next two text fields indicate the user and group. The first character is usually used to denote a directory or file. In this case, "nsmail" is a directory. The next 9 characters represent three repeating fields of permissions. In each field the first character indicates Read permissions, the second is for Write permissions and the third character is for eXecute permissions. The first field is for the user, the second field is for the group (which many users may be a member of), and the third field is for other permissions. Other refers to everyone else. Thus, in the above example, the directory nsmail may be read from, and written to by the user "joe" and group "joe." Usually, for every user, there is a group by the same name, typically containing only that user. The file "test3.pl" may be read, written, and executed by the user "joe" and any member of the group "dbusers." In addition, anybody else may read this file and execute it, but they can not write to it. If we wished to modify these permissions, we could use the "chmod" command. Type "man chmod" for a detailed description of how this works. If we are operating as root, we could also freely change the owner using the "chown" command, or change the group with "chgrp" command.

The reason for emphasizing this concept is that the AMAD installation has various sets of permissions, users and groups associated with it. For your Linux system, you must create the necessary groups before extracting the database scripts from the tar file. For this set of scripts, we use a generic group called "dbusers" and the user name "nobody." This latter user is what the web server runs under, and therefore these scripts exist with only a limited set of permissions, thus limiting any unintended behaviors. All default Linux distributions install a user "nobody" but the dbusers group name is custom. You can add this group name using the following command:

groupadd dbusers

Optionally, you can use one of the nifty graphical user and group managers that now come standard with the GNOME desktop environment, or the KDE desktop environment.

The next step is to decompress the tar file and extract the individual files it contains. It is important to note that the tar file contains a complete structure of directories and files, and that these will be created when you "un-tar" the file. Thus, it is necessary to extract the directories and files into the proper location. Although you may choose to setup AMAD anywhere you prefer on your system, we recommend creating a directory (using the "mkdir" command) called "httpd" in the /usr/local subdirectory. To do this, type:

cd /usr/local

mkdir httpd

Make sure this subdirectory has the following permissions and attributes, by using the following commands:

chgrp dbusers httpd

chmod a+xr httpd

chmod g+w httpd

This allows this directory to be read and execute by all, and gives the group write permissions.

Now, download the tar file, or move the tar file into the /usr/local/httpd directory.

Unpack AMAD!

Now, type the following command to extract the contents of the tar file:

tar -xvpf AMADv1.tar.Z --uncompress --same-owner

The "x" option specifies that the files are to be eXtracted. The "v" option specifies that the program should tell the user what is going on, the "p" option preserves the permissions that were associated with each file, and the "f" option designates the filename, which in this case, is "AMADv1.tar.Z" The "--uncompress" option takes care of the ".Z" compression, and the "--same-owner" option restores the owner and group names to the files that are extracted. Assuming nothing went wrong, a number of filenames will blaze down your screen.

Now, try an "ls -l" command, and you should see that there is a new directory called "dbhttpd" in the /usr/local/httpd directory:

drwxrwxr-x 6 nobody dbusers 4096 Dec 29 23:40 dbhttpd

This indicates that you have successfully unpacked the AMAD database scripts. Congratulations!

Set up the Apache config files

Apache is the name of the webserver program distributed with most Linux systems. To really understand the power of the apache web server, I highly recommend "Apache: The Definitive Guide" by Ben and Peter Laurie. To get AMAD to function correctly, we need to tell apache where the necessary files are, and which files are to be executed as scripts, rather than read as standard web content. Assuming you are installing AMAD in the recommended location (/usr/local/httpd), then you can go ahead an relax, because I've provided the necessary configuration files for you. Type:

cd /usr/local/httpd/dbhttpd/httpdconf/

ls -l

You should see:

-rw-rw-r-- 1 root dbusers 1986 Dec 28 16:30 access.conf

-rw-rw-r-- 1 root dbusers 11229 Dec 28 16:20 httpd.conf

-rw-rw-r-- 1 root dbusers 8418 Dec 28 16:32 srm.conf

Now, you must replace your existing config files with these. With most RedHat Linux distributions, the relevant apache files are kept in /etc/httpd/conf. Check to see that these are indeed in the place we assume they are, and if so, go ahead and copy these three config files over your old ones. (You may wish to keep a backup of the old files in another directory, just in case.) To copy these new config files over your old ones, use the command:

cp * /etc/httpd/conf/

(You will be asked whether you would like to overwrite the existing files)

Now, we need to restart apache (assuming it was running to begin with). To stop the web server on a typical RedHat Linux distribution, type: (note that the single quotes are the kind which tilt to the left)

kill `cat /var/run/httpd.pid`

Now, to restart apache, type:

httpd

If no error messages are returned, everything should be working, but there are still some pieces of information that need to be modified before AMAD is completely functional.

Edit your .profile

We need to add the AMAD script directory to the list of directories containing executable programs. To do this, type:

pico /etc/profile

Pico is a simple text editor, and "profile" is a config file. Find the line that looks something like:

PATH="$PATH:/usr/X11R6/bin"

Now, change it add the AMAD script directory path information: (separate paths are separated by a colon character )

PATH="$PATH:/usr/X11R6/bin:/usr/local/httpd/dbhttpd/cgi-bin/amad"

Type Control-O to write out the file, and then Control-X to quit Pico.

Type:

source /etc/profile

to make Linux read the new path information in that file.

Modify AMAD scripts with your local IP information

Before you can use AMAD, you need to modify a location specific items in the scripts. Type:

pico /usr/local/httpd/dbhttpd/cgi-bin/amad/arraylib.pl

Near the top of this file, you will see the lines:

# Edit this one to match your machine address

$server = "http://your_domain_name.edu";

This is where you set the domain name of your server. Change the "your_domain_name.edu" to whatever your domain name happens to be. Write the file out by hitting Control-O, and then quit using Control-X.

Now edit the entry page into the database which redirects the browser to the database menu script:

pico /usr/local/httpd/dbhttpd/html/amad/index.html

Edit the line:

to replace "your_domain_name.edu" with your domain name. Save the file and quit Pico.

You are almost there! Now, there are just a few more domain name replacements to take care of, and you will be ready! Type:

pico /usr/local/httpd/dbhttpd/html/amad/ssi/header.shtml

Again, replace all instances of "your_domain_name.edu" with your domain name. (There are six total). Do the exact same thing for:

pico /usr/local/httpd/dbhttpd/html/amad/ssi/navbar.shtml

You have now completed all the necessary changes needed to configure AMAD.

Give AMAD a try.

From NetScape on another computer, or even on the Linux machine you are running your database, type your IP number or domain name into the URL field. If you are greeted with the AMAD menu screen, you have successfully installed AMAD. The database comes with one sample yeast file already in the database. You can download a GenePix results file from www.microarrays.org to test submitting data.

TroubleShooting

If you receive an error message, something is mis-configured. Looking at the apache error log may help. Type:

tail /var/log/httpd/error_log

Security issues

While no security system is completely bulletproof, passwords and other forms of security are relatively easy to implement using apache directives. Take a look at the manual pages for "htpasswd" for a simple way to use passwords protection. (Also read my short guide to Making your Linux box more secure - posted 8/2000 on the DeRisi Lab web site.)

Backing up your data

Your original scans and results files should be backed up on CD-ROM or some other archive quality media. The files necessary to backup the data in the database include all files under the following two directories:

/usr/local/httpd/dbhttpd/html/amad/data

/usr/local/httpd/dbhttpd/lib/amad/tools