Forum OpenACS Q&A: Upgrading packages

Request notifications

Posted by Reuven Lerner on
I've installed the 4.5 release version of OpenACS, and it is (as
expected) quite excellent.  But there are obviously still some bugs,
and it's already clear that a number of modules are going to be
updated in the near future.

That's all well and good, and APMs make it pretty easy to upgrade one
or more applications to a newer version.  My question is how to
customize the design of one or more .adp pages in an APM such that
upgrading the package won't blow away

In other words: I customize the .adp pages for bboard to my client's
satisfaction.  Perhaps I even customize the .tcl pages.  A new version
of bboard comes out.  If I install the APM, do I destroy my
modifications?  Or is APM smart enough (sort of like RPM on Red Hat
and similar Linux versions) not to touch files that have been modified?

If APM isn't this smart, then how do I handle package upgrades?

Posted by Ola Hansson on
APM isn't this smart, but CVS is!

APM is smart when it comes to datamodel changes, though. At least when a proper upgrade script is provided.

These are the steps I take for the moment, when dealing whith the things that you ask about.

  1. checkout a "master copy" of the desired branch of OpenACS from to your hard drive and never edit this code
  2. initialize a local repository on your hard drive
  3. import the above copy to the local repository
  4. checkout one or two or three "working copies" from the local repository (I use two; one with the development server pointed to it and the other with the production server pointing to it)
  5. do your customer-specific changes to the dev copy, and when satisfied with the result, cvs add and/or commit the files.
  6. cd to the production copy and cvs update the files

    Along comes a new version of the bboard package, for instance...

  7. cvs update the "master copy" to incorporate the new bboard code
  8. once again import the (now updated) "master copy" to your existing local repository. This will, in effect, update your repository to the latest standards without destroying your modifications to the code. (cvs might ask you to merge the changes but will tell you how to do it! You might also have to resolve any possible clashes.)
  9. update the development copy and, when you're happy with the result, the production copy.

Now, if you go to the package manager and click on the "Install packages" link you should find a link promting you to upgrade the package in question. IF any data model changes was made to it, that is.

This is just the way *I* do things which is not to say it's the best apporach...but I hope it helps. Hopefully someone else will chime in and correct me where I'm wrong.

Posted by Andrew Piskorski on
Reuven, yes, Ola is right in that CVS is the only mechanism OpenACS has to do what you want. And while it does require some extra work on your part (unlike say, the way rpms can be told to "leave modified files unchanged"), it actually gives you a complete solution, and for anybody who was able to customize the ADP and TCL pages in the first place, the extra CVS work should be no big deal.

I agree with Ola that in some fashion, you always want to import a copy of the OpenACS code onto a vendor branch in your local "my private OpenACS fork" CVS repository, and merge your customizations and resolve conflicts there. (You probably also want to be careful to always import a tagged version of OpenACS, e.g. oacs-4-5-rc-1, not just the untagged tip of the development trunk.) And you'll also want at least one separate checkout directly from the OpenACS CVS repository, so you can conveniently do cvs log and the like against the OpenACS repository, and otherwise check what's going on in the development sources.

FYI, it's been way too long since I last updated them with new stuff I've learned or found usefull, but my Version Control docs on go into many of the CVS issures mentioned above.

Posted by Ola Hansson on
A question I've been asking myself on a number of occasions is the following:

Which is the best approach if you have multiple projects (sites) that are being developed and/or run on one box, with the projects both wanting to share a lot of changes/bugfixes to the original code, and, at the same time, wanting to run individual custom made code?

For example: At the moment I have two sites that run separate instances of OpenACS 4.5b. I imported the same codebase twice into two separate repositories.

This isn't very practical as I have to copy code from one dev checkout to the other, or deal with patching...

OTOH it is nice when I want to separate the code from the projects, and it's very simple.

But, probably 99 percent of the code is identical.

So, would it be workable to let several projects share one repository using branches or some such?

If so, can anyone briefly describe such a solution?

Posted by Kevin Murphy on

Right on.  I have never used CVS before, but your (very old) message inspired me to start.  CVS is kind of mysterious and annoying-looking to the uninitiated, but it turns out that it doesn't take long to learn the basics.

For the benefit of other CVS novices, I was able to undertand most of the OpenACS references to CVS after a couple hours of reading the following:
2) man cvs
3) Snippets from

