previous up next Upgrading or moving Madrigal Doc home Madrigal home
Previous: Installing Madrigal   Up: Madrigal admin guide   Next: Madrigal data model

Upgrading or moving Madrigal

With the release of Madrigal 2.5, the procedure to upgrade and/or move Madrigal to a new server was improved. To either upgrade Madrigal on your existing server, or to move it to another server, you can now do a clean installation first. This clean installation will not effect your present Madrigal server. If the clean installation succeeds, then you migrate your Madrigal data and make the new server active. If the migration fails for any reason, it is simple to switch back to the original Madrigal server. Of course you can also directly upgrade your present Madrigal installation also - you simply need to be sure the server is fully backed up in case the installation fails.

To determine what release of Madrigal you are presently running, see the title of the main documentation page (that's the page you get to by clicking on Documentation from the home page). The latest release of Madrigal will always be available from the OpenMadrigal web site via the Download/Update link.

This page covers the following administrative tasks:

 

Setting environmental variables

It is now required that the Madrigal administrator set the following environmental variables in their login script:

The installation script will also tell you if you need to set LD_LIBRARY_PATH for the web server, and give you instructions if its needed.

 

Upgrading Madrigal (using the same server)

To upgrade Madrigal to the latest release using the same server:

  1. Create a new MADROOT directory for your new installation on your existing Madrigal server. After installation this will be your permanent MADROOT directory (unless you then follow the moving MADROOT procedure). Set your MADROOT environmental variable to this new directory.
  2. Create two temporary directories on your existing Madrigal server for 1) html files and 2) cgi scripts. For example, if you standard Madrigal server stores its html files under /var/www/html/madrigal and its cgi files under /var/www/cgi-bin/madrigal, you could create the directories /var/www/html/madrigal2 and /var/www/cgi-bin/madrigal2.
  3. From OpenMadrigal, download the Madrigal distribution file, madrigal*.tar.gz to your MADROOT directory.
  4. From OpenMadrigal, download the sample experiment file, experiments.tar.gz to your MADROOT directory.
  5. gunzip experiments.tar.gz and madrigal.tar.gz
  6. tar -xf experiments.tar.
  7. tar -xf madrigal*.tar.
  8. Copy madrigal.cfg from the old MADROOT to the new MADROOT, and edit the following five fields:
    1. MADROOT - set to new MADROOT
    2. MADSERVERROOT - New, temporary url directory relative to MADSERVER for the temporary html files. This directory should not allow files to be executed. For the "/var/www/html/madrigal2" example, this would be "madrigal2".
    3. MADSERVERCGI - New, temporary script directory relative to MADSERVER for temporary cgi files. The web server will need write permission in this directory. This directory should be set to execute only. For the "/var/www/cgi-bin/madrigal2" example , this would be "madrigal2".
    4. MADSERVERDOCABS - New, temporary directory (absolute) where html files should be installed. This directory was created in step 2.
    5. MADSERVERCGIABS - New, temporary cgi directory. This directory was created in step 2.
  9. Copy siteTab.txt from the old MADROOT/metadata directory to the new MADROOT/metadata directory. This file is comma-delimited. For your site, edit field 4 to be the new MADSERVERROOT set in step 8-2, and field 5 to be the new MADSERVERCGI set in step 8-3.
  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 here describe how to added derived parameters and/or additional layouts for an given instrument, and optionally by kindat.
  11. Be sure to cd to new MADROOT before running the following step. Run the following command:
    bash installMadrigal  &> install.log &
    Help with any installation errors is available from the OpenMadrigal administrator.
  12. If there were no errors, test your madrigal installation at the url given by MADSERVERROOT. You can also test it by running MADROOT/bin/python testMadrigalBuild.py, which will test the ability to create plots.
  13. In the next step you will run a script that will switch the active Madrigal installation to the new installation. By default, it will copy all the experiment data to the new MADROOT directory, so you'll need to make sure there's enough room on the hard drive for two copies of the experiments directory. If you do not have room for that, you may use the --moveExp flag to cause the experiment directory to be moved to the new MADROOT directory, rather than copied. Also, you can use the --skipExp flag if you'd prefer to manually copy the experiments[0-9]* directories over. This script will also modify madrigal.cfg to use the web paths of the original Madrigal server, and will then install the new cgi scripts and html documents to those original web directories. In this way users will not need to enter a new url to visit your Madrigal site. If any problem emerges with the new version, instructions are given in the next step for switching back to the original Madrigal version. 
    bin/switchMadrigal.py [--moveExp] [--skipExp] <original_madroot> <new_madroot>
    You should now be able to test the new release of Madrigal at the main Madrigal url.
  14. If for any reason you decide you want to switch back to the old version of Madrigal, it is easy to do so. Just export MADROOT to be the old value, cd to the old MADROOT, and run:
    	  tclsh configureHtml
	  tclsh configureScripts
	  bin/updateMaster
    You should now see the old version of Madrigal at the main Madrigal url. If you used the --moveExp flag when switching in the previous step, you will need to preceed this procedure by moving the experiments back to the original MADROOT directory and running ./configureExperiments.
  15. There may be reasons you do not want the value of the MADROOT environmental variable to change when you update Madrigal on the same server. For example, you may have written programs using the Madrigal API that hard-coded the MADROOT value. If, after you are done with the procedure above, you decide you want the new version on Madrigal to run using the old MADROOT value, follow the procedure Moving the Madrigal madroot directory.
  16. This update procedure creates two copies of Madrigal and all the data. Once you are satisfied with the new version of Madrigal, free up disk space by removing:
    1. The old MADROOT directory
    2. The temporary MADSERVERROOT directory created in step 9-2.
    3. The temporary MADSERVERCGI directory created in step 9-3.

 

