Previous: Is Madrigal appropriate?   Up: Madrigal admin guide   Next: Upgrading Madrigal

Installing Madrigal for the first time


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

  1. A C and a FORTRAN compiler. The free GNU compilers may be downloaded from the GNU Website .
  2. tclsh, which may be downloaded from the Tcl Resource Center and libpng available from Both these are typically included on unix distributions.
  3. A web server.
  4. The environmental variable MADROOT should be set to the path to the Madrigal installation directory. Its recommended this be done in your login script (eg, .bash_profile) because you will need it to run administrative scripts later.
  5. The environmental variable LD_LIBRARY_PATH should be set to $LD_LIBRARY_PATH:$MADROOT/lib. Its recommended this be done in your login script (eg, .bash_profile) because you will need it to run administrative scripts later.

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.

  1. Create a directory to be used as your Madrigal root directory on your unix server. This directory will be referred to as MADROOT.
  2. Create the environment variable MADROOT with that directory path.
  3. Download the latest Madrigal distribution file, madrigal*.tar.gz from the OpenMadrigal distribution page to MADROOT.
  4. gunzip madrigal*.tar.gz
  5. tar -xf madrigal*.tar
  6. Repeat the 3 steps above to get and untar the Sample Experiments file experiments.tar.gz.
  7. Create two virtual directories on your webserver for your madrigal cgi files (which must allow scripts to run) and for your madrigal html files.
  8. 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.
  9. 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.
  10. With Madrigal 2.6, users can now download cached HDF5 files. These cached HDF5 files are created during installation. You will want to make sure you have enough room in your experiments directory (typically about double the existing space used). You can create an ini file to modify how these HDF5 files are created. Instructions below describe how to added derived parameters and/or additional layouts for an given instrument, and optionally by kindat.
  11. 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.
  12. 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, which will test the ability to create plots.
  13. If you want to receive notices about updates to Madrigal, sign up for the openmadrigal-admin mailing list under
  14. Set the script madroot/bin/updateMaster up as a cron job to run once a day.
  15. 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.
  16. 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.

Creating or modifying MADROOT/cachedFiles.ini

By default, Madrigal will create cached HDF5 versions of all default files when Madrigal 2.6 or later is installed. These cached HDF5 files are created so that the user will get a fast response when an HDF5 file is requested for download. Large HDF5 files can take minutes to create from the Cedar source file. By default, these cached HDF5 files only contain the parameters in the Cedar file, and arrange the data only in the default table layout. If you want these cached HDF5 files to have any additional derived parameters or extra layout formats, you will need to create a file called cachedFiles.ini in your MADROOT directory.

With Madrigal 2.6, there is only one additional layout available: 'array'. If you ask for this additional layout, your HDF5 file will contain a subdirectory where each parameter has its own two-dimensional table, where one dimension is the dependent variable (for example, range) and the other dimension is record. This layout is more complex than the standard table layout, but may allow easier plotting of the data.

This ini file has section headings which are simply instrument ids (kinst code). The key value pairs can be:

  1. <kindat>_parms = <comma-delimited parameter list>
  2. <kindat>_formats = <python dictionary>
  3. default_parms = <comma-delimited parameter list>
  4. default_formats = <python dictionary>

If an instrument does not have a section, then defaults are used. If a given instrument has a default_parms or default_formats key, then that will be used, unless a key with the matching kindat (kind or data) is found. If an instrument has kindat keys and no default, and the kindat does not match, the default is used.

Here's an example cachedFiles.ini file. In this case, for kinst=30 (the Millstone ISR), kindats 13204 and 13300 are listed separately. If any other kindat is found, the default key is used:

# Millstone Hill radars 
# 13204 is F regions winds file

13204_parms =
13204_formats = {}
# 13300 is gridded ISR data
13300_parms = 
13300_formats = {}
# all other kindats should be as follows
default_parms = gdlat,glon,gdalt,ne,dne 
default_formats = {'array':'range'}

Previous: Is Madrigal appropriate?   Up: Madrigal admin guide   Next: Upgrading Madrigal