Child pages
  • How to Migrate to Variations 6.0 - In Place

This space has moved to IU's Confluence.
It is located at https://uisapp2.iu.edu/confluence-prd/display/iulV3/

Skip to end of metadata
Go to start of metadata

How to Migrate to Variations 6.0 - In Place

This page lists explains how to upgrade from 5.0.* to 6.0 for both the Variations server and client. The instructions below are written to minimize downtime, preserve data, and provide a smooth transition to Variations 6.0. If you do not need this level of availability and do not need to preserve any data then a fresh install of Variations is suggested. A fresh install also provides an opportunity to move to updated hardware or to RHEL 5. A third alternative is to migrate data and configuration all at once, forcing client upgrades. For this approach, see How to Migrate to Variations 6.0 - New Install.

If you have any questions about or problems with the update process, please email the Variations support list, variations-discuss@lists.sourceforge.net, or if necessary contact Chris Colvard directly (812-856-0026, cjcolvar@indiana.edu).

Important things to note about this migration:

  • The 6.0 server requires 6.0 clients. Previous clients will NOT work with the 6.0 server. 6.0 clients are not compatible with pre-6.0 servers.You will need to migrate your users to the new client (and thus server) before you turn off the old production server.
  • This upgrade process will let you run the old production server in parallel with the new production server so that users can continue to access Variations while you are configuring the new server and rolling out the new clients.
  • The old cataloging server will be turned into the new production server. EXAMPLE_CATALOGING will become EXAMPLE. EXAMPLE_PRODUCTION stays the same but will eventually be turned off.
  • When your migration is complete, and you turn off the old production server, you will just have one server rather than two: the cataloging/production split disappears in 6.0. This simplifies Variations setup for new sites and reduces the complexity of managing Variations.
  • 6.0 will run in a subdirectory underneath /home/dmlserv.
  • This upgrade will also move your implementation from MySQL 4 to MySQL 5 and Java 1.4 to Java 1.6, if you haven't moved already.

Important things to backup before attempting to upgrade:

  • Dmlserv's home directory
    • You may want to backup the content directory separately due to its large size:
      • tar cvzf content-backup.tar.gz content/
      • tar cvzf variations-backup.tar.gz bin/ conf/ COPYING data/ lib/ log/ public_html/ server.jar VERSION
    • Do this using the preferred method for your institution
  • Full-system filesystem
    • Do this using the preferred method for your institution
  • All MySQL Databases
    • Run mysqldump -A --allow-keywords --create-options -r dump.sql

Step 1. Upgrade MySQL, Java, and (optionally) the Operating System

Note: The upgrade process will stop your cataloging and production servers. You will also have to allow time for some hand-editing of configuration files to preserve your local customizations. And finally you will have to restart your Variations server applications.

There are two options for preparing the system for upgrading to Variations 6.0: upgrading the operating system to Red Hat Enterprise Linux 5 (or another OS that provides MySQL 5) or doing an in-place upgrade to MySQL 5.

(Option 1) Upgrade Operating System

Upgrade RHEL4 to RHEL5

Obtain a Red Hat Enterprise Linux 5 install DVD (or CDs). Reboot your machine with the install disc and when prompted type linux upgradeany. When the install process starts make sure to select to upgrade the existing system.

Post-Upgrade Cleanup

