Forum OpenACS Q&A: Proper package upgrade method

Posted by Ryan Gallimore on 05/20/06 12:54 PM

Ok, so I have a version of xowiki on my system with hundreds of pages, categories etc. Gustaf releases the newest version of xowiki and I know I must upgrade.

But how do I retain all my pages? Will the drop script blow away my precious wikis?

What is the proper way to upgrade packages? I've had success with the following:

1. Unmount and delete all instances. (Delete site nodes).
2. Delete the package from APM. (Remove the apm_package rows and run the drop script)
3. Download the new version via CVS.
4. From the APM 'Install Software' and install your new package.

If all goes well, we're done... except that my hundreds of wiki pages are gone!

Can anyone shed some light on this?

Thanks.

2: Re: Proper package upgrade method (response to 1)

Posted by Gustaf Neumann on 05/20/06 01:46 PM

First of all, the versions in CVS head are not supposed to work, this a merely an exchange area for developers (aka kitchen sink).

The versions which are supposed to work are releases, or versions close to releases (e.g. in CVS oacs-5-2)

In general, there is no need to unmount etc. the packages.
what i do is rougly the following:
once:
a) get a full tree of oacs from HEAD
b) get a full tree of oacs-5-2

then decide, what you want to use from where.
i have a tree, where everything is from oacs-5-2, only xowiki is a link to the HEAD version.

in order to updgrade, you

1) do in the approproate package a cvs .... update
2) do acs-admin/apm/ a "Install packages" and click on the updgrades

and you are done.

-gustaf

PS: xowiki has a import/export facility, such you can export all your pages to a ascii file and import these afterwards again, also in a different installation. currently, one uses the category associations, since one cannot export the category trees and their associations, but the export is certainly helping here.

PPS: The full-release circles or CVS updates are IMHO not the right tool for a someone starting with oacs, or someone trying new packages to proceed. the idea of the .apm files was addressing this problem, but these are not very popular (not used?)

3: Re: Proper package upgrade method (response to 1)

Posted by Dave Bauer on 05/20/06 02:30 PM

OpenACS has a reasonably reliable upgrade system for released packages.

You can visit /acs-admin/install for the friendly installer, or /acs-admin/apm/packages-install for the developer's installer which let's who choose which SQL scripts to run and override dependencies etc.

Every package is supposed to inclde upgrade scripts that will take your existing packgae version and update it to the new version.

Of course, always backup your database before you do this, because you never know :) One of the steps of the release process for OpenACS requires testing of upgrades, but it is impossible to test every combination of packages and custom code, so it is a good idea to test upgrades on a staging server before updating your production system.

If you maintain a local CVS repository there is a recommended technique to merge the new OpenACS code into your repository https://openacs.org/doc/openacs-5-2/upgrade-openacs-files.html

That also documents getting new code if you site is not in CVS.

More options are documented here https://openacs.org/doc/openacs-5-2/upgrade-5-0-dot.html

4: Proper package upgrade and deleting methods (response to 3)

Posted by Ryan Gallimore on 05/20/06 02:46 PM

Thanks, daveb. Very helpful.

Must you delete an older package before upgrading? Do upgrade scripts respect existing data?

And on a related note: I understand the best way to remove a package instance from a subsite is to unmount it and then delete it. Doing this before deleting an application from the APM is a must.

1. Why doesn't the APM on uninstalling a package, unmount all instances? Actually, I think XoWiki does do this, but it's the only example I've seen.

2. Are there any standards for package creation, deployment, and upgrade support?

3. Can we remove the little trash can delete buttons from the Applications admin tab, as they almost never work, or include the code from the unmount/delete site node process in that functionality?

Cheers.

5: Re: Proper package upgrade and deleting methods (response to 4)

Posted by Dave Bauer on 05/20/06 03:01 PM

No upgrading means you don't have to delete anything. All your existing data will stay where it is. (But backup first, of course.)

Uninstall of packages just hasn't seen as much attention as installing. Basically on the real systems most OpenACS developers work on, packages aren't deleted so its not a huge issue.

On experimental systems, I just reinstall. It doesn't take that long.

There _is_ a way to have all packages uninstall/delete themselves cleanly. Every package may implement an unmount/delete instance/uninstall package callback that runs custom code for each package when these events occur.

Not all packages have been updated to use these callbacks for uninstall type events yet. In general, as I said, most sites do not require deleting of data, so this area is neglected.