In the process of translating Ola's e-mail into actual cvs commands, I documented what I was doing, and I came up with the following, which is almost, but not quite, a runnable script (it assumes the existence of a user nsadmin and group web, for instance).

-Kevin Murphy

# First off, CVS can be used several ways in the context of OpenACS.

# 1) Obtaining OpenACS in a one-time shot.  If this is all you use cvs for,
# you might as well just download the tarball.

# 2) #1 plus a convenient way of applying openacs updates to your local
# copy.  If you use it for this, it's probably worth it.
# The main reason why this is superior to downloading another
# tarball and untarring it on top of your site is that ... you'd
# be crazy to do the latter, especially if you had modified any
# openacs core or package files.  cvs lets you do _merges_ that you
# control (but don't do this directly on a live site!)

# 3) #1 plus #2 plus a way of backing up and maintaining your local
# site files and any changes you might make to the core openacs files.
# Now we're talking.

# 4) All the above plus a way of maintaining both a "development" and
# "production" version of your local site while retaining the ability
# to merge in updates of OpenACS.  Feel the excitement!

# 5) Someday ... be an OpenACS developer with commit rights on the
# openacs repository.  For this, using cvs is a requirement!  In the
# meantime, report any bugs and your fixes to


# The rest of this peudo-script has the peculiar feature that comments FOLLOW the command.


export MY_PROJ=med

# Create an environment variable to hold your base web site/project
# name.  This will be used later in the script.

su nsadmin

# The user who owns and runs aolserver

cd /tmp

# or wherever

cvs -z3 -d co -r oacs-4-6 acs-core

# Checkout the openacs core into /tmp/openacs-4
# -z3 means use compression level 3
# -d specifies the repository location
# co is a synonym for checkout
# -r oacs-4-6 is a version (release) tag
# acs-core is the name of the cvs module/project you want to checkout

cvs -d $HOME/cvsroot init

# You may not want to do this in nsadmin's $HOME if it is /usr/local/aolserver.
# If so, temporarily override $HOME in this script.
# Create a local cvs repository in nsadmin's home directory
# -d $HOME/cvsroot specifies the repository location

cd /tmp/openacs-4

cvs -d $HOME/cvsroot import -m "Creating initial local master repository of OpenACS 4.6." openacs-4 nsadmin initial

# Move the openacs-4 distribution into a master copy in your own local
# cvs repository.  This master copy will be a backup of your
# development and production sites and help you manage your site
# development.  As you build your site, your master copy will diverge
# from the original 4.6 distribution, mainly by the addition of your
# own files and changes to configuration files.  If you find bugs in
# the OpenACS code, you can of course make fixes by editing the
# original files.
# *) "-d $HOME/cvsroot" specifies the location of your local
# repository for nsadmin.
# *) import means to recursively check in the contents of the
# current directory.
# *) -m "..." is the log message.
# *) openacs-4 is the name of the module/project to create in the
# repository.
# *) nsadmin is the "vendor tag".
# *) initial is a "release tag" which will allow you to distinguish
# between the initial set of files and a later configuration.

find $HOME/cvsroot/openacs-4 | less

# Verify what you've done

sudo mkdir -p /web
sudo chown nsadmin:web /web
cd /web

# /web is where you want your openacs projects to live.
# They don't actually all have to be in the same place, of course.

cvs -d $HOME/cvsroot checkout openacs-4
mv openacs-4 $MYPROJ-dev

# Check out an initial "development" version from your local
# repository.  I repeat: you are not checking out from but
# from your local master copy.  As you make changes to the dev site,
# you can commit those changes to your local repository.  When you are
# ready to go live, you can update the production site based on the
# changes.

cvs -d $HOME/cvsroot checkout openacs-4
mv openacs-4 $MYPROJ-prod

# Check out an initial "production" version from your local
# repository.  Whenever you are ready to update your production site,
# do an update

export CVSROOT=$HOME/cvsroot
cat >>$HOME/.profile <<EOF
export CVSROOT=$HOME/cvsroot

# Set the CVSROOT environment variable to use the local repository as
# the default.  From now on, you can skip the -d clause in cvs
# commands as long as you are making changes to your local repository
# or site directories.  Whenever you do commands against the openacs
# cvs server, e.g. check for updates, you will have to take care to do
# them in your master repository directory ($HOME/cvsroot/openacs-4)
# and specify the "-d" clause
# to override the CVSROOT environment variable.