Once the RHEL upgrade has finished, check to make sure that all services restarted successfully:

  • /etc/init.d/mysqld status
  • /etc/init.d/dss status
  • /etc/init.d/httpd status** If httpd is not running, try restarting it: /etc/init.d/httpd start** If httpd fails to start, check for a new version of the configuration file that wasn't installed: /etc/httpd/conf/httpd.conf.rpmsave . If this file exists, then do the following:
      • Make a backup of the existing configuration file: cp /etc/httpd/conf/httpd.conf /etc/httpd/conf/httpd.conf.backup
      • Copy new configuration file into place: cp /etc/httpd/conf/httpd.conf.rpmnew /etc/httpd/conf/httpd.conf
      • Edit the new /etc/httpd/conf/httpd.conf to merge over the manual configurations from the backup (the Listen statement and the Variations specific aliases and directory configurations).
    • If httpd still fails to start with an error about mod_jk, then reinstall mod_jk following the instructions at Install mod_jk
  • (If using Samba) /etc/init.d/smb status** Make the following SELinux changes related to samba
      • Allow Samba to access content directory tree: chcon -R -t public_content_rw_t /home/dmlserv/content
      • Allow Samba to write to a public directory: setsebool -P allow_smbd_anon_write=1
      • Allow Samba to write to a home directory: setsebool -P samba_enable_home_dirs=1

Update the system to install any packages that have newer versions than the install disc: yum update

To finish Step 1, skip down to Upgrade JRE and Restart Variations.

(Option 2) Upgrade MySQL Without Upgrading the Operating System

  1. Download the MySQL 5.1 community shared, client, and server RPMs for RHEL4 from http://www.mysql.com
  2. Stop Variations (as dmlserv): bin/stopVariations.sh
  3. Hide the old version of MySQL (as root):

    Run rpm -qa | grep -i mysql to find the exact package number for the commands below.

    rpm -e --justdb mysql-server-4.1.22-2.el4_8.3
    rpm -e --nodeps --justdb mysql-4.1.22-2.el4_8.3
    
  4. Install the new version (as root):

    The installer will try to restart the mysql server and it may hang requiring manual stopping of the process (CTRL+C).

    rpm -i MySQL-shared-community-5.1.45-1.rhel4.i386.rpm
    rpm -i MySQL-client-community-5.1.45-1.rhel4.i386.rpm
    rpm -i MySQL-server-community-5.1.45-1.rhel4.i386.rpm
    
  5. Start up new MySQL server (as root):
    /etc/init.d/mysqld stop
    /etc/init.d/mysql stop
    rm /var/lock/subsys/mysql
    /etc/init.d/mysql start
    

Upgrade JRE and Restart Variations

  1. Install new JRE (See instructions on installing 1.6 JRE)
  2. Check that JAVA_HOME is set to the new JRE: echo $JAVA_HOME
    • If JAVA_HOME is not set to the new JRE, then close your shell and reopen it and check again
  3. Make sure to copy or merge the changes to the java.policy file ($JAVA_HOME/jre/lib/security/java.policy)
  4. Restart Variations: bin/stopVariations.sh; bin/startVariations.sh
  5. Check that the Variations server are running properly by connecting with a 5.0.* client

Step 2. Upgrade the Variations Servers from 5.0.* to 6.0

Install Variations 6.0

