CMap Install
If you are upgrading from a previous version of Cmap, please see the "upgrade" directory.
If you are installing CMap anew and are pretty experienced with Unix systems administration, here is the very abbreviated explanation of how to install CMap:
Install libpng, libjpeg and libgd 2.x
Install the database of your choice (MySQL, PostgreSQL, Oracle, Sybase, SQLite); create tables with contents of "sql" directory; grant appropriate user permissions
Install Perl 5.6.1 or greater and a web server with CGI capabilities (e.g., Apache 1.3.x or 2.x)
Execute "perl Build.PL; ./Build; su; ./Build install"; install any other Perl modules reported missing by the build process
Modify configuration information in "/path/to/conf/cmap.conf/*.conf"
Import your data or the sample data included in the "data" directory
Examine maps in viewer
Note: The install script will ask if you want to create a demo. This will import test data into the database and create the needed config file. This is easy if you have a CMap database already constructed (if not it will ask to set up a CMap database in MySQL).
If you need further instructions, read on.
There are quite a number of prerequisites to getting CMap running:
libgd 2.x
A database (MySQL, Oracle 9x, Sybase, PostgreSQL, SQLite)
Perl (5.6.1 or higher)
A web server, Apache version 1.3.x or 2.x suggested
Directories for CMap components
Various CPAN modules (listed below)
Versions prior to 0.10 required mod_perl, but this is no longer the case. As such, CMap should actually work with any web server that supports CGI, not just Apache (e.g., Microsoft IIS, Netscape, etc.).
If you are using a modern version of Linux, you should be able to use a package manager to install at least some of these packages.
It is sometimes helpful to see a list of available packages. On a Fedora/Red Hat machine, the command "$ sudo yum list all | less" will give you a list of the packages. In Ubuntu, using the graphical synaptic package manager is easier ("$ sudo synaptic").
-
Red Hat, Fedora
$ sudo yum install gd.i386
-
Debian, Ubuntu
$ sudo apt-get install libgd2-xpm
NOTE: To get GD.pm to install when using a packaged libgd, you may have to install the gd-devel package as well (fedora: gd-devel.i386, Ubundu: libgd2-xpm-dev).
Unfortunately, unless your operating system can install libgd via a package manager, you're pretty much on your own for installing libgd. Versions of CMap before 0.10 would work with either the 1.x or 2.x version of libgd, but the new dependency on GD::SVG for creating SVG output necessitates libgd 2.x. With any luck, you may already have it on your system if you have a GNU/Linux system. To check, you could just skip this step for now and wait to see if the Perl module GD.pm will install properly. If it complains that it can't find libgd, then come back here. Note that as of version 2.0.28, libgd produces GIF images again. This version of CMap assumes you have the latest versions of libgd and GD.pm in order to produce GIFs.
Installation of libgd can easily be one of the more frustrating parts of this installation. There are a number of dependencies including the zlib compression library and whatever image libraries you want, like JPEG, libpng, and libgif. Again, you may already have some of these libraries, so you needn't panic just yet. One way to see if you do is to check the directories "/usr/lib" and "/usr/local/lib" for files that look like "libgd*," "libjpeg*," "libpng*," and "libgif*". If you're using something like RedHat Linux, you could try the "locate" command for each of these (without the star as it does wildcard searching on its own).
To install libgd, retrieve the source (tar.gz package) from the libgd.org website. When you go to build libgd, it should tell you which libraries it can and can't find. You definitely won't get far without zlib installed, so you need to do that first. Then you can look to see which kinds of files libgd will be able to write after you run the configure process. You'll want to be sure that you can at least write JPEG (Joint Photographic Experts Group) and PNG (Portable Network Graphics) formats.
Here are URLs to help you track down everything you need to install libgd:
libgd: http://www.libgd.org/
JGEP: http://www.ijg.org/
The CMap application relies on a relational database management system (RDBMS) to store and retrieve data. If you already have a database such as MySQL (at least version 4.0 required), you can skip ahead to the next section. If not and you're doing this on your own and are not a trained DBA, I'd recommend using MySQL (http://www.mysql.com/) for your database. It's free, extremely stable, flexible, and fun. Another free database that can be highly recommended is PostgreSQL (http://www.postgresql.org/). Oracle is really overkill for such a lightweight application as this because the code doesn't rely on much of anything from the database except joins (no transactions, no referential integrity, no stored procedures, etc.).
Note: Oracle 8.x doesn't support ANSI-standard left joins, so some parts of the application will fail. If you can't upgrade, then you can alter the few SQL statements that cause problems.
I'll assume that you're going to use MySQL. If you don't already have MySQL on your system, you can get everything you need either from your software vendor or directly from http://www.mysql.com/. There is a package called "Apache Toolbox" that claims to be able to install MySQL and Apache and many other things. It's available at http://www.apachetoolbox.com/. Additionally, RedHat Linux offers RPMs for installing everything you need, Debian GNU/Linux offers apt-get and their DEB packages, or you can get precompiled binaries from MySQL for the architecture of your machine. You may also choose to install from source, depending on your bent. There are a number of freely available GUI (Graphical User Interface) and web-based tools to help you manage your databases if you want an alternative to MySQL's command-line tools; see the MySQL website for more information. If you get really stuck, then MySQL AB, the company which develops and releases MySQL, offers commercial support.
Once you've settled on your database of choice and have a working installation, you need to create the tables that will hold the data for the comparative maps. In the "sql" directory, you will find create scripts for all the databases on which CMap is known to run.
If you are installing CMap tables into a Chado database please see the documentation in the chado_integration directory. This will guide you through installing the tables.
For MySQL, you can do the following to create the database "CMAP" and grant appropriate permissions to a user "joe" with the password "foobar":
$ cd /usr/local/src/cmap-0.XX/
$ mysql -uroot -p -e 'create database CMAP'
$ mysql -uroot -p CMAP < sql/cmap.create.mysql
$ mysql -uroot -p CMAP -e 'grant select, insert, update, delete
on CMAP.* to joe@localhost identified by "foobar"'
$ mysqladmin -uroot -p flush-privilegesIn the above example, you'll be required to type the root password for MySQL.
Note: This is not the same "root" as your system "root." If you never set MySQL's "root" password, then just hit <Enter> at the password prompt (though I'd be remiss if I didn't suggest you actually protect your MySQL root user with a decent password). Be sure to remember the user name and password you'll connect to the database with as you'll need to place these values into your "cmap.conf" file further into the installation process.
After you've granted the user name access to the system, please test that the login works by logging in. For example, if you used the above, try this:
$ mysql -ujoe -pfoobar CMAPIf you get in, then all is well. If not, you should consult your documentation.
If you're using something other than MySQL, then you should do the equivalent of creating the tables described in the create scripts in the "sql" directory and then granting the proper permissions to whatever user will connect to your database.
It would be hard to imagine that a UNIX system wouldn't have some version of Perl installed. We need a minimum of Perl 5.6.0 (but 5.6.1 is recommended). To inspect your version of Perl, type:
$ perl -vOn my current system, the output looks like this:
This is perl, v5.8.0 built for i686-linux
Copyright 1987-2002, Larry Wall
Perl may be copied only under the terms of either the Artistic
License or the GNU General Public License, which may be found
in the Perl 5 source kit.
Complete documentation for Perl, including FAQ lists, should be
found on this system using `man perl' or `perldoc perl'. If you have
access to the Internet, point your browser at http://www.perl.com/,
the Perl Home Page.If your version of Perl is OK, you can skip ahead to the next section. If you have anything 5.00503 or older, you'll need to upgrade your Perl binary. You can often do this with the package management of your system (RPM, apt-get, FreeBSD ports, etc.) or by building from source. If you want or need to compile your own Perl, it's actually fun (in a geeky way), but it will create a lot more work for you to install all the modules that you'll need for CMap. And, obviously, upgrading important system binaries like Perl can cause unforeseen problems. If you're using an established machine that is already being used for other tasks, upgrading Perl could break a lot of things, so you should discuss this with your sysadmin. You should choose what's practical, convenient, and appropriate for you.
If you want to build a new Perl binary from source, it only takes a few minutes. Here's one way:
$ su -
# cd /usr/local/downloads
# ncftp ftp.cpan.org
ncftp> cd /pub/CPAN/src
ncftp> get perl-5.8.0.tar.gz
ncftp> quit
# cd ../src
# tar zxvf ../downloads/perl-5.8.0.tar.gz
# cd perl-5.8.0
# sh Configure -de
# make
# make installFor better downloads, go to the CPAN (Comprehensive Perl Archive Network) website (http://www.cpan.org/) and find a mirror near you. (A mirror is a machine whose owner is nice enough to provide disk space and bandwidth so that demand can be distributed among processors and across geographical areas. Needless to say, it's usually better to find a mirror that's near you as long as that machine isn't overloaded. Just keep trying different machines until you find one with a good, fast connection to you.)
Given that Apache is the most popular web server right now, it's also likely that you'll already have it installed on your system. It's usually installed by default on most Linux distributions as well as Mac OS X. If you need to install Apache, just go to http://www.apache.org/ and follow the directions there. CMap works just fine with both the 1.3.x or 2.x trees. If you wish to use mod_perl, I recommend you stay with the 1.3.x tree of Apache and the latest version of mod_perl < 1.99 (which is actually the beta version for mod_perl 2).
As stated earlier, CMap is simply a CGI application and should therefore run on most any modern web server, including Microsoft IIS. If you have any problems (or success) using a web server other than Apache, please contact the author.
This is likely only a problem for Ubuntu users, as the CGI script directory that Ubuntu uses, is not created by default. To create this file run "sudo mkdir /usr/lib/cgi-bin".
Here is a lits of directories needed for the CMap install. The installer should find these automatically (with the exception of the Ubuntu issue described above). These can be specified as arguments to Build.pl as well.
CONF
The location of the config files. The final directory in the path will be cmap.conf. Meaning that "/usr/local/apache/conf/" will become "/usr/local/apache/conf/cmap.conf/".
CGIBIN
The location of the directory where the web server runs CGI scripts.
TEMPLATES
The location where Template Toolkit templates are stored. (These can be altered after install to suit individual needs.)
WEB_DOCUMENT_ROOT
This is the root directory for the web server. For example "/var/www/" or "/usr/local/apache/htdocs/".
HTDOCS
This is the base directory for the cmap files. It is generally "WEB_DOCUMENT_ROOT/cmap".
CACHE
The location where CMap stores it's cache files. Usually "HTDOCS/tmp".
SESSIONS
The location where CMap stores it's sessions files. Usually "CACHE/sessions".
There are a number of CPAN modules required by the CMap application. You will likely need to install these prior to installing the CMap modules as they are not in the standard Perl distribution. These modules are listed in the "requires" section in the Build.PL build script included with this distribution. It is possible to install the CMap application without installing these modules, but you will see a lot of errors, and, of course, things won't work in the end.
To get the majority of these modules, use the Bundle::CMap module that is available using the CPAN interface. To do this run
$ sudo perl -MCPAN -e "install Bundle::CMap"After running this, see which modules failed to install by running "perl Build.pl". Install any missing modules individually.
Required Modules:
Algorithm::Numerical::Sample
Apache::Htpasswd
Bit::Vector
Cache::Cache
CGI
CGI::Session
Class::Base
Clone
Config::General
Data::Dumper
Date::Format
Data::Page
Data::Pageset
Data::Stag
DBI
DBD::mysql (if you're using MySQL)
DBD::Oracle (if you're using Oracle)
DBD::Pg (if you're using PostgreSQL)
DBD::SQLite (if you're using SQL::Lite)
DBD::Sybase (if you're using Sybase)
Digest::MD5
File::Temp
Filesys::DfPortable
GD
GD::SVG
IO::Tee
Params::Validate
Regexp::Common
Storable
Template
Template::Plugin::Comma
Text::RecordParser
Text::ParseWords
Time::ParseDate
Time::Piece
URI::Escape
XML::Parser::PerlSAX
XML::Simple
Optional Modules:
Apache
The Apache module is only needed if you plan to run CMap under mod_perl.
Several of these modules (e.g., CGI, File::Basename) are in the Perl "core," which means they are installed by default with Perl. Many of the above modules that will likely need installing will have dependencies of their own which you must resolve. This can be very tedious to do by hand, so if you do need to install any of these Perl modules, I'd really recommend you use the CPAN shell, a convenient package that automates the downloading and building of modules. The CPAN shell can also can recursively install all module dependencies automatically, which is a very nice feature. To use the CPAN shell, type the following (as root):
# perl -MCPAN -e shellIf you're curious, the "-M" flag tells Perl to use a particular module, in this case "CPAN.pm," and the "-e" flag tells Perl to execute some code. In this case, we're executing the command "shell," which is exported by CPAN.pm. If you want to see if any of the above modules is already installed on your system, simply substitute the name of the module where "CPAN" occurs above, e.g., for the Class::Base module, you would do the following:
$ perl -MClass::Base -e 'print "OK\n"'If Perl is able to load Class::Base, you'll see "OK"; otherwise, you will certainly know about it, and you could do this (as root):
# perl -MCPAN -e 'install Class::Base'The first time you use the CPAN shell, you will have to answer a few questions mostly concerned with choosing a mirror close to you and where certain important system binaries are (like "gzip," "ncftp," "tar," etc.). Generally you can just keep hitting <Return> to accept the defaults presented in square brackets.
Occasionally a module may not install properly via the CPAN shell, or perhaps it is not available on CPAN or the installation process wants to upgrade your version of Perl to the latest (and you don't want that). In that case, you can install the module in much the same way that you install system binaries. I'd recommend downloading the source into "/usr/local/downloads" and then untarring into "/usr/local/src." Execute "perl Makefile.PL; make; make test; make install" and you're generally all done. If the module requires another module, you'll need to track that down (try "http://search.cpan.org"), install it, then return to installing the first one. After satisfying several dependencies on your own, you'll begin to appreciate all the automation the CPAN shell gives you.
To install the CMap modules and scripts:
$ perl Build.PL
$ ./Build
$ su
# ./Build installThe script will make a best guess for where to place components. If the guesses are incorrect, the installation script can ask for the locations individually. They can also be specified at the command line when running "perl Build.PL" Execute "perl Build.PL -h" to read a brief help message on what they are and how you can specify your choices.
The build options are described above in the "Directories for CMap Components" section.
To change the directories where components are installed from the default locations, specify them in the "./Build install" command by using the "install_path" option. You can change the location of the Perl modules (lib), the scripts (script), the documentation (libdoc) and others. (See the documentation for Module::Build for further details).
# ./Build install --install_path lib=/new/path/During the build process, several important steps will be taken:
The "Bio::GMOD::CMap::Constants.pm" file will be created in the "lib" directory and will have it's "CONFIG_FILE" set to match the "CONF" argument to "Build.PL." Should you ever move or rename the CMap config file, you will have to alter this file.
The "cmap.conf" directory will be created in the "conf" directory and will contain a global.conf to set the "template_dir" and "cache_dir" to match the "TEMPLATES" and "CACHE" arguments to "Build.PL," respectively. It will then be copied to the "CONF" location. Additionally, an example individual database config file, example.conf will be copied into the cmap.conf directory. Individual config files should be edited with specific database information and have is_enabled set to 1.
For additional information on editing config files see ADMINISTRATION.pod.
The "cmap_admin.pl" script will be copied into a system binary location. You will use this script for most CMap administration tasks.
The contents of the "templates" directory will be copied to the "TEMPLATES" directory specified to Build.PL.
The contents of the "htdocs" directory will be copied to the "HTDOCS" directory specified to Build.PL.
The "CACHE" and "SESSIONS" diretories specified will be created and have their permissions set so that files can be written and deleted from it.
The "cmap" CGI script will be created in the "cgi-bin" directory and will be copied to the "CGIBIN" directory specified to Build.PL and its permissions will be changed to make it executable.
Be sure to update your database specific config files located in "cmap.conf/" after installation with the correct database connection information. (If you forget the location of the configuration file and you installed via option #1, then you can look in the "cmap_install.conf" file in the source directory of the CMap application.) Multiple specific .conf files can be used. "example.conf" is provided as an example conf file but should be edited to your liking.
The database section is at the top of the file. I would encourage you to look around this file and change things to affect the look and feel of your site. If you don't like a change, comment out the line by placing a pound sign ("#") at the beginning of the line.
The files will not be overwritten if they exist unless you give the OK:
cmap.conf/*.conf
htdocs/index.html
If you are upgrading (or reinstalling a current version of) CMap, you may have made important changes to those files that you don't want to lose by running "./Build install." You will be prompted as to whether you wish to overwrite these files.
If you're new to CMap, perhaps you will find it easiest simply to import the small set of sample data included in the "data" directory. Just "gunzip" the file and then run it into your database. Note: The file contains SQL statements to empty each table and fill it with values -- so don't run this file into an existing database unless you don't mind losing all your data. E.g., with MySQL you could do this:
$ cd data
$ gunzip sample-dump.sql.gz
$ mysql -ujoe -p CMAP < sample-dump.sqlYou may wish to create a database just for this sample data and another for your own data so you can switch between the two to better understand how to manipulate map settings. Once you have determined that CMap is working properly with the sample data, then you can read the "ADMINISTRATION.pod" document in the "docs" directory (or the HTML version in the installed HTDOCS directory) to understand how to import your own data and create correspondences.
You should protect the web admin tool (e.g., "/cgi-bin/cmap/admin") with a password. To do this with Apache, use the "htpasswd" program that is installed in Apache's "bin" directory. If you've never used htpasswd before, you can get the quick synopsis by giving it a single argument of "-h" or "--help." You should read the help to make sure that you create your password file correctly (making sure not to overwrite an existing file!), but this will probably work just fine for you:
$ su -
# cd /usr/local/apache
# mkdir passwd
# ./bin/htpasswd -c /usr/local/apache/passwd/cmap adminIn the last command, the last argument is the user name which you'll use when prompted by your web browser to see the admin tool, and the argument before that is the name of the new password file that will be created by the "-c" argument. If the file already exists, then don't use "-c."
Now you just need to tell Apache to protect the location of the admin interface with a password like so:
<Location /cgi-bin/cmap/admin>
AuthType Basic
AuthName "CMap Admin"
AuthUserFile /usr/local/apache/passwd/cmap
Require valid-user
</Location>Restart Apache to make the change take effect.
Once you have installed the CMap modules, templates, HTML files, and scripts (command-line and CGI), you should be able to view the CMap application by pointing your browser to the web server, e.g.:
http://my.server.org/cmapIf your web server doesn't have a name that resolves into an IP address for you, then you can just use the IP address instead of a name. You should see a page created during installation summarizing how CMap was installed and with links pointing to the CMap CGI script and tutorials.
The map images will only be used for one request, so you'll need to include some way to clear out old images. A simple cron job will do the trick, so we'll need to add a line root's crontab. You edit a crontab by typing "crontab -e" on the command line. If you are "joe" when you type this, you'll be editing your own crontab. Since your normal login won't likely have the permissions necessary to remove the old images, you should su to root and execute "crontab -e".
The "-e" says that you want to "edit" your crontab using an editor. On most GNU/Linux systems, crontab will use the value of whatever you've set as in your environment as your EDITOR or VISUAL. If nothing is set, then crontab will use "vi," (the VIsual editor, progeny of "ex"). vi is an interesting editor; it requires you understand "command" and "insert" modes, and is usually only used by somewhat hard-core UNIX-y people. Unless you're already familiar with vi, I'd suggest you set your EDITOR to something like "pico," a very intuitive editor and then run crontab. How you set your environment will depend on the shell you're using. I like bash (GNU's Bourne Again SHell), so I edit my "~/.bashrc" file, add "export EDITOR=/usr/bin/pico," then source the file with "source ~/.bashrc." I can see that it worked by typing "echo $EDITOR" on the command line.
However you choose to edit the file, you'll need to paste or type the following lines:
# clear out old CMap images
# added by Joe User <[email protected]>
0 0 * * * find /usr/local/apache/htdocs/cmap/tmp/ -type f -mtime +1 -exec rm -rf {} \;Of course, you'll want to change the "Joe User..." part to reflect your own name and e-mail address. Also, if you choose to store your map images in a location other than the default directory then you'll need to change the above directory to match your choice. When you save the file, crontab will automatically exit. If all went well, you should see a message saying that a new crontab was installed.
If you're curious, a "crontab" is simply a file which uses a particular syntax to describe to the "cron" daemon events which should happen at some interval. (And a "daemon" is a program that runs continuously in the background on a system that does function, like listening for HTTP requests [httpd] or FTP requests [ftpd] or telnet requests [telnetd], etc. You see the pattern: usually the service and a "d" [for "daemon"] makes up the name.) "Crond" (pronounced "cron-dee," always just say "-dee" for the "d") sits around waiting to do something on someones behalf. As you might imagine, the "cron" part implies the time aspect of the program. So, if you wanted to download a file every month from an FTP site to see if it had changed, you might see up a crontab to tell crond to do just that. You edit your crontab by saying "crontab -e" (for "edit"), then enter a line that describes to crond when to run the command and what the command is. Yours might look like this:
# download the foo.dat file
0 0 1 * * <ftp command>From the man(5) page for crontab (which you get by typing "man 5 crontab" on my GNU/Linux system), you get this:
cron(8) examines cron entries once every minute.
The time and date fields are:
field allowed values
----- --------------
minute 0-59
hour 0-23
day of month 1-31
month 1-12 (or names, see below)
day of week 0-7 (0 or 7 is Sun, or use names)Every minute "crond" looks around to see if it's time to do something by looking at the first 5 fields of each line in everybody's crontabs. Stars mean "all" and numbers mean, well, the number. So the above would tell crond to run <ftp command> (whatever that might be) on the zero-th minute of the zero-th hour (i.e., midnight) of the first day of every month, regardless of the day of week. It's a quirky syntax, but pretty powerful. I added a comment to the crontab above with the hash at the beginning of the first line -- that's just being polite. It's always a good idea to comment on what you're doing in a system-wide file like root's crontab so you and everyone else knows what each command does. Be sure to put in your own name and e-mail address. The whole command (starting with the "0") should go on one line.
Note: Some UNIXs may have a slightly different cron format. Check your man page!
All of the dynamic HTML in CMap is generated from templates and reference stylesheets in the hope that you will find it easy to customize the look of the application to your web site. The templates are processed by the CPAN module Template Toolkit (http://www.template-toolkit.com/) which employs a very simple yet powerful syntax for creating displays. In addition, you can specify site-specific introductions to most of the pages in your "cmap.conf" file.
If you have questions or comments about this document, please write the CMap development mailing list at "[email protected]." Please consider joining the list in order to stay up on the latest in the development as well as to contribute your opinions as to the direction that CMap takes in the future.
Please consider allowing the GMOD project advertise your use of our code. If you have a publicly accessible installation of CMap, we would very much like to provide a link from the GMOD website to it!
If you'd like to install and/or hack on the very latest version of CMap, then you'll want to checkout the "cmap" project from the anonymous CVS repository at SourceForge. See the project homepage for instructions:
http://gmod.sourceforge.net/cmapKen Y. Clark <[email protected]>
Ben Faga <[email protected]>