UpgradingtoRelease8

Getting the Release 8 package

Firstly, fetch the release 8 package from the ANDS Online Services GitHub tags page. Releases are tagged for your convenience and GitHub provides a simple method for you to download these tags as either a ZIP file or Tarball.

Example:

cd ~   ## execute this from your home directory
wget https://github.com/au-research/ANDS-Online-Services/tarball/release8
tar zxf release8

This will create a new directory call au-research-ANDS-Online-Services-<some git revision code>.

Rebuilding and Updating the Harvester

There have been several minor changes to the Harvester between release7 and release8. This requires the Harvester software component to be rebuilt. Note that the Harvester requires the Tomcat servlet library (by default, this is included in your tomcat installation's lib directory).

Example:

cd au-research-ANDS-Online-Services-*
cd harvester
ant -lib /usr/share/tomcat6/lib/ build_wars 
cp build/harvester.war /var/lib/tomcat6/webapps/
rm -rf /var/lib/tomcat6/webapps/harvester/
service tomcat6 restart

Thats it!

Updating the SOLR Indexer schema

Grab the latest SOLR Index schema from ANDS-Online-Services/wiki/SOLRSchemaLatest and overwrite your current SOLR schema.

Example:

cd /usr/local/solr36/solr/solr/conf/
mv schema.xml schema.xml.bck
wget https://raw.github.com/au-research/ANDS-Online-Services/25edde3ea02ee84003d89275cea044aef68150da/registry/lib/solr_schema/schema.xml
service tomcat6 restart

Add the Gearman Background Daemon and Task Worker(s)

ANDS Online Services now requires a background task daemon to run regular registry maintenance tasks and execute large tasks in the background soas not to disrupt the user. More information and instructions on installation are available at ANDS-Online-Services/wiki/BackgroundTasks.

Setting up Gearman Daemon:

yum install gearmand 
service gearmand start
chkconfig --level 5 gearmand on 
yum install php-pecl-gearman
service httpd restart

Now create the ANDS task workers directory (and allow the apache user to access it):

cd ~/au-research-ANDS-Online-Services-*/
mkdir /var/www/tasks
cp -r taskmgr/* /var/www/tasks
chown -R apache.apache /var/www/tasks

Add the regular trigger service (Gearman doesn't support future-dated tasks, so this emulates it):

crontab -u apache -e 
# Add the following line:
*/5 * * * * php -f /var/www/tasks/bin/trigger_cron.php 

Note that this cron will fail a few times until we properly configure the release (see below).

Finally, (optionally) install the ANDS Task Manager service (which allows you to manage the task workers using service commands):

cp taskmgr/bin/andstaskmgr /etc/init.d/

# Edit the /etc/init.d/andstaskmgr file and modify the line to point to where your tasks are installed
PROG_PATH="/var/www/tasks"

chkconfig --add andstaskmgr
chkconfig andstaskmgr on
service andstaskmgr start

Update the Website Files

As part of the new SEO-friendly URLs the software is no longer required to be in a subdirectory (such as /home/) in order to be uniquely distinguished on the system.

Copy the registry/src/ folder to the appropriate area of your web server's root. Then copy the required libraries to their appropriate locations. Example:

# Copy the bulk of the web files
cp -R registry/src/* /var/www/html/

# Copy the required libraries
cp -R registry/lib/ckeditor/ /var/www/html/
cp -R registry/lib/htmlpurifier/ /var/www/html/orca/
# And fix the permissions of the HTMLPurifier cache
chmod -R 0777 /var/www/html/orca/htmlpurifier/library/HTMLPurifier/DefinitionCache/

We will come back to configuring these files shortly.

Setup the ORCA cache space

The XML Storage layer now provides a flat-file cache for records in their native format (usually RIFCS/XML).

Simply create a directory which is writeable by the apache user. This can be outside the web root. Example:

mkdir /var/www/orca_cache
chown apache.apache /var/www/orca_cache

Update the Database schema

ANDS provides incremental database upgrade scripts between minor versions. You must run each of these successively in order to progress the database to release 8. These scripts are located in the registry/db/ folder.

For example, if your current version is Release7.1, you should run the release7.1_to_7.2_incremental/ scripts, followed by release7.2_to_r8_incremental/. If there is no directory for the release version, this means that no database changes are necessary (similarly, if there is only a "ORCA" upgrade script, but no "COSI" script, no changes are necessary for your COSI database).

Example (upgrading from Release 7):

sudo su -c psql postgres

postgres=# \c dbs_cosi 
dbs_cosi=# \i registry/db/release7_to_7.1_incremental/dbs_cosi_r7_to_r7.1.sql
dbs_cosi=# \i registry/db/release7.2_to_r8_incremental/dbs_cosi_r7.2_to_r8.sql

postgres=# \c dbs_orca
dbs_orca=# \i registry/db/release7_to_7.1_incremental/dbs_orca_r7_to_r7.1.sql
dbs_orca=# \i registry/db/release7.1_to_7.2_incremental/dbs_orca_r7.1_to_r7.2.sql
dbs_orca=# \i registry/db/release7.2_to_r8_incremental/dbs_orca_r7.2_to_r8.sql
dbs_orca=# \q

Thats the setup done. Now just a few final steps to configure your new environment!

Configuration

Configuring global_config.php

It is recommended that when upgrading to a major release (i.e. Release 8), the software should be reconfigured from scratch. In releases prior to R7.1, configuration variables were contained throughout various areas of the software making this a necessary step for any users migrating to Release 8 from affected versions.

The latest version of the global configuration is contained in global_config.sample. Advanced users and users upgrading between minor versions may wish to simply compare their global config for differences using a tool such as comm. Alternatively, users can copy the config file and configure it using a text editor. More information at ANDS-Online-Services/wiki/GlobalConfiguration.

Example:

cd /var/www/html/
cp global_config.sample global_config.php
nano global_config.php
# ^^^ Make various configuration changes
mv orca/rda/sample.htaccess orca/rda/.htaccess
nano orca/rda/.htaccess
# ^^^ modify the RewriteBase to match your environment

Configuring the Task Workers

Now update the task workers to point to your installation directory:

nano /var/www/tasks/init.php
# ^^^ modify the application base to point to the root of your installation (where global_config is!)
# i.e. $APPLICATION_BASE = "/var/www/html/";
service andstaskmgr restart  

Running the maintenance tasks for the first time

Login as a COSI Admin, go to the new "Background Task Manager" (in the Administration menu), click "Trigger worker".

Wait for the background processes to run (can take some time -- up to 2 hours for the entire ANDS registry).