#### NOMAD INSTALLATION INSTRUCTIONS #### This document is intended as an explanation of, and guide to NOMAD's installation procedure. Section 1, Requirements Section 2, Installation Section 3, Troubleshooting and Bug Reports ### Section 1 ## 1.0 Server Requirements See the file requirements for a detailed explanation of the requirements for installing and using NOMAD. This section will briefly list them, but more detail is given in the accompanying file. 1) Unix, or Unix like system. This includes Linux, Mac OS X and probably many others, however NOMAD is (so far) only tested on Linux (Red Hat, Debian, Mandrake) and Mac OS X. 2) Apache Webserver, this should be available for most unix like systems and is often installed by default. 3) Perl Interpreter, Perl is the primarly language used to write NOMAD, so without it you are not going to get anywhere! NOMAD is written and tested using versions of Perl greater than 5. 4) Perl Modules, NOMAD takes advantage of several Perl modules, each is available through CPAN. The modules required are, DBI, DBD::mysql, GD, CGI. GD requires libgd. 5) MySQL Database, NOMAD requires MySQL and the SQL code is not portable to other databases at present. ## 1.1 Client Requirements 1) Web Browser that can support Java, Javascript and Macromedia Flash ### Section 2 Incredibly Brief version ./configure make install More Detailed Version ## 2.1 Getting NOMAD OK, the chances are if you are reading this you already have a version of NOMAD, but if you need to know where to get it, or where to update it, read on. In the future, we will provide formally packaged installations (likely as .rpm and .deb files). our intention is to comply with the filesystem hierarchy standard; if you detect any inconsistency, please advise us. However, at the moment only a source distribution is available. There are currently two main methods of getting NOMAD, the first is to download a tarball of NOMAD from the NOMAD website at sourceforge. The second, and less recommended method is to use CVS to obtain the latest version of NOMAD, please be aware that versions direct from CVS are often broken, so only do this if you are not using NOMAD in a production role and you are interested in exploring the bleeding edge. Instructions for retrieving NOMAD via CVS are on the NOMAD Website . ## 2.2 Configuration # 2.2.1 Configuration of other programs 1) MySQL, The installation requires a working version of the mysqld server, please consult the mysql documentation for advice on how to obtain and configure MySQL. NOMAD should work on a most reasonably recent versions of MySQL and does not require any non-standard configuration or compiler options to MySQL. The install requires root access to the MySQL server with no password set. If your MySQL server has a root password please see section 3.1 "Trouble Shooting and Bug Reporting" Once NOMAD is installed you should require a root password for access to your MySQL server as doing otherwise leaves the data open to destruction by malicous users... 2) Apache. The installation requires several changes to the Apache configuration file. The changes are fairly straightforward and several platform specific examples are available in the examples subdirectory of this doc directory. Please note that simply dropping these files into the right place in your system may not be enough to allow NOMAD to function as you would like, other system, network and miscellaneous settings could interfere. The NOMAD specific requirements are as follows, ScriptAlias /nomad-cgi/ "/your/webserver/docroot/NOMAD/nomad-cgi/" AddHandler cgi-script .pl AllowOverride ALL Options None Options ExecCGI Order allow,deny Allow from all In addition, the ServerName and ServerAdmin should be specified, see the Apache docs for more information on installing and configuring Apache. 3) Perl Modules, DBI, DBD::mysql and GD. The most straightforward method of installation is to use the CPAN perl module, see for more information on using and installing the CPAN module. ## Section 2.2.2 Configuration of NOMAD Installation Configuration should be straight forward, however there are several potential problems. 1) Untar the NOMAD distribution 2) cd into the NOMAD dir and run configure (type ./configure ) You should see several lines of text similar to found HTTPD_ROOT at .... found HTTPD_CONTROL at ... deduced that HTTPD_USER is ... found MYSQL_CONTROL at ... found MYSQL_ADMIN at ... found MYSQL_RUN at ... PASSWORD_GENERATOR = perl -e "print rand;" creating Makefile. use it. in each case the '...' will be replaced with the system specific location/user for each line. This is the first place where a problem my crop up. If the configure script cannot find/deduce something it requires to set up NOMAD it will report an error and stop running. If running configure produces an error please refer to section 3 "Troubleshooting and Bug Reports" ## 2.3 Instalation The standard install of NOMAD is very straightforward simply run, as the superuser: make install This will create the NOMAD database in MySQL and install NOMAD into the main sytem file hierarchy, specifically into the the Document root of the webserver and the following directories. /etc/nomad /usr/lib/nomad /usr/share/doc/nomad /usr/share/nomad /var/cache/nomad /var/cache/nomad/tree /var/lib/nomad /var/log/nomad Developers can choose a second type of installation, cvs_link. Instead of installing the various parts of NOMAD into the main file hierarchy cvs_link makes a symbolic link from each of those places to the files in the same dir as the configure and make scripts. This allows developers to keep there version in sync with the latest and greatest without having to reinstall all the time. This type of install requires that the files in this directory are left in place, otherwise NOMAD will stop working. This installation is only recommended for developers. As superuser, type: make cvs_link ## Section 2.4 Testing Please try your installation of NOMAD, point your web browser at or the server on which you have installed NOMAD. Click on the link to create a user, fill in the form and attempt to log in, if creating a user succeeds, and you can log in the install itself was probably succesful, if not see section 3, "Troubleshooting and Bug Reporting" ### Section 3 Troubleshooting and Bug Reporting ## Section 3.1 Troubleshooting # Section 3.1.1 Configuration Errors 1) The configure script may fail if it cannot find the salient parts of the system it needs to install and configure NOMAD. The script will give you an error message saying something like error: could not find ... where ... refers to something like the webserver document root, or the MySQL control script. or, Error: could not find User value in apache configuration Both of these are probably the result of either you didn't install the dependancies first, like Apache or MySQL, or they are in a place that is not catered for by the configure script. In the first case install the dependancies and try again! In the second case some judicious editing of the configuration script may be required. For example if the script cannot locate the Document root of the webserver you can insert it into the configure script in the following section, find this part of the configure script and add the location of the document root to the list of possibilities: # find HTTPD root if [ ! $httpd_root ]; then possibilities="/var/www/html /var/www /var/httpd /Library/Webserver/Documents" name="HTTPD root" var=HTTPD_ROOT detect "$name" $var $failures $possibilities failures=$(($failures+$?)); fi For most of the configuration variables there is a similar list of possiblities, you can add the locations required for your installation at the end of each list of possibilities. If your system is not catered for in the configure script because the location of something is not listed please let us know so we can add it to the configure script for everyone else's benefit! Use the Bug Reporter at the sourceforge site (more on Bug Reporting Below). ## Section 3.1.2 Installation Errors Permission denied, you did run the install script as the superuser, didn't you? Failed to connect to database through ... Is the MySQL database installed and running? If not, start it! Access to Database denied Do you have a root password set for MySQL? The current install scripts assume the root mysql user does not have a password. We are working on making the install be more friendly to password protected installs of MySQL, but it isn't there yet... The work around is either to temporarily unsetting the root password for MySQL or to go through the Makefile and add '-p' to each call to the mysql and mysqladmin program, the script will then prompt for the password each time it attempts to access the database. ## Section 3.1.3 Post Install Problems Cannot Create User? There are a number of possibilities as to why you may not be able to create users. Did you modify the Apache configuration files? Did you install the perl modules DBI, DBD::mSQL modules? Is MySQL running? Submission of jpeg files of arrays fails Did you install the Perl Module GD? Broken links, non-functional features Well, it is still an alpha.... Check the Bug Reports page and if the bug isn't already there, submit a bug describing the problem. ## Section 3.2 Bug Reporting Please check that all the dependancies are installed and working prior to reporting a bug and Apache and MySQL are correctly configured. Please submit bugs via our sourceforge website using the sourceforge Bug Reporter NOMAD is under rapid development so let us know where it needs fixing, bug reports with fixes are especially welcomed # Installation instructions v1.0a2 Last modified 02/01/2002.