Forum OpenACS Q&A: Upgrading a heavily modified site

Posted by Randy Ferrer on
I have a heavily modified OACS installation that I need to upgrade from 4.6.2 to 4.6.3. While I have all my changes carefully documented and the installation is under CVS control, I am not sure how to go about upgrading in the least painful manner. I am especially concerned about the future upgrade to 5.0. While upgrades from "stock" installations is a snap, modifying OACS seems to quickly lead one away from this "upgrade nirvana". If there is anyone out there that has experience doing OACS upgrades on heavily modified sites that can share some practical knowledge, it would be much appreciated. Thanks!!
Posted by Dave Bauer on

Have you changed the data model of any OpenACS package? If so you will need to reconcile your changes to any upgrades made to the data models in the newer version of OpenACS.

The procedure is basically this:

0) Make a backup of your database to test with.

1) Import latest OpenACS code onto a vendor branch.

2) Checkout a working copy of your web site into a staging directory.

3) cvs update your staging directory with the vendor branch you previously imported.

4) Resolve conflicts, this is the fun part. You really just have to look and make a decision here.

5) If there are data model upgrade scripts for acs-kernel. Run them through psql or sqlplus manually. This might not be an absolute requirement, but it doesn't hurt.

6) Start your staging service, go to the APM and upgrade any packages using the installer. When the installer offers to upgrade acs-kenerl, uncheck the box to load the sql file, as you have already installed that.

At any point, look out for error messages. If you have a sql file that doesn't load you will probably need to revert your database back to the previous step and resolve the problem before.

If you haven't made any changes to the packages data model and only made changes to tcl/adp templates and possibly added your own packages, this process should work fairly smoothly.

If anyone else has any comments or changes to this process please let me know.

Posted by Jeff Davis on
I have a couple of comments to add to what Dave mentioned. The first is that you should have the original reference code (4.6.2 in your case) and the new version both in there and to merge via something like
cvs update -j oacs-4-6-2 -j oacs-4-6-3 
It really should not be too bad, I merged the changes from 4.6.0-4.6.3 into HEAD (which I guess could be thought of as a heavily modified 4.6.0) and it was only 2 or 3 days work.

Another quicky solution is to diff the two distributions (diff -urN and exclude the CVS ids), apply the changes with patch and then check through the rejected patches. The advatage of this is you can more quickly discard changes to .adp files which are locally modified (which is sometimes a big source of conflicts in trying to merge).

Posted by Jade Rubick on
We really need a definitive document on how to do this.
Posted by Peter Marklund on
For what it's worth, here are some notes I took to be able to reproduce the upgrade that I did of

*** Doing the CVS Merge

- Checkout acs-core plus the packages acs-events, acs-datetime, acs-developer-support and any other
packages needed by planet:

cvs -d checkout -r oacs-4-6 acs-core
  cd openacs-4/packages
  cvs -d checkout -r oacs-4-6 acs-datetime acs-events acs-developer-support

- Import the checked out sources to a new release tag on the vendor branch (example date is the 13:th of May 2003):

  cd openacs-4
  cvs import -b 1.1.2 -m "importing openacs-4-6" planet openacs-vendor-branch openacs-4-6-2003-05-13

- Now enter a clean checkout of planet on the CVS head and merge against the new release branch (release-tag-of-last-m\
erge could be for example openacs-4-6-2003-05-12):

  cvs update -kk -j  -j openacs-4-6-2003-05-13 -P

- Resolve any resulting conflicts

*** Testing Planet with the new Sources

- Make sure first that you have a dump file of the not upgraded planet database so that you can re-do the upgrade.

- Stop the server and start with a clean error log file. Start the server again and grep for all error messages.

- Remember that many of the procs in acs-tcl are overridden by procs in gp-tcl.

- Resolve enough errors to be able to use the package manager (/acs-admin/apm). Now upgrade the packages one at a time\
 starting with the core packages. You need to figure out which upgrade scripts to run as the APM has a history of some\
times suggesting running too early upgrade scripts that you then need to deselect.

- After each upgraded package you need to restart the server and watch for error messages. Some error messages may ste\
m from the fact that not all packages are upgraded yet and can be ignored.

- When you are done, test the site and watch for error messages. If there are issues you may need to upgrade again.
Posted by Eric Wolfram on
I also could benefit from more docs on this, for your information. Of course, I really appreciate the details in this thread already, as a step by step, and I am only chiming in here to caution that I fear you see in me more mentality in me then I currently posses. I'm a total n00b (newbie) compared to many of the great people in this community and it's difficult to overstate the canyon of difference between what you understand and what I understand.

For instance, I'm unsure if I changed my data model, as you put it above, and so am I to assume that if I don't know if I changed it then I probably didn't? Bare with me, I only first got my site going in March and I don't have a CS degree or anything

LOL, seriously, in spite of my inexperience with unix, I did manage to get CVS set up and a site going, check it out:

