| Prev | Chapter�5.�Upgrading | Next |
|---|
OpenACS is distributed as a collection of files, available as one big tarball, via CVS, and via automatic download from within the APM. Upgrades work by first changing the file system (via any of the previous methods), and then using the APM to scan the file system, find upgrade scripts, and execute them. This section describes how to upgrade the file system. Starting with OpenACS 5.0, this section can generally be skipped because the OpenACS APM can directly download new files from the openacs.org repository.
Many OpenACS site developers operate their own CVS repository to keep track of changes from the release OpenACS code. This part describes how to import the latest OpenACS version into your own repository. If you are using CVS, you will unpack the OpenACS 5.1 tarball into a working directory and then import that directory into cvs. If you have changed files in the core packages, cvs will attempt to merge your changes. You may have to manually merge some conflicts. When that's finished, you can update your normal development checkout directory and the new files will appear. If you aren't using CVS, you can unpack the tarball on top of your existing tree, but any customizations you've made to the kernel or core packages will be erased.
Upgrading files for a site which is not in a CVS repository.�Unpack the tarball into a new directory and copy its contents on top of your working directory.
[root root]# su - $OPENACS_SERVICE_NAME +Upgrading the OpenACS files OpenACS is distributed in many different ways: +
- as a collection of files
- as one big tarball
- via CVS
- via automatic download from within the APM + (package manager)
+
Upgrades work by first changing the file system (via any + of the previous methods), and then using the APM to scan the + file system, find upgrade scripts, and execute them. Starting + with OpenACS 5.0, the last method was added, which + automatically changes the file system for you. If you are + using the last method, you can skip this page. This page + describes whether or not you need to be upgrading using this + page or not: + the section called “Upgrading an OpenACS 5.0.0 or greater installation” +
Upgrading files for a site which is not in a CVS repository.�Unpack the tarball into a new directory and copy its + contents on top of your working directory. Or just 'install + software', select remote repository, and upgrade your files + from there.
[root root]# su - $OPENACS_SERVICE_NAME [$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver -[$OPENACS_SERVICE_NAME web]$ tar xzf /tmp/openacs-5-1.tar.gz +[$OPENACS_SERVICE_NAME web]$ tar xzf /var/tmp/openacs-5-1.tar.gz [$OPENACS_SERVICE_NAME web]$ cp -r openacs-5-1/* openacs-4 [$OPENACS_SERVICE_NAME openacs-upgrade]$ exit [root root]# su - $OPENACS_SERVICE_NAME cd /var/lib/aolserver -tar xzf /tmp/openacs-5-1.tgz +tar xzf /var/tmp/openacs-5-1.tgz cp -r openacs-5-1/* openacs-4 exitUpgrading files for a site in a private CVS repository -
Step 1: Import new CVS code.�There are two common ways to get new OpenACS code into your local CVS repository - via tarball or with a working CVS checkout of OpenACS. Both methods work well for starting your local repository; the second method is better for incremental additions or upgrades.
(a): via tarball.�Download a current tarball and unpack the new files into a working directory.
[root root]# su - $OPENACS_SERVICE_NAME -[$OPENACS_SERVICE_NAME aolserver]$ cd /tmp -[$OPENACS_SERVICE_NAME tmp]$ tar xzf openacs-5-1.tar.gz -[$OPENACS_SERVICE_NAME tmp]$ cd openacs-5-1(b): via cvs working checkout.�Create a CVS checkout from OpenACS. The first time you do this, you will need to create the checkout directory. We use one dedicated directory for each branch of OpenACS - if you are using OpenACS 5.0,x, you only need an OpenACS 5.0 branch. The openacs-5-1-compat tag identifies the latest released version of OpenACS 5.1 (ie, 5.1.3 or 5.1.4) and the latest compatible version of each package, including .LRN. Each minor release of OpenACS since 5.0 has this tagging structure. For example, OpenACS 5.1.x has openacs-5-1-compat. - You will want to separately check out all the - packages you are using. -
[root root]# su - $OPENACS_SERVICE_NAME +Many OpenACS site developers operate their own CVS + repository to keep track of local customizations. In this + section, we describe how to upgrade your local CVS repository + with the latest OpenACS version, without overriding your own + local customizations.
This diagram explains the basic idea. However, the + labels are incorrect. Step 1(a) has been removed, and Step + 1(b) should be labelled Step 1.
Step 0: Set up a working CVS checkout.�
To get your OpenACS code into your local CVS + repository, you will set up a working CVS checkout of + OpenACS. When you want to update your site, you'll + update the working CVS checkout, import those changes + into your local CVS checkout, create a temporary CVS + checkout to merge your local changes, fix any + conflicts, commit your changes, and then update your + site. It sounds complicated, but it's not too bad, and + it is the best way to work around CVS's limitations.
This part describes how to set up your working CVS + checkout. Once it is set up, you'll be able to update any + packages using the existing working CVS checkout. We use one + dedicated directory for each branch of OpenACS - if you are + using OpenACS 5.1,x, you will need a 5.1 checkout. That will + be good for 5.1, 5.11, 5.12, and so on. But when you want to + upgrade to OpenACS 5.2, you'll need to check out another + branch.
The openacs-5-1-compat tag identifies the latest released version of OpenACS 5.1 (ie, 5.1.3 or 5.1.4) and the latest compatible version of each package. Each minor release of OpenACS since 5.0 has this tagging structure. For example, OpenACS 5.1.x has openacs-5-1-compat.
You will want to separately check out all the + packages you are using. +
[root root]# su - $OPENACS_SERVICE_NAME [$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver -[$OPENACS_SERVICE_NAME aolserver]$ cvs -d :pserver:anonymous@openacs.org:/cvsroot checkout -r openacs-5-1-compat acs-core +[$OPENACS_SERVICE_NAME aolserver]$ cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot checkout -r openacs-5-1-compat acs-core [$OPENACS_SERVICE_NAME aolserver]$ cd openacs-4/packages -[$OPENACS_SERVICE_NAME aolserver]$ cvs -d :pserver:anonymous@openacs.org:/cvsroot checkout -r openacs-5-1-compat packagename packagename2... +[$OPENACS_SERVICE_NAME aolserver]$ cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot checkout -r openacs-5-1-compat packagename packagename2... [$OPENACS_SERVICE_NAME aolserver]$ cd ../.. -[$OPENACS_SERVICE_NAME aolserver]$ mv openacs-4 openacs-5-1If this checkout already exists, you can simply update it instead of recreating it.
[root root]# su - $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME aolserver]$ mv openacs-4 openacs-5-1Make sure your working CVS checkout doesn't have + the entire CVS tree from OpenACS. A good way to check + this is if it has a contrib directory. If it does, you + probably checked out the entire tree. You might want to + start over, remove your working CVS checkout, and try + again. +
Step 1: Import new OpenACS code.�
Update CVS.�Update your local CVS working checkout (unless + you just set it up).
[root root]# su - $OPENACS_SERVICE_NAME [$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver/openacs-5-1 -[$OPENACS_SERVICE_NAME aolserver]$ cvs up -Pd(c) A single package via cvs working checkout.�You can add or upgrade a single package at a time, if you already have a cvs working directory.
[root root]# su - $OPENACS_SERVICE_NAME -[$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver/openacs-5-1 -[$OPENACS_SERVICE_NAME openacs-5-1]$ cvs up -d myfirstpackageIn the next section, the import must be tailored to just this package.
Step 2: Merge New OpenACS code.�Now that you have a local copy of the new OpenACS code, you need to import it into your local CVS repository and resolve any conflicts that occur.
Import the new files into your cvs repository; where they match existing files, they will become the new version of the file.
[$OPENACS_SERVICE_NAME openacs-5-1]$ cd /var/lib/aolserver/openacs-5-1 +[$OPENACS_SERVICE_NAME aolserver]$ cvs up -Pd ChangeLog *.txt bin etc tcl www packages/*Update a single package via cvs working checkout.�You can add or upgrade a single package at a time, if you already have a cvs working directory.
[root root]# su - $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver/packages/openacs-5-1 +[$OPENACS_SERVICE_NAME openacs-5-1]$ cvs up -Pd packagenameIn the next section, the import must be tailored to just this package.
Step 2: Merge New OpenACS code.�Now that you have a local copy of the new OpenACS code, you need to import it into your local CVS repository and resolve any conflicts that occur.
Import the new files into your cvs repository; where they match existing files, they will become the new version of the file.
[$OPENACS_SERVICE_NAME openacs-5-1]$ cd /var/lib/aolserver/openacs-5-1 [$OPENACS_SERVICE_NAME openacs-5-1]$ cvs -d /var/lib/cvs import -m "upgrade to OpenACS 5.1" $OPENACS_SERVICE_NAME OpenACS openacs-5-1Tip
If adding or upgrading a single package, run the cvs import from within the base directory of that package, and adjust the cvs command accordingly. In this example, we are adding the myfirstpackage package.
[root root]# su - $OPENACS_SERVICE_NAME [$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver/openacs-5-0/package/myfirstpackage -[$OPENACS_SERVICE_NAME myfirstpackage]$ cvs -d /var/lib/cvs/ import -m "importing package" $OPENACS_SERVICE_NAME/packages/myfirstpackage OpenACS openacs-5-1Create a new directory as temporary working space to reconcile conflicts between the new files and your current work. The example uses the cvs keyword yesterday, making the assumption that you haven't checked in new code to your local tree in the last day.
[$OPENACS_SERVICE_NAME openacs-5.1]$ cd /var/lib/aolserver +[$OPENACS_SERVICE_NAME myfirstpackage]$ cvs -d /var/lib/cvs/ import -m "importing package" $OPENACS_SERVICE_NAME/packages/myfirstpackage OpenACS openacs-5-1Create a new directory as temporary working space to + reconcile conflicts between the new files and your current + work. The example uses the cvs keyword yesterday, making + the assumption that you haven't checked in new code to + your local tree in the last day. This section should be + improved to use tags instead of the keyword yesterday!
[$OPENACS_SERVICE_NAME openacs-5.1]$ cd /var/lib/aolserver +[$OPENACS_SERVICE_NAME tmp]$ rm -rf $OPENACS_SERVICE_NAME-upgrade [$OPENACS_SERVICE_NAME tmp]$ mkdir $OPENACS_SERVICE_NAME-upgrade -[$OPENACS_SERVICE_NAME tmp]$ cvs checkout -d openacs-upgrade -jOpenACS:yesterday -jOpenACS -kk $OPENACS_SERVICE_NAME > cvs.txt 2>&1 -(CVS feedback here)The file /tmp/openacs-upgrade/cvs.txt contains the results of the upgrade. If you changed files that are part of the OpenACS tarball and those changes conflict, you'll have to manually reconcile them. Use the emacs command M-x sort-lines and then, for each line that starts with a C, open that file and manually resolve the conflict by deleting the excess lines. When you're finished, or if there aren't any conflicts, save and exit.
Once you've fixed any conflicts, commit the new code - to your local tree.
[$OPENACS_SERVICE_NAME tmp]$ cd openacs-upgrade -[$OPENACS_SERVICE_NAME openacs-upgrade]$ cvs commit -m "Upgraded to 5.1"Step 3: Upgrade your local staging site.�Update your working tree with the new files. The CVS flags ensure that new directories are created and pruned directories destroyed.
[$OPENACS_SERVICE_NAME openacs-upgrade]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME tmp]$ cvs checkout -d $OPENACS_SERVICE_NAME-upgrade -jOpenACS:yesterday -jOpenACS -kk $OPENACS_SERVICE_NAME > cvs.txt 2>&1 +(CVS feedback here)The file /var/tmp/openacs-upgrade/cvs.txt contains the + results of the upgrade. If you changed files that are + part of the OpenACS tarball and those changes conflict, + you'll have to manually reconcile them. Use the emacs + command M-x sort-lines + (you may have to click Ctrl-space at the beginning of the + file, and go to the end, and then try M-x sort-lines) and then, for each line that starts with a C, open that file and manually resolve the conflict by deleting the excess lines. When you're finished, or if there aren't any conflicts, save and exit.
Once you've fixed any conflicts, commit the new code + to your local tree.
[$OPENACS_SERVICE_NAME tmp]$ cd $OPENACS_SERVICE_NAME-upgrade +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME-upgrade]$ cvs commit -m "Upgraded to 5.1"Step 3: Upgrade your local staging site.�Update your working tree with the new files. The CVS flags ensure that new directories are created and pruned directories destroyed.
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME-upgrade]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cvs up -Pd (CVS feedback) [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ exit [root root]#- Upgrading files for a site using the OpenACS.org CVS repository + Upgrading files for a site using the OpenACS CVS repository (cvs.openacs.org)
[$OPENACS_SERVICE_NAME ~]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cvs up -Pd (CVS feedback) -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$If you are upgrading a production OpenACS site which is on a private CVS tree, this process lets you do the upgrade without risking extended downtime or an unusable site:
Declare a freeze on new cvs updates - ie, you cannot run cvs update +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$
If you are upgrading a production OpenACS site which is on a private CVS tree, this process lets you do the upgrade without risking extended downtime or an unusable site:
Declare a freeze on new cvs updates - ie, you cannot run cvs update on the production site
Make a manual backup of the production site in addition to the automated backups
Import the new code (for example, OpenACS 5.0.4, openacs-5-0-compat versions of @@ -59,4 +110,4 @@
Test the $OPENACS_SERVICE_NAME-upgrade site
If $OPENACS_SERVICE_NAME-upgrade is fully functional, do the real upgrade.
Take down the $OPENACS_SERVICE_NAME site and put up a "down for maintenance" page.
Repeat the upgrade with the most recent database
Test the that the new site is functional. If so, change the upgraded site to respond to - yourserver.net requests. If not, bring the original production site back up and return to the merge.
View comments on this page at openacs.org + yourserver.net requests. If not, bring the original production site back up and return to the merge.
