Support for upgrades.
by Joel AufrechtStarting with Version 4.5, all OpenACS core packages support
automatic upgrade. That means that, if you have OpenACS 4.5
or better, you should always be able to upgrade all of your core
packages automatically. If you haven't changed anything, no
manual intervention should be required. If you are running
OpenACS prior to 4.5, upgrading will require manual effort.Upgrading OpenACS 4.5 to 4.6ChecklistThe required platform for OpenACS 4.6 is the same as
4.5, with the excepion of OpenFTS. You now need OpenFTS 0.3.2, not 0.2.
OpenACS 4.6 does not support PostGreSQL 7.3.A computer with OpenACS 4.5.OpenACS 4.6 tarballRequired for Full Text Search on PostGreSQL: OpenFTS 0.3.2OverviewOpenACS consists of files and a database schema. The files
in the OpenACS 4.6 tarball include database upgrade scripts. To start the
upgrade, replace your existing files with the new files and
then restart the server. Then, browse to the APM, which will
detect the new packages and offer to run the appropriate database upgrade
scripts. After restarting the server again, the upgrade is
complete.Assumptions in this sectionname of OpenACS usernsadminOpenACS server nameopenacs-devRoot of OpenACS file tree/web/openacs-devDatabase backup directory/backup/openacs/upgradeOpenACS 4.5 to 4.6Linux/UnixUpgrading on Linux/UnixMake a BackupBack up the database and file system.PostGreSQLCreate a backup file and verify that it was created and has a reasonable size (several megabytes).[root@localhost root]# su - nsadmin
[nsadmin@localhost aolserver]$ pg_dump -f /backup/openacs/openacs_dev_before_upgrade_to_4.6.dmp openacs-dev
[nsadmin@localhost aolserver]$ ls -al /backup/openacs/openacs_dev_before_upgrade_to_4.6.dmp
-rw-rw-r-- 1 nsadmin nsadmin 4005995 Feb 21 18:28 /backup/openacs/openacs_dev_before_upgrade_to_4.6.dmp
[nsadmin@localhost aolserver]$ exit
[root@localhost root]#
su - nsadmin
pg_dump -f /backup/openacs/openacs_dev_before_upgrade_to_4.6.dmp openacs-dev
ls -al /backup/openacs/openacs_dev_before_upgrade_to_4.6.dmp
exitOracle - INCOMPLETEFile tree with CVSIf you are already using CVS, you probably don't
need to do anything to back up your data. Just make
sure that your current work is checked into the system.
You can then roll back based on date - just note the
current system time, down to the minute. For maximum
safety, you can apply a tag to your current
files.[root@localhost root]# su - nsadmin
[nsadmin@localhost aolserver]$ cd /web/openacs-dev
[nsadmin@localhost openacs-dev]$ cvs commit -m "last-minute commits before upgrade to 4.6"
cvs commit: Examining .
cvs commit: Examining bin
(many lines omitted)
[nsadmin@localhost openacs-dev]$ cvs tag before_upgrade_to_4_6
cvs server: Tagging bin
T bin/acs-4-0-publish.sh
T bin/ad-context-server.pl
(many lines omitted)
[nsadmin@localhost openacs-dev]$ exit
[root@localhost root]#
su - nsadmin
cd /web/openacs-dev
cvs commit -m "last-minute commits before upgrade to 4.6"
cvs tag before_upgrade_to_4_6
exitFile tree without CVSIf you don't use cvs, you may want to back up the working directory. The simplest way is just to copy it.[root@localhost root]# su - nsadmin
[nsadmin@localhost aolserver]$ cp -r /web/openacs-dev /web/openacs-dev-before-upgrade-to-4.6
[nsadmin@localhost aolserver]$ exit
[root@localhost root]#
su - nsadmin
cp -r /web/openacs-dev /web/openacs-dev-before-upgrade-to-4.6
exitOPTIONAL: Upgrade OpenFTSOpenACS Full Text Search requires several pieces: the OpenFTS code, some database functions, and the OpenFTS Engine. If you have OpenFTS 0.2, you'll need to upgrade to to OpenFTS 0.3.2. This is backwards-compatible -
completing this step will not break a working OpenFTS Engine from 4.5.
Uninstall the old OpenFTS EngineBrowse to http://yourserver/openfts.Click Administration.Click Drop OpenFTS EngineBuild and install the new OpenFTS driver and supporting tcl procedures. (This section of shell code is not fully documented; please exercise care.)cd /usr/local/src/
tar xzf /tmp/Search-OpenFTS-tcl-0.3.2.tar.gz
chown -R root.root Search-OpenFTS-tcl-0.3.2/
cd Search-OpenFTS-tcl-0.3.2/
./configure --with-aolserver-src=/usr/local/src/aolserver/aolserver --with-tcl=/usr/lib/
cd aolserver/
make
Back up the old fts driver as a precaution and install the newly
compiled onemv /usr/local/aolserver/bin/nsfts.so /usr/local/aolserver/bin/nsfts-0.2.so
cp nsfts.so /usr/local/aolserver/bin
Build and install the postgres codecd /usr/local/src/Search-OpenFTS-tcl-0.3.2/
cp -r pgsql_contrib_openfts /usr/local/src/postgresql-7.2.3/contrib /usr/local/src/postgresql-7.2.3/contrib/pgsql_contrib_openfts
make
su - postgres
cd tsearch/
make
make install
exitIn order for the OpenACS 4.6 OpenFTS Engine to use the OpenFTS 0.3.2 driver, we need some commands added to the database.[root@localhost root]# su - nsadmin
[nsadmin@localhost dev]$ psql openacs-dev -f /usr/local/pgsql/share/contrib/openfts.sql
CREATE
CREATE
[nsadmin@localhost dev]$ psql openacs-dev -f /usr/local/src/postgresql-7.2.3/contrib/tsearch/tsearch.sql
BEGIN
CREATE
(~30 more lines)
[nsadmin@localhost dev]$ exit
[root@localhost root]#
su - nsadmin
psql openacs-dev -f /usr/local/pgsql/share/contrib/openfts.sql
psql openacs-dev -f /usr/local/src/postgresql-7.2.3/contrib/tsearch/tsearch.sql
exitStop the server[root@localhost root]# svc -d /service/openacs-devUpgrade the file treeIf you are using CVS, you will unpack the OpenACS 4.6 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 without CVSUnpack the tarball into a new directory and copy its contents on top of your working directory.[root@localhost root]# su - nsadmin
[nsadmin@localhost aolserver]$ cd /web
[nsadmin@localhost web]$ tar xzf /tmp/openacs-4-6.tgz
[nsadmin@localhost web]$ cp -r openacs-4-6/* openacs-4
[nsadmin@localhost openacs-upgrade]$ exit
[root@localhost root]#
su - nsadmin
cd /web
tar xzf /tmp/openacs-4-6.tgz
cp -r openacs-4-6/* openacs-4
exitUpgrading files with CVSUnpack the new files into a working directory.[root@localhost root]# su - nsadmin
[nsadmin@localhost aolserver]$ cd /tmp
[nsadmin@localhost tmp]$ tar xzv openacs-4-6.tgz
[nsadmin@localhost tmp]$ cd openacs-4.6Import the new files into your cvs repository; where they match existing files, they will become the new version of the file.[nsadmin@localhost openacs-4.6]$ cvs import -m "upgrade to OpenACS 4.6" openacs
OpenACS openacs-4-6Create 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.[nsadmin@localhost openacs-4.6]$ cd /web
[nsadmin@localhost tmp]$ mkdir openacs-upgrade
[nsadmin@localhost tmp]$ cvs checkout -d openacs-upgrade -jOpenACS:yesterday -jOpenACS openacs < cvs.txt 2<&1
(CVS feedback here)
su - nsadmin
cd /tmp
tar xzv openacs-4-6.tgz
cd openacs-4.6
cvs import -m "upgrade to OpenACS 4.6" openacs OpenACS openacs-4-6
cd /tmp
mkdir openacs-upgrade
cvs checkout -d openacs-upgrade -jOpenACS:yesterday -jOpenACS openacs < cvs.txt 2<&1
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 with the 4.5-4.6 upgrade, 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. [nsadmin@localhost tmp]$ cd openacs-upgrade
[nsadmin@localhost openacs-upgrade]$ cvs commit -m "Upgraded to 4.6"cd openacs-upgrade
cvs commit -m "Upgraded to 4.6"Update your working tree with the new
files. The CVS flags ensure that new directories are created and pruned directories destroyed.
[nsadmin@localhost openacs-upgrade]$ cd /web/openacs-dev
[nsadmin@localhost openacs-dev]$ cvs up -Pd
(CVS feedback)
[nsadmin@localhost openacs-dev]$ exit
[root@localhost root]#
cd /web/openacs-dev
cvs up -Pd
exitStart the server[root@localhost root]# svc -u /service/openacs-devUse APM to upgrade the databaseBrowse to the package manager, http://yourserver/acs-admin/apm.Click Install packages.Select the packages you want to install. This should be everything that says upgrade, plus any new packages you want.On the next screen, click Install PackagesWhen prompted, restart the server:[root@localhost root]# restart-aolserver openacs-devWait a minute, then browse to the package manager, http://yourserver/acs-admin/apm.Check that the kernel upgrade worked by clicking All and making sure that acs-kernel version is 4.6.1.OPTIONAL: Install the new OpenFTS Engine.If you want to upgrade the OpenFTS Engine, do these steps. (You
must have already upgraded the OpenFTS driver to
0.3.2.Browse to http://yourserver/admin/site-mapOn the openfts line, click on set parameters.Change the value of openfts_tcl_src_path from /usr/local/src/Search-OpenFTS-tcl-0.2/ to /usr/local/src/Search-OpenFTS-tcl-0.3.2/Click Set Parameters[root@localhost root]# restart-aolserver openacs-devBrowse to http://yourserver/openftsClick Administration.Click Initialize OpenFTS EngineRollbackIf anything goes wrong, roll back the database and try
again.[root@localhost root]# su - nsadmin
[nsadmin@localhost aolserver]$ svc -d /service/openacs-dev
[nsadmin@localhost aolserver]$ dropdb openacs-dev
DROP DATABASE
[nsadmin@localhost aolserver]$ createdb openacs-dev
CREATE DATABASE
[nsadmin@localhost aolserver]$ psql -f /web/openacs-dev/packages/acs-kernel/sql/postgresql/postgresql.sql openacs-devPostGreSQL's dump command does not guarantee to back up all of the
procedures and things in the right order for them to be reassembled.
In practice, OpenACS users have found that rebuilding some of the
common procedures before running the restore usually addresses this. You will see a number of "already exists" errors when you run the database restore; these can be ignored. This forum thread has more information.[nsadmin@localhost aolserver]$ psql openacs-dev < /backup/openacs/openacs_dev_before_upgrade_to_4.6.dmp
[nsadmin@localhost aolserver]$ svc -u /service/openacs-dev
[nsadmin@localhost aolserver]$ exitAt this point, you can try go back to the APM and try
to upgrade the database again. Alternately, if you want to roll back
all the way and stop the upgrade, you need to roll back the file
system as well.[root@localhost root]# su - nsadmin
[nsadmin@localhost aolserver]$ mv /web/openacs-dev /web/openacs-failed-upgrade
[nsadmin@localhost aolserver]$ mv /web/openacs-dev-before-upgrade-to-4.6 /web/openacs-dev
[nsadmin@localhost aolserver]$ svc -u /web/openacs-dev
[nsadmin@localhost aolserver]$ exit
[root@localhost root]#All commands for this section:
su - nsadmin
svc -d /service/openacs-dev
dropdb openacs-dev
createdb openacs-dev
psql -f /web/openacs-dev/packages/acs-kernel/sql/postgresql/postgresql.sql openacs-dev
psql openacs-dev < /backup/openacs/openacs_dev_before_upgrade_to_4.6.dmp
svc -u /service/openacs-dev
cd /web/openacs-dev
cvs up -r current
exit($Id: upgrade.xml,v 1.2.2.1 2003/03/30 05:56:18 joela Exp $)