If I ever attempted to merge my 4.6.1 installation with your upgrades, the type of detail that I would find re-assuring would be a cleaned up emacs shell log of the entire process interspersed with these great step by steps above. The problem is: Your CVS diff command output, would be differ then the output of my CVS diff commands, but I am interested in how others modify their openACS systems so I'm still interested. Plus, seeing you merge your things gives me an idea how to merge my things.

Still, if someone took a log of their upgrade process and added a little commentary about the output, here and there, that could be very helpful for someone like me who is trying to understand.  I guess that would be one LONG log -- but it might be very reassuring to someone who wanted to understand the exact process.

BTW, I've started using emacs commands for CVS. For instance: C-x v i

That adds a new file. I wonder if you use them to merge or do you just type CVS in the command line? Do you merge in three buffers or two? Docs like that could help too -- how to set up emacs if you have a special way of viewing diffs?

Posted by Don Baccus on
Eric - your site looks quite impressive for a first site built by an OpenACS newbie!

One problem I noticed, though - the "edit this page" link shows up for me even though I'm not logged in.  I doubt you want random people editing your home page??? :)

Looks to me as though your OpenACS permissions on that page are too permissive.

You are correct about the datamodel, if you didn't change the code in packages/foo/sql/oracle or postgresql then you didn't change the datamodel.  And I would assume you'd know if you had.

Posted by Eric Wolfram on
Thanks Don, for noticing that I had given write permissions to public users on the root, which made the "edit this page" link appear for everyone -- d'oh.

And, more importantly, thank you for not changing my pages. Thanks for the encouragement about my site being good for a n00b, and as you know, I am on the shoulder of giants (namely, you openACS people and the rest of gnu...)

As an aside, in an attempt to remove the edit this page from my root, I inadvertently joined the "removed public read permissions from the root" club, and for reasons that were only obvious after I pressed submit, one shouldn't join that club. Searching the forums for "revoked privileges" found the right doc to fix it -- evidently, I'm not the only one in the club.

You have no idea how stressful it is for me to start messing with the database...but it sure feels good to have fixed it...and now I'm ready for the next...

Posted by Andrew Grumet on
In addition to the great answers above, you may find the following document helpful: (recently brought over from the old sdm site to by Carl B.). Don't let the dotLRN part of the title throw you off. It's really about using CVS vendor branches and merging.
Posted by Randy Ferrer on

Hi - Thanks so much for the fantastic answers! I have printed all this and will look into doing the upgrade in the next few days.

If I manage to put together clean docs, I'll post it to hopefully make it easier for others to do this. I do agree with Jade that we need a doc for this, I just don't know about "definitive" since there are so many different types of sits. out there. One thing is sure - it should be easy to come up with a set of installation recommendations to make upgrades easier and then base upgrade procedures on those. For example, CVS or more generally, version control is a "must" to make this a sane process...

Posted by Joel Aufrecht on
Here are the current Upgrade instructions.

Eric, try doing a full backup and restore (steps 1 and 8). Once you are comfortable that you can safely get back to your starting point in less than ten minutes no matter how badly you scrambled your current install, a lot the stress associated with changing the database may melt away.

Everybody else:

  • did you see the upgrade instructions? if not how can we make them more visible?
  • What's missing from the upgrade instructions? Let's capture all these good notes.
  • Could someone doing an upgrade present some kind of capture that we could all look at to see how helpful/reassuring it is?
Posted by Eric Wolfram on
Thanks Joel for posting those 4.5 --> 4.6 docs, they gave me enough confidence to try. Here are some examples of the issues I had, which will go to show you what type of bonehead you're up against when trying to make perfect docs. Maybe this journal of my attempt will help someone...

First I want to back up. I'm following the docs at:

I got stuck right away.

1. Postgresql backup

I had to login as user "postgres" on my machine, not nsadmin. We actually do have a user called "nsadmin" for the web server, so I was confused by those docs because I didn't notice the key at the top -- where nsadmin is defined as "any user" -- so thought you wanted me to log in as that specific user...of course, the database didn't let do anything as that user. When I loged in as the user for the database I was able to run the commnads.

Still, for the pg_dump, I had to go to /user/local/pgsql/bin, where the program pg_dump was, and then I had to put a ./ in front of the pg_dump command to force the path. I guess my paths for that postgres user doesn't point to that bin. It also didn't point to . That is, when I did echo $PATH I didn't see those paths...I don't know how to fix that...

2. File Tree with CVS --

* Running the cvs commit as nsadmin got the following error -- this is because nsadmin never change files or because something in the /CVS directory needs chmod/chgrp.

[nsadmin@rhumba new]$ cvs commit -m "last minute commits before upgrade to 4.6.3"
cvs [commit aborted]: cannot open CVS/Entries.Log: Permission denied
[nsadmin@rhumba new]$ [nsadmin@rhumba new]$

So I logged in as ewolfram and tried the CVS commit and got this:

cvs commit: Examining bin
cvs commit: Examining content-repository-content-files
cvs commit: Examining log
cvs commit: in directory log:
cvs [commit aborted]: there is no version here; do 'cvs checkout' first

I got concerned about the "aborted" in the output -- even though the output in the docs is snipped. CVS is choking on the log. I tried to check out log/  -- didn't work...

