Upgrading Packages

 

Every so often you are in need to upgrade your packages to keep up with the latest developments. To do this, certain guidelines need to be followed and you should be aware of consequences of your actions. This is what this document is trying to achieve.

Backup and Testing 

It cannot be stressed enough. Before you do any upgrade work, make a backup of your site. This is a full backup. Once that is done, create a test site against which to test the upgrade based on the full upgrade that you just made. You can use [ OpenACS Setup guide ] to help you do this. Just make sure you import the dumpfile done in the backup and do not create the site from scratch.

Once you have your test site running, apply the product update. For the sake of the argument we assume that you have your website running off a versioning system (syntax for subversion provided), this makes it much easier for us. Here is how to do this:

  • Download the product release in a separate directory.
  • Delete all CVS / SVN /VSS (you name it) folders that are used for versioning so it does not interfere.
  • Make sure you have an up to date checkout from subversion on your test site. 
    cd /web/testing
svn update
svn status ; # this is done to see if you have changed files not yet committed
svn commit ; # Commit your local changes BEFORE continuing
  • Then copy the files from the product over 
    cp -pr /web/product/* /web/testing
  • Once done, make a check what has changed 
    cd /web/testing
svn diff |less
  • If there are any changes where code was removed that you have put in originally, read [ Customize existing packages ] , reapply your work in a proper fashion and come back here.
  • Now your system is ready for testing the upgrade. Go to http://yoursite/acs-admin/apm/ and run the install process. 
  • If there have been errors, try to fix them. Here are some scenarios and solutions:

Failures in Upgrade

  • Error in an .SQL file.
    • Fix the .sql file in package_directory/sql/postgresql/upgrade. 
    • Run the sql_file in "psql" manually
    • Go to /acs-admin/apm/install-packages and reselect the package for upgrade
    • Uncheck all .SQL files before and including the fixed file (so if you fixed upgrade-1.2.2d5-1.2.2d6.sql then do not execute it, and all files before it like upgrade-1.2.2d4-1.2.2d5.sql
  • Error in a parameter creation
    • Fix the parameter definition
    • Increase the version number of the package
    • Rerun the upgrade
  • Error during localization
    • Fix the locale
    • go to /acs-admin/apm/, click on the package, click on internatioalization and load the catalog files from the file system.
  • Error during TCL callbacks (you will see that in the error log)
    • Find out which upgrade failed
    • Fix that upgrade
    • go to /ds/shell (the developer support shell)
    • Run the upgrade in the developer support shell. Do this until you get it right :-)
    • Copy the code from the other upgrades that come *after* the failed manually to the developer support shell
  • Too complicated, get me out of here:
    • Fix the problem
    • Stop your webservice
    • Delete your *testing* database
    • Create your *testing* database
    • Load the dumpfile (see backup) into your testing database
    • Start your webservice
    • Rerun the whole upgrade process.
  • Too much effort, I have a fairly broken upgrade package and don't want to run the whole scripts over and over again
    • Upgrade all packages but the broken package
    • Make a new dump from the testing site
    • Follow the steps mentioned under "too complicated" but use the testing dump and only upgrade and fix the broken package

 

  • As you might have noted, the "Too complicated" scenario works great if you do not have too much data. It is a different story if your dumpfile is 4GB large. 

 

Upgrade layout and other customizations

The last step to do in your upgrade process is to make sure that nothing has changed in product which might have an impact on you. Therefore you should take a look at all your customizations in /packages/service_name/ {lib|templates|resources|www/resources} and see if anything new has come up from product. You can do this by comparing the "diff" between the file you copied over (see [ custom-package ] ) and the one in use.

This last step is usually not necessary when you do minor version upgrades, but you should revisit this step every now and then, just to be on the save side.

To save you some time, you can also do an svn status to figure out if the original file has changed:

cd /web/testing/packages
svn status acs-subsite acs-templating acs-tcl

If a file shows up as modified, then you should take a look, otherwise don't.

Final test and production upgrade

Once you are done with the upgrade on testing you are nearly there.

  • Make a dump of your production environment and import it into testing
  • Run the upgrade against this dump
  • Assuming success, commit your changes to the repository 
    cd /web/testing
svn commit -m "Upgrade of product to version X" (remember the SVN release version, eg. 333)
  • Shut down your production site
  • Make a dumpfile and keep it in a save place
  • Get the latest code 
    cd /web/production
svn status ;# Make sure NO FILE HAS CHANGED!
svn update -r 333 ;# The 333 being the release version of the commit above
  • Bring up your production site on a secret port (so you can access it) 
  • Run the upgrade. No errors should happen. 
  • Once the upgrade is finished, restart the site on the original production port

If you are nice to your users you should setup a "down" site on the original port while working on the upgrade. This will tell users that your site is down and you can communicate the status to them.