Installing Madrigal for the first time

Prerequisites

Most of the prerequisites for Madrigal are pre-installed in any modern unix distribution. They are:

A C and a FORTRAN compiler. The free GNU compilers may be downloaded from the GNU Website .
tclsh, which may be downloaded from the Tcl Resource Center .
The freetype library, available from www.freetype.org.
A web server.

The installation script will stop and issue a warning if any prerequisite is missing.

Installation instructions

Madrigal can be installed on any unix server with a web server. If you want to link your data in with data on other Madrigal servers, please notify the OpenMadrigal administrator. In general you do not need root permission to install madrigal once the prerequisites listed above are installed. You may need to be root to create the html and cgi directories in the web server. It is generally easiest to then chown for those two directories to the user that will be installing Madrigal.

Create a directory to be used as your Madrigal root directory on your unix server. This directory will be referred to as MADROOT.
Create the environment variable MADROOT with that directory path.
Download the latest Madrigal distribution file, madrigal*.tar.Z from the OpenMadrigal distribution page to MADROOT.
uncompress madrigal*.tar.Z
tar -xf madrigal*.tar
Repeat the 3 steps above to get and untar the Sample Experiments file experiments.tar.Z.
Create two virtual directories on your webserver for your madrigal cgi files (which must allow scripts to run) and for your madrigal html files.
In madroot, there will now be a file called madrigal.cfg.template. Copy it to madrigal.cfg, and edit all the configuration parameters, as described in the Editing madrigal.cfg section below.
Edit the file MADROOT/metadata/siteTab.txt with a unique id to include your site. The format of siteTab.txt is described here. If you want to be an official Madrigal site that other Madrigal sites share data with, request the OpenMadrigal administrator to assign you this id. If you do not want all the sites in siteTab.txt included in your combined inventory listing, just remove these sites from siteTab.txt. Links to data from sites you leave in the siteTab.txt file will appear in your Madrigal web site.
Be sure to cd to MADROOT before running the following step. Then you should be able to complete the installation simply by typing
```
bash installMadrigal  &> install.log &
```
There may be a long pause when running updateMaster near the end of the installation since the instParmTab.txt metadata file is being built for the first time by examining every data file, but future calls to updateMaster will be much faster since only new experiments are examined. Help with any installation errors is available from the OpenMadrigal administrator.
If there were no errors, your madrigal installation should be running at the url given by madrigal. You can also test it by running MADROOT/bin/python testMadrigalBuild.py, which will test the ability to create plots.
If you want to receive notices about updates to Madrigal, sign up for the openmadrigal-admin mailing list under www.openmadrigal.org.
Set the script madroot/bin/updateMaster up as a cron job to run once a day.
If you want to add any documentation pages specific to your site to the Madrigal documentation pages, see the other admin tasks section of this manual.
If you want to add your own rules of the road to the Madrigal experiment page, see the other admin tasks section of this manual.

Editing the madrigal.cfg file

The madrigal.cfg file contains all the configuration information specific to your installation. This section discusses how to edit that file for each parameter. The madrigal.cfg.template file contains examples of each parameter.

MADROOT - Madrigal root directory (absolute). This must be set as an environmental variable.
MADSERVER - Web server for accessing Madrigal
MADSERVERROOT - document virtual directory relative to MADSERVER. If the full Madrigal Url is the same as the MADSERVER field (for example, if the url is http://madrigal.hao.ucar.edu/), then set this field to a period. (Example: MADSERVERROOT = . ) This directory should not allow files to be executed.
MADSERVERCGI - script virtual directory relative to MADSERVER. The web server will need write permission in this directory. This directory should be set to execute only.
MADSERVERDOCABS - Directory (absolute) where Madrigal documentation and images necessary for the Web software should be installed. You will need write permission to install files in this directory. You may need to be root to create this directory.
MADSERVERCGIABS - Directory (absolute) where Madrigal CGI scripts will be installed. You will need write permission to install files in this directory. You may need to be root to create this directory.
SITEID - Site ID - Must be unique and same as in siteTab.txt
HTMLSTYLE - Body style of html pages
INDEXHEAD - Heading in the top-level Madrigal page
CONTACT - Mailto link of contact person(s) for this madrigal installation. Multiple email addresses may be included if separated by commas.
MAILSERVER - Name of mailserver (possibly localhost if running sendmail)
NOTESMANAGER - If you want someone to be notified whenever a user adds a note to an experiment, uncomment this optional line and add the email address. See below for a discussion of the optional notes feature and how to configure it after installation.
MAXGLOBALQUERIES - The maximum number of global queries you want to allow to run on your webserver at any one time. Since a global query can take minutes or even hours to run, setting this value will limit the number of these background jobs running on your webserver. Users who request a global query when the server is at this maximum already will get a message requesting them to resubmit the query later.
MAXTEMPREPORTS - Sets the maximum size of the tempReports directory in GB. If not set, defaults to 2 GB.