%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. If all of these conditions are true: Your OpenACS Core is 5.0.0 or later You do not keep your OpenACS site in a local CVS repository You do not have any custom code then you can upgrade automatically using the automated installer in the OpenACS Package Manager (APM), and you can probably skip the rest of this chapter. To upgrade directly from the OpenACS repository using the APM: Browse to the Installer. Click install or upgrade under "Install from OpenACS Repository" and select the packages to install or upgrade. The APM will download the requested packages from OpenACS.org, install the files on your hard drive, run any appropriate database upgrade scripts, and prompt you to restart the server. After restarting the server again, the upgrade is complete.

It's always a good idea to precede an upgrade attempt with a snapshot backup. name of OpenACS user $OPENACS_SERVICE_NAME OpenACS server name $OPENACS_SERVICE_NAME Root of OpenACS file tree /var/lib/aolserver/$OPENACS_SERVICE_NAME Database backup directory /var/lib/aolserver/$OPENACS_SERVICE_NAME/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. If upgrading from 4.4, you need to manually run acs-kernel/sql/postgres/upgrade-4.4-4.5.sql. See Bug #632 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/$OPENACS_SERVICE_NAME Start the server [root root]# svc -u /service/$OPENACS_SERVICE_NAME 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 $OPENACS_SERVICE_NAME 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. This forum posting documents how to upgrade an Oracle installation from OpenACS 4.6.3 to 5 . You must use PostGreSQL 7.3.x or newer to upgrade OpenACS beyond 4.6.3. See Upgrade PostGreSQL to 7.3; Back up the database and file system. Upgrade the kernel manually. (There is a script to do most of the rest: /contrib/misc/upgrade_4.6_to_5.0.sh on HEAD). You'll still have to do a lot of stuff manually, but automated trial and error is much more fun.) [root root]# su - $OPENACS_SERVICE_NAME [$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver/ $OPENACS_SERVICE_NAME/packages/acs-kernel/sql/postgresql/upgrade Manually execute each of the upgrade scripts in sequence, either from within psql or from the command line with commands such as psql -f upgrade-4.6.3-4.6.4.sql $OPENACS_SERVICE_NAME. Run the scripts in this order (order is tentative, not verified): psql -f upgrade-4.6.3-4.6.4.sql $OPENACS_SERVICE_NAME psql -f upgrade-4.6.4-4.6.5.sql $OPENACS_SERVICE_NAME psql -f upgrade-4.6.5-4.6.6.sql $OPENACS_SERVICE_NAME psql -f upgrade-4.7d-4.7.2d.sql $OPENACS_SERVICE_NAME psql -f upgrade-4.7.2d-5.0d.sql $OPENACS_SERVICE_NAME psql -f upgrade-5.0d-5.0d2.sql $OPENACS_SERVICE_NAME psql -f upgrade-5.0d2-5.0d3.sql $OPENACS_SERVICE_NAME psql -f upgrade-5.0d6-5.0d7.sql $OPENACS_SERVICE_NAME psql -f upgrade-5.0d7-5.0d9.sql $OPENACS_SERVICE_NAME psql -f upgrade-5.0d11-5.0d12.sql $OPENACS_SERVICE_NAME psql -f upgrade-5.0.0a4-5.0.0a5.sql $OPENACS_SERVICE_NAME psql -f upgrade-5.0.0b1-5.0.0b2.sql $OPENACS_SERVICE_NAME psql -f upgrade-5.0.0b2-5.0.0b3.sql $OPENACS_SERVICE_NAME psql -f upgrade-5.0.0b3-5.0.0b4.sql $OPENACS_SERVICE_NAME Upgrade ACS Service Contracts manually: [$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver/ $OPENACS_SERVICE_NAME/packages/acs-service-contracts/sql/postgresql/upgrade psql -f upgrade-4.7d2-4.7d3.sql $OPENACS_SERVICE_NAME Load acs-authentication data model. psql -f /var/lib/aolserver/$OPENACS_SERVICE_NAME/openacs-5/packages/acs-authentication/sql/postgresql/acs-authentication-create.sql $OPENACS_SERVICE_NAME Load acs-lang data model. psql -f /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-lang/sql/postgresql/acs-lang-create.sql $OPENACS_SERVICE_NAME (This step may overlap with the two previous steps, but I think it's harmless?) Create a file which will be executed on startup which takes care of a few issues with authentication and internationalization: create $OPENACS_SERVICE_NAME/tcl/zzz-postload.tcl containing: if {![apm_package_installed_p acs-lang]} { apm_package_install -enable -mount_path acs-lang $::acs::rootdir/packages/acs-lang/acs-lang.info lang::catalog::import -locales [list "en_US"] } if {![apm_package_installed_p acs-authentication]} { apm_package_install -enable $::acs::rootdir/packages/acs-authentication/acs-authentication.info apm_parameter_register "UsePasswordWidgetForUsername" \ "Should we hide what the user types in the username field, the way we do with the password field? Set this to 1 if you are using sensitive information such as social security number for username." \ acs-kernel 0 number \ security 1 1 parameter::set_value -package_id [ad_acs_kernel_id] -parameter UsePasswordWidgetForUsername -value 0 } If you can login, visit /acs-admin/apm and upgrade acs-kernel and acs-service-contract and uncheck the data model scripts. Restart. If everything is still working, make another backup of the database. Upgrade other packages via the APM See also these forum posts: Forum OpenACS Development: 4.6.3 upgrade to 5-HEAD: final results, OpenACS 5.0 Upgrade Experiences. There are a few things you might want to do once you've upgraded. First, the acs-kernel parameters need to be set to allow HREF and IMG tags, if you want users who can edit HTML to be able to insert HREF and IMG tags. Also, you might need to set the default language for your site. See the above link on OpenACS 5.0 Upgrade Experiences for details. If you have no custom code, and your site is not in a CVS repository, upgrade with these steps: Go to /acs-admin/install/ and click "Upgrade Your System" in "Install from OpenACS Repository" Select all of the packages you want to upgrade and proceed After upgrade is complete, restart the server as indicated. If you are using locales other than en_US, go to acs-lang/admin and "Import all Messages" to load the new translated messages. Your local translations, if any, will take precedence over imported translations. If you have custom code, and your site is in a CVS repository, upgrade with these steps: Go to /acs-admin/install/ and click "Upgrade Your System" in "Install from local file system" Select all of the packages you want to upgrade and proceed After upgrade is complete, restart the server as indicated. If you are using locales other than en_US, go to acs-lang/admin and "Import all Messages" to load the new translated messages. Your local translations, if any, will take precedence over imported translations. 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: 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 /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 /var/tmp/openacs-5-1.tgz cp -r openacs-5-1/* openacs-4 exit Upgrading files for a site in a private CVS repository 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.

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@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@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-1 Make 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. 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 ChangeLog *.txt bin etc Tcl www packages/* 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 packagename In the next section, the import must be tailored to just this package. 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-1 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-1 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. 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_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" 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 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 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 ETP, blogger, and other applications) into a "vendor branch" of the $OPENACS_SERVICE_NAME CVS tree, as described in "Upgrading a local CVS repository", step 1, above. As soon as we do this, any cvs update command on production might bring new code onto the production site, which would be bad. Do step 2 above (merging conflicts in a $OPENACS_SERVICE_NAME-upgrade working tree). Manually resolve any conflicts in the working upgrade tree Use the upgrade script and a recent backup of the production database, to ake a new upgraded database called $OPENACS_SERVICE_NAME-upgrade. Now we have a new website called $OPENACS_SERVICE_NAME-upgrade. 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. 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 $OPENACS_SERVICE_NAME 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 /var/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 PostgreSQL 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 - $OPENACS_SERVICE_NAME [$OPENACS_SERVICE_NAME dev]$ psql $OPENACS_SERVICE_NAME -f /usr/local/pgsql/share/contrib/openfts.sql CREATE CREATE [$OPENACS_SERVICE_NAME dev]$ psql $OPENACS_SERVICE_NAME -f /usr/local/src/postgresql-7.2.3/contrib/tsearch/tsearch.sql BEGIN CREATE (~30 more lines) [$OPENACS_SERVICE_NAME dev]$ exit [root root]# su - $OPENACS_SERVICE_NAME psql $OPENACS_SERVICE_NAME -f /usr/local/pgsql/share/contrib/openfts.sql psql $OPENACS_SERVICE_NAME -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 $OPENACS_SERVICE_NAME 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/$OPENACS_SERVICE_NAME/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 - $OPENACS_SERVICE_NAME [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]# cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/bin [$OPENACS_SERVICE_NAME bin]$ ./pg_7.2to7.3_upgrade_helper.pl \ ../database-backup/nightly.dmp \ ../database-backup/upgrade-7.3.dmp \ /var/lib/aolserver/$OPENACS_SERVICE_NAME ================================================================== 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) [$OPENACS_SERVICE_NAME bin]$ Use perl to replace timestamp with timestamptz in the dump file. See example perl code in step two in /contrib/misc/upgrade_4.6_to_5.0.sh Create a new user for PostgreSQL 7.3.x, as per the Postgres installation guide. Keep in mind that your installation location is different, and your startup script (/etc/init.d/postgres73 should be named differently. You might even need to edit that file to make the paths correct). You'll also need to add export PGPORT=5434 to the .bashrc and/or .bash_profile for the postgres73 user. Install PostgreSQL 7.3.x. Note that you PostgreSQL must listen on a different port in order to work correctly, so you'll need to edit the configuration file (/usr/local/pgsql73/data/postgresql.conf) and change the port (to 5433, say). create a second postgres user to differentiate between the two postgres installs. When you do ./configure, you'll need to include --prefix=$HOME to ensure that it is installed in the postgres73 user's home directory. Change the path in $OPENACS_SERVICE_NAME's .bashrc or .bash_profile (or both) files to reflect the new postgres73 user directory. Also add in the PGPORT. Restore the database from dump as per the recovery instructions.