Moving Madrigal to a new server (installs the latest Madrigal version)

If you want to move Madrigal to a new server, and the main Madrigal url is changing, you should notify the OpenMadrigal administrator so that they can update the Madrigal metadata that lists Madrigal sites. If you are moving to a new server but retaining the old Madrigal url, there is no need to change the metadata file siteTab.txt.

In this procedure you will first install a fresh version of Madrigal, and then run a script to import your Madrigal data from your old server.

  1. Install a new version of Madrigal as decribed in Installing Madrigal for the first time. You may use your old madrigal.cfg file as a guide, but you will need to change it for the fields that have changed for the new server.
  2. Once you are happy with the new installation, run the following script from the MADROOT directory of the new Madrigal server. Include the --skipExp flag if you prefer to copy the experiments[0-9]* directories over manually, rather than have the script do it: 
    bin/switchMadrigal.py --newUrl [--skipExp] <username>@<server>:<original_madroot> <new_madroot>
  3. Check that all the data from the old Madrigal server now appears on the new server.
  4. Once you are satisfied with the new installation, you may remove the old installation by removing the following three directories on the old server:
    1. The MADSERVERROOT directory on the old server (specified in old_madroot/madrigal.cfg)
    2. The MADSERVERCGI directory on the old server (specified in old_madroot/madrigal.cfg)
    3. The old MADROOT directory

Moving the Madrigal madroot directory

There may be reasons you do not want the value of the MADROOT environmental variable to change when you update Madrigal on the same server. For example, you may have written programs using the Madrigal API that hard-coded the MADROOT value. If, after installing Madrigal as described in the Upgrading Madrigal section, you want to have MADROOT return to its original value, do the following:

  1. Rename the old MADROOT directory to a different name
  2. Rename the new, active MADROOT directory to the original MADROOT name.
  3. Set the MADROOT environmental variable to be the original MADROOT name.
  4. Make sure LD_LIBRARY_PATH contains <original MADROOT>:lib
  5. Edit the MADROOT line in madrigal.cfg to be the original MADROOT name.
  6. Next you will rerun the installation. It should be faster since the creation of metadata and cached HDF5 files will be skipped:
    bash installMadrigal &> install2.log &
  7. Help with any installation errors is available from the OpenMadrigal administrator.

Direct Upgrade

To install the latest Madrigal release using the Direct Upgrade method:

  1. Be sure you have recently backed up your entire server in case a problem arises.
  2. Download the Madrigal distribution file, madrigal*.tar.gz to your MADROOT directory.
  3. gunzip madrigal*.tar.gz
  4. tar -xf madrigal*.tar (This will not overwrite any file meant to be modified by a specific Madrigal installation.)
  5. Compare the new version of madrigal.cfg.template file to your existing madrigal.cfg file found under the MADROOT directory. If any new parameters have been added to the end of the file, add them to you madrigal.cfg file and edit just those entries as described in the installation documentation.
  6. 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 here describe how to added derived parameters and/or additional layouts for an given instrument, and optionally by kindat.
  7. 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. There may also be a delay when all the cached HDF5 files are created. Help with any installation errors is available from the OpenMadrigal administrator.
  8. If there were no errors, your madrigal installation should be running at the url given by MADSERVERROOT. You can also test it by running MADROOT/bin/python testMadrigalBuild.py, which will test the ability to create plots.
  9. 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.
  10. 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.
previous up next Upgrading or moving Madrigal Doc home Madrigal home
Previous: Installing Madrigal   Up: Madrigal admin guide   Next: Madrigal data model