Do the following as dmlserv:

  1. Unzip tar: tar xvzf Variations_6.0_Server.tar.gz
  2. Move into new directory: cd Variations-6.0
  3. Run the bin/initVariations.sh script with the values used for existing install (See instructions here for more information)
  4. Merge configuration files: conf/client/dml.conf, conf/server/dmlscript.conf, conf/server/dmlserver.xml
  5. In dmlserver.xml, make the following edits:
    1. Change the endPort attribute in the RMIServerPorts tag to 49932 (the extra port is needed to allow the version 5 production server to run alongside the version 6 server during the transition)
    2. Change jdbcURL and schemaName to EXAMPLE_CATALOGING (from EXAMPLE_METADATA)
    3. Change jdbcURL and schemaName to DMLLIB (from EXAMPLE_DMLLIB)
    4. Make sure to configure new SystemProperty tags: dml.z3950.Container.field.id.label, dml.z3950.Container.field.id.example using values from a digitizer's dml.conf
  6. Copy vocabularies to new server: cp /home/dmlserv/data/vocab/* /home/dmlserv/Variations-6.0/data/vocab/
  7. Copy or merge any other files manually edited in old installation including the user guide (~/public_html/use/)
  8. If using CAS authentication, copy cas jars over from old installation: cp /home/dmlserv/lib/cas* /home/dmlserv/Variations-6.0/lib/

Moving to New Server

Do the following as dmlserv except where noted:

  1. Stop Variations: /home/dmlserv/bin/stopVariations.sh
  2. Adjust MySQL column: echo 'alter table Container change column `condition` physicalCondition mediumtext' | mysql -u dmlserv EXAMPLE_CATALOGING
  3. Update Apache aliases to point to new install (as root): perl -pi -e 's/dmlserv\/public_html/dmlserv\/Variations-6.0\/public_html/g' /etc/httpd/conf/httpd.conf
  4. Restart Apache (as root): /etc/init.d/httpd restart
  5. Allow Apache to read the new directory (as root): setsebool -P httpd_read_user_content=1
  6. Start Variations (6.0): /home/dmlserv/Variations-6.0/bin/startVariations.sh
  7. Bring up old production Variations server: /home/dmlserv/bin/libapp-passwordless.sh start EXAMPLE_PRODUCTION
  8. Check that everything is running: bin/checkVariations.sh . You should see output listing both EXAMPLE_PRODUCTION and EXAMPLE under Databases currently running

    Make sure to merge any added entries to your crontab before replacing it.

  9. Replace crontab with 6.0 crontab: crontab /home/dmlserv/Variations-6.0/bin/crontab

Additional steps for Variations-Web

  1. Rebuild mod_jk Apache module:
    1. Download latest mod_jk sources from http://tomcat.apache.org/download-connectors.cgi
    2. Untar the sources and cd into native: tar xvzf tomcat-connectors-1.2.30-src.tar.gz; cd tomcat-connectors-1.2.30-src/native
    3. Compile and install mod_jk (as root):
      CFLAGS="-O2 -g -Wall -fno-strict-aliasing" ./configure --with-apxs=/usr/sbin/apxs --disable-trace --enable-flock
      make
      sudo make install
      
  2. Restart Apache (as root): /etc/init.d/httpd restart

Step 3. Upgrade Variations clients from 5.0.* to 6.0

Now that the 6.0 server is up, the next task is to transition all users to 6.0 clients. Ideally, this should be done by creating a new Variations installer based on a Variations 6.0 client Windows zip or Mac tar. Note the old digitizer clients will NOT work with the new server and cataloging should not be done on the old production server. Both digitizer and end-user 6.0 clients will connect to the EXAMPLE server. This means that new content will not be copied back to the old EXAMPLE_PRODUCTION server.

  1. Download and unzip (or untar) the 6.0 client distribution
  2. Merge configuration files you modified for your 6.0 client. See Configuring the Client - 6.0 for a list of client configuration files. See Windows Client Changes and Mac Client Changes below for files that have changed in 6.0 and should be merged with 5.0.* copies.
  3. Follow the directions in Building the Client Installer - 6.0

Step 4. (When Ready) Decommission 5.0.* Server and Clean Up Server Installation

Now that 6.0 end-user clients have been distributed, plan to shut down the old production server, using libapp.sh or libapp-passwordless.sh instead of stopVariations.sh.

/home/dmlserv/bin/libapp-passwordless.sh stop EXAMPLE_PRODUCTION

It is possible to notify users of the need to upgrade by adding a message after each 5.0 version in /home/dmlserv/conf/server/versions/EXAMPLE_PRODUCTION.versions. For example, "5.0: This server will be retired on 6/1/2010. Please upgrade to Variations 6.0."

Post-Install Cleanup

Once the transition has been made to the Variations 6.0 server and the Variations 5.0.* server has been turned off, the following steps should be taken to cleanup dmlserv's home directory. This will avoid confusion and avoid running the wrong version of scripts or the Variations server.

Make a backup of dmlserv's home directory before running the following commands.

# Remove all files from the Variations 5.0.* installation that are not used by Variations 6.0:
rm -r /home/dmlserv/bin /home/dmlserv/conf /home/dmlserv/COPYING /home/dmlserv/data /home/dmlserv/lib /home/dmlserv/public_html /home/dmlserv/server.jar /home/dmlserv/VERSION

You can also make the following change to endPort in the new dmlserver.xml in /home/dmlserv/Variations-6.0/conf/server:

  <RMIServerPorts startPort="49930" endPort="49931">
  </RMIServerPorts>

as the additional port (49932) will no longer be needed after the 5.0.* server is decommissioned. The change will be picked up at the next server restart.

Server Changes

File

Change

~/VERSION

Changed from 5.0.7 to 6.0

~/data/ServerLegalNotices.txt, ~/data/legal_notices.html

Changed from 5.0.7 to 6.0

~/server.jar

MySQL 5 compatibility, reduction to single library server, LDAP authentication support, bug fixes and other changes:
See Variations Release 6.0 for more information.

Windows Client Changes

File

Change

Program Files/Variations/Client/readme.rtf

Added version 6.0 to Revision History

Program Files/Variations/Client/VERSION

Changed from 5.0.7 to 6.0

Program Files/Variations/Client/data/legal_notices.html

Changed from 5.0.7 to 6.0

Program Files/Variations/JRE

Updated bundled JRE to 1.6.0_18

Program Files/Variations/Client/client.jar

Replaced end-user search window with welcome window, client-server changes to handle server improvements, and bug fixes.
See Variations Release 6.0 for more information.

Mac Client Changes

File

Change

Variations.app/Contents/Info.plist

Bumped version number to 6.0

Variations.app/Contents/Resources/Java/VERSION

Changed from 5.0.7 to 6.0

Variations.app/Contents/Resources/Java/client.jar

Replaced end-user search window with welcome window, client-server changes to handle server improvements, and bug fixes.
See Variations Release 6.0 for more information.

Variations.app/Contents/Resources/Java/data/legal_notices.html

Changed from 5.0.7 to 6.0

Variations.app/Contents/Resources/English.lproj/InfoPlist.strings

Bumped version number to 6.0

Terms-of-Use.html

Changed from 5.0.7 to 6.0

Configuration Changes

Added Configuration

  • dmlserver.xml
    • Added Z39.50 system properties for passing to clients: dml.z3950.Container.field.id.label, dml.z3950.Container.field.id.example
    • Added welcome window url system properties (VARIATIONS-12): dml.client.disableSearch, dml.client.url.welcome
    • Made max database connections configurable (VARIATIONS-37) using Option tag under ExtraOptions under SQLRepository and UserProfileManager tags
  • dmlscript.conf
    • dml.server.webui.url.quicktime: Link to download Quicktime to be added to the access page if web player is enabled
    • dml.xslt.access.dramurl: Link to DRAM to be added to access page if DRAM support is enabled and container is DRAM-supplied
  • dml.conf
    • dml.login.adminMode, dml.login.digitizerMode: Added commented out to all dml.conf due to unified digitizer and end-user dml.conf files
    • dml.z3950.Container.field.*: Added all dml.conf due to unified digitizer and end-user dml.conf files

Removed Configuration

  • dml.conf
    • dml.login.protocol: Removed with move to realm based authentication instead of protocol based
    • dml.login.adminMode, dml.login.digitizerMode: Commented out in dml.conf due to unified digitizer and end-user dml.conf files
    • dml.z3950.Contributor.*, dml.z3950.Work.*, dml.z3950.Container.enabled, dml.z3950.Container.host, dml.z3950.Container.port, dml.z3950.Container.database, dml.z3950.Container.field.id.name, dml.z3950.Container.field.id.label, dml.z3950.Container.field.id.example: Server-supplied and removed generally unused properties
  • No labels