[ewolfram@rhumba new]$ cvs checkout log/
cvs checkout: cannot find module `log' - ignored

So I moved the log directory into /tmp, because I didn't want my logs under cvs, and then I tried the CVS commit again. This time, in the midst of a ton of cvs commit: Examining, I got a bunch of:

cvs commit: Examining .
cvs commit: Up-to-date check failed for `index-oracle.xql'
cvs commit: Up-to-date check failed for `index-postgresql.xql'
cvs commit: Up-to-date check failed for `index.tcl'
cvs commit: Up-to-date check failed for `index.xql'

And at the end it said cvs commit aborted!

It turns out that most of these Up-to-date things were files that I deleted but that I never cvs removed. So, one by one, I did a
:cvs remove index.xql

After I did that to all the failed files in a dir, then I did the cvs commit and it finally worked!

Next, I wanted to do the Tag, but the cvs tag command ironically expected the log directory to be in /web/myserver/, when the cvs commit didn't expect it. That's very confusing to me...I'm running the tag command in a directory WITHOUT a log/, and it returns:

T content-repository-content-files/readme.txt
cvs tag: Tagging log
cvs [tag aborted]: could not chdir to log: No such file or directory

Anyway, I'd do an ls and there was NO directory called log/ (I had moved it to the /tmp for the commit command...) So I finally was able to tag everything...I think...gulp...going ahead

Next I'm going to get the tar file of 4.6.3. Since I'm sshed into a machine that is in Texas somewhere (I'm in SF, CA), I don't know how to pop a browser and download the tar from the openacs site. If I had a URL, I could do a wget, but I don' I go to the site, download to my old local windows machine from a web browser, then I upload via ftp to my hosted account, and then I do a wget from the server to my hosting account (there's GOT to be a better way of doing that...) During the wget -- the terminal window starts repeating gibberish, ie:

6^M78% [===========================>        ] 6,712,292    316.07K/s    ETA 00:05^M79% [============================>        ] 6,806,132    317.03K/s    ETA\
00:05^M80% [============================>        ] 6,876,512    316.91K/s    ETA 00:05^M80% [============================>        ] 6,955,172    317.54K/s  \
  ETA 00:05^M81% [=============================>      ] 7,024,172    317.72K/s    ETA 00:04^M82% [=============================>      ] 7,119,392    319.07\
K/s    ETA 00:04^M83% [=============================>      ] 7,192,532    319.36K/s    ETA 00:04^M84% [==============================>      ] 7,256,012    3\
18.99K/s    ETA 00:04^M85% [==============================>      ] 7,326,392    318.84K/s    ETA 00:03^M85% [==============================>      ] 7,387,024\
    318.63K/s    ETA 00:03^M86% [===============================>    ] 7,443,692    318.21K/s    ETA 00:03^M87% [===============================>    ] 7,49\
8,892    317.51K/s    ETA 00:03^M87% [===============================>    ] 7,562,372    317.45K/s    ETA 00:03^M88% [===============================>    ]\
7,625,852    317.37K/s    ETA 00:02^M89% [================================>    ] 7,693,472    317.48K/s    ETA 00:02^M90% [================================>\
    ] 7,736,252    316.53K/s    ETA 00:02^M90% [================================>    ] 7,794,212    316.00K/s    ETA 00:02^M91% [============================\
====>    ] 7,860,452    316.05K/s    ETA 00:02^M92% [=================================>  ] 7,925,312    315.98K/s    ETA 00:02^M93% [=======================\
==========>  ] 8,010,872    316.55K/s    ETA 00:01^M94% [=================================>  ] 8,095,052    317.27K/s    ETA

At the end of the download, the file looks about 8.2 mgb, which is about right, but when I do the tar xvz openacs -- it hangs. It's not unpacking. I repeat the download, same thing...Going to bed now...will report back later...these are just a few of the types of things that we n00bs struggle with every day :-)

Posted by Jade Rubick on
We *really* need to make the openacs download available by wget. Hopefully, someone will eventually step forward to do it :)
Posted by Michael Yoon on
Given that I'm using about 2 of my 40 GB monthly bandwidth, I'd be willing to mirror OpenACS downloads on my server. What do I need to do?
Posted by Jade Rubick on
Michael, that would be awesome.

All that really needs to be done is to go to the openacs documentation page, download the openacs tarball, and put it on your web server in a location that can be reached by http without going through forms. Then send the link to Joel and ask him if he could put it in the documentation.

Posted by Michael Yoon on
Done. The 4.6.3 tarball is now available at:

I've also emailed the link to Joel.

By the way, AOLserver's "fancy" and "simple" directory listing styles appear to be identical on my server. Is that what's expected, or am I screwing something up?

Posted by Jeff Davis on
The request processor hijacks generating directory listings (if aolserver's dir listing is turned on) but generates the same listing regardless of whether fancy or simple is chosen. See rp_html_directory_listing if you want to fix it...
Posted by Michael Yoon on
Thanks for the explanation, Jeff. I think it's best for all parties if I don't attempt to hack on the Request Processor...