%myvars; ]> by Joel Aufrecht Starting 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. It's always a good idea to precede an upgrade attempt with a snapshot backup. OpenACS consists of files and a database schema. The files in a new tarball include database upgrade scripts. To start the upgrade, replace your existing files with the new files and 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. name of OpenACS user service0 OpenACS server name service0 Root of OpenACS file tree /var/lib/aolserver/service0 Database backup directory /var/lib/aolserver/service0/database-backup upgrade OpenACS 4.5 to 4.6.x Linux/Unix The required platform for OpenACS 4.6 is the same as 4.5, with the exception of OpenFTS. OpenACS 4.6 and later require OpenFTS 0.3.2 for full text search on PostGreSQL. If you have OpenFTS 0.2, you'll need to upgrade. A computer with OpenACS 4.5. OpenACS 4.6 tarball or CVS checkout/export. Required for Full Text Search on PostgreSQL: OpenFTS 0.3.2 Back up the database and file system (see ). Stop the server [root root]# svc -d /service/service0 Start the server [root root]# svc -u /service/service0 Browse 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. It's safest to upgrade the kernel by itself, and then come back and upgrade the rest of the desired packages in a second pass. On the next screen, click Install Packages When prompted, restart the server: [root root]# restart-aolserver service0 Wait 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 &version;. If anything goes wrong, roll back to the backup snapshot. Same as OpenACS 5.0 requires PostGreSQL 7.3; OpenACS 4.6.3 supports both 7.2 and 7.3; OpenACS versions prior to 4.6.3 do not support PostGreSQL 7.3. Therefore, if you are upgrading a PostGreSQL OpenACS site from a version before 4.6.3, you must do it in three steps: Upgrade OpenACS to 4.6.3 Upgrade PostGreSQL to 7.3 Upgrade OpenACS to 5.0.0 Current working notes in Forum OpenACS Development: 4.6.3 upgrade to 5-HEAD: final results. 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. If 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. Unpack the tarball into a new directory and copy its contents on top of your working directory. [root root]# su - service0 [service0 aolserver]$ cd /var/lib/aolserver [service0 web]$ tar xzf /tmp/openacs-4-6.tgz [service0 web]$ cp -r openacs-4-6/* openacs-4 [service0 openacs-upgrade]$ exit [root root]# su - service0 cd /var/lib/aolserver tar xzf /tmp/openacs-4-6.tgz cp -r openacs-4-6/* openacs-4 exit Upgrading files with CVS Unpack the new files into a working directory. [root root]# su - service0 [service0 aolserver]$ cd /tmp [service0 tmp]$ tar xzf openacs-4-6.tgz [service0 tmp]$ cd openacs-4.6 Import the new files into your cvs repository; where they match existing files, they will become the new version of the file. [service0 openacs-4.6]$ cvs import -m "upgrade to OpenACS 4.6" openacs OpenACS openacs-4-6 Create 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. [service0 openacs-4.6]$ cd /var/lib/aolserver [service0 tmp]$ mkdir openacs-upgrade [service0 tmp]$ cvs checkout -d openacs-upgrade -jOpenACS:yesterday -jOpenACS openacs > cvs.txt 2>&1 (CVS feedback here) su - service0 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. [service0 tmp]$ cd openacs-upgrade [service0 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. [service0 openacs-upgrade]$ cd /var/lib/aolserver/service0 [service0 service0]$ cvs up -Pd (CVS feedback) [service0 service0]$ exit [root root]# cd /var/lib/aolserver/service0 cvs up -Pd exit OpenACS Full Text Search requires several pieces: the OpenFTS code, some database functions, and the OpenFTS Engine. This section describes how to upgrade OpenFTS from 0.2 to 0.3.2 and upgrade the search engine on an OpenACS site at the same time. Uninstall the old OpenFTS Engine from the service0 database. Browse to http://yourserver/openfts. Click Administration. Click Drop OpenFTS Engine Build 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 one mv /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 OpenFTS code for PostGresSQL cd /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 exit In 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 root]# su - service0 [service0 dev]$ psql service0 -f /usr/local/pgsql/share/contrib/openfts.sql CREATE CREATE [service0 dev]$ psql service0 -f /usr/local/src/postgresql-7.2.3/contrib/tsearch/tsearch.sql BEGIN CREATE (~30 more lines) [service0 dev]$ exit [root root]# su - service0 psql service0 -f /usr/local/pgsql/share/contrib/openfts.sql psql service0 -f /usr/local/src/postgresql-7.2.3/contrib/tsearch/tsearch.sql exit 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-map On 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 root]# restart-aolserver service0 Browse to http://yourserver/openfts Click Administration. Click Initialize OpenFTS Engine An OpenACS database created in PostGreSQL 7.2 will not work correctly in PostGreSQL 7.3. This is because 7.2 truncates function names to 31 characters, but 7.3 does not. This does not cause problems in 7.2, because truncation occurs both at function creation and at function calling, so they still match. But if you use a database created in 7.2 in 7.3, the function names in the database remain truncated but the function calls are not, and so they don't match. Also some functions use casting commands that no longer work in 7.3 and these functions must be recreated. To upgrade an OpenACS site from PostGreSQL 7.2 to 7.3, first upgrade the kernel to 4.6.3. Then, dump the database, run the upgrade script /var/lib/aolserver/service0/bin/pg_7.2to7.3_upgrade_helper.pl on the dump file, and reply the dump. See Forum OpenACS Q&A: PG 7.2->7.3 upgrade gotcha?. Example: Back up the database as per . Run the upgrade script on the backup file. [root root]# su - service0 [service0 service0]# cd /var/lib/aolserver/service0/bin [service0 bin]$ ./pg_7.2to7.3_upgrade_helper.pl \ ../database-backup/nightly.dmp \ ../database-backup/upgrade-7.3.dmp \ /var/lib/aolserver/service0 ================================================================== looking for function acs_object__check_object_ancest in oacs grep result: /var/lib/aolserver/aufrecht-dev/packages/acs-kernel/sql/postgresql/acs-objects-create.sql:create function acs_object__check_object_ancestors (integer,integer,integer) replacing acs_object__check_object_ancest with acs_object__check_object_ancestors (many lines omitted) [service0 bin]$ Use perl to replace timestamp with timestamptz. find . -type f -name "*sql" | xargs perl -p -i.tmp -e "s/timestamp with time zone/timestamptz/g" find . -type f -name "*sql" | xargs perl -p -i.tmp -e "s/\\wtimestamp[^t]/ timestamptz/g" Restore the database from dump as per the recovery instructions.