%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 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. If upgrading from 4.2, you need to manually run acs-kernel/sql/postgres/upgrade-4.2-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/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. Not yet documented. It should be possible to upgrade via the APM just as when upgrading to 4.6.3. 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 - service0 [service0 aolserver]$ cd /var/lib/aolserver/ service0/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 service0. Run the scripts in this order (order is tentative, not verified): psql -f upgrade-4.6.3-4.6.4.sql service0 psql -f upgrade-4.6.4-4.6.5.sql service0 psql -f upgrade-4.6.5-4.6.6.sql service0 psql -f upgrade-4.7d-4.7.2d.sql service0 psql -f upgrade-4.7.2d-5.0d.sql service0 psql -f upgrade-5.0d-5.0d2.sql service0 psql -f upgrade-5.0d2-5.0d3.sql service0 psql -f upgrade-5.0d6-5.0d7.sql service0 psql -f upgrade-5.0d7-5.0d9.sql service0 psql -f upgrade-5.0d11-5.0d12.sql service0 psql -f upgrade-5.0.0a4-5.0.0a5.sql service0 psql -f upgrade-5.0.0b1-5.0.0b2.sql service0 psql -f upgrade-5.0.0b2-5.0.0b3.sql service0 psql -f upgrade-5.0.0b3-5.0.0b4.sql service0 Upgrade ACS Service Contracts manually: [service0 aolserver]$ cd /var/lib/aolserver/ service0/packages/acs-service-contracts/sql/postgresql/upgrade psql -f upgrade-4.7d2-4.7d3.sql service0 Load acs-authentication data model. psql -f /var/lib/aolserver/service0/openacs-5/packages/acs-authentication/sql/postgresql/acs-authentication-create.sql service0 Load acs-lang data model. psql -f /var/lib/aolserver/service0/packages/acs-lang/sql/postgresql/acs-lang-create.sql service0 (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 service0/tcl/zzz-postload.tcl containing: if {![apm_package_installed_p acs-lang]} { apm_package_install -enable -mount_path acs-lang [acs_root_dir]/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_root_dir]/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. 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 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 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 for a site in a private CVS repository

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. Download a current tarball and 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 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-0-compat tag identifies the latest released version of OpenACS 5.0 (ie, 5.0.3 or 5.0.4) and the latest compatible version of each package, including .LRN. Each minor release of OpenACS since 5.0 has this tagging structure. (Ie., OpenACS 5.1.x has openacs-5-1-compat.) [root root]# su - service0 [service0 aolserver]$ cd /var/lib/aolserver [service0 aolserver]$ cvs -d :pserver:anonymous@openacs.org:/cvsroot checkout -r openacs-5-0-compat openacs-4 [service0 aolserver]$ mv openacs-4 openacs-5-0 If this checkout already exists, you can simply update it instead of recreating it. [root root]# su - service0 [service0 aolserver]$ cd /var/lib/aolserver/openacs-5-0 [service0 aolserver]$ cvs up -Pd You can add or upgrade a single package at a time, if you already have a cvs working directory. [root root]# su - service0 [service0 aolserver]$ cd /var/lib/aolserver/openacs-5-0 [service0 openacs-5-0]$ cvs up -d myfirstpackage 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. [service0 openacs-4.6]$ cvs -d /var/lib/cvs import -m "upgrade to OpenACS 4.6" openacs OpenACS openacs-4-6 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 - service0 [service0 aolserver]$ cd /var/lib/aolserver/openacs-5-0/packagse/myfirstpackage [service0 myfirstpackage]$ cvs -d /var/lib/cvs/ import -m "importing package" service0/packages/myfirstpackage 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 service0-upgrade [service0 tmp]$ cvs checkout -d openacs-upgrade -jOpenACS:yesterday -jOpenACS openacs > 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 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" 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]# Upgrading files for a site using the OpenACS.org CVS repository [service0 ~]$ cd /var/lib/aolserver/service0 [service0 service0]$ cvs up -Pd (CVS feedback) [service0 service0]$ 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 service0 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 service0-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 service0-upgrade. Now we have a new website called service0-upgrade. Test the service0-upgrade site If service0-upgrade is fully functional, do the real upgrade. Take down the service0 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 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 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 service0'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.