Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/upgrade.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/upgrade.xml,v diff -u -r1.15.2.1 -r1.15.2.2 --- openacs-4/packages/acs-core-docs/www/xml/install-guide/upgrade.xml 17 Apr 2004 14:11:03 -0000 1.15.2.1 +++ openacs-4/packages/acs-core-docs/www/xml/install-guide/upgrade.xml 5 Jul 2004 19:47:37 -0000 1.15.2.2 @@ -45,7 +45,7 @@ Upgrading with the APM - + @@ -57,19 +57,19 @@ name of OpenACS user - service0 + $OPENACS_SERVICE_NAME OpenACS server name - service0 + $OPENACS_SERVICE_NAME Root of OpenACS file tree - /var/lib/aolserver/service0 + /var/lib/aolserver/$OPENACS_SERVICE_NAME Database backup directory - /var/lib/aolserver/service0/database-backup + /var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup @@ -110,7 +110,7 @@ Stop the server - [root root]# svc -d /service/service0 + [root root]# svc -d /service/$OPENACS_SERVICE_NAME @@ -122,7 +122,7 @@ Start the server - [root root]# svc -u /service/service0 + [root root]# svc -u /service/$OPENACS_SERVICE_NAME @@ -149,7 +149,7 @@ When prompted, restart the server: - [root root]# restart-aolserver service0 + [root root]# restart-aolserver $OPENACS_SERVICE_NAME Wait a minute, then browse to the package manager, http://yourserver/acs-admin/apm. @@ -194,42 +194,42 @@ 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 + [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 service0. Run the scripts in this order (order is tentative, not verified): + 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 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 + 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: - [service0 aolserver]$ cd /var/lib/aolserver/ service0/packages/acs-service-contracts/sql/postgresql/upgrade -psql -f upgrade-4.7d2-4.7d3.sql service0 + [$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/service0/openacs-5/packages/acs-authentication/sql/postgresql/acs-authentication-create.sql service0 + 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/service0/packages/acs-lang/sql/postgresql/acs-lang-create.sql service0 + 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 service0/tcl/zzz-postload.tcl containing: + (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_root_dir]/packages/acs-lang/acs-lang.info lang::catalog::import -locales [list "en_US"] @@ -257,11 +257,20 @@ 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. + - Upgrading 5.0.0 to 5.0.x + Upgrading 5.0.0 to 5.0.x or 5.1.x @@ -314,23 +323,23 @@ Upgrading the OpenACS files 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. + 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 - 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 - $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]$ cp -r openacs-5-1/* openacs-4 +[$OPENACS_SERVICE_NAME openacs-upgrade]$ exit [root root]# -su - service0 +su - $OPENACS_SERVICE_NAME cd /var/lib/aolserver -tar xzf /tmp/openacs-4-6.tgz -cp -r openacs-4-6/* openacs-4 +tar xzf /tmp/openacs-5-1.tgz +cp -r openacs-5-1/* openacs-4 exit @@ -341,7 +350,7 @@ Upgrading a local CVS repository - + @@ -357,33 +366,39 @@ (a): via tarball 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 + [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-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.) + 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 - 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 + [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]$ 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]$ cd ../.. +[$OPENACS_SERVICE_NAME aolserver]$ mv openacs-4 openacs-5-1 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 + [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 - service0 -[service0 aolserver]$ cd /var/lib/aolserver/openacs-5-0 -[service0 openacs-5-0]$ cvs up -d myfirstpackage + [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 myfirstpackage In the next section, the import must be tailored to just this package. @@ -394,34 +409,37 @@ 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 + + [$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 - 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 + [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. - [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. + [$OPENACS_SERVICE_NAME openacs-5.1]$ cd /var/lib/aolserver +[$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. - [service0 tmp]$ cd openacs-upgrade -[service0 openacs-upgrade]$ cvs commit -m "Upgraded to 4.6" + [$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. -[service0 openacs-upgrade]$ cd /var/lib/aolserver/service0 -[service0 service0]$ cvs up -Pd +[$OPENACS_SERVICE_NAME openacs-upgrade]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cvs up -Pd (CVS feedback) -[service0 service0]$ exit +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ exit [root root]# @@ -432,10 +450,10 @@ - [service0 ~]$ cd /var/lib/aolserver/service0 -[service0 service0]$ cvs up -Pd + [$OPENACS_SERVICE_NAME ~]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cvs up -Pd (CVS feedback) -[service0 service0]$ +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ @@ -454,10 +472,10 @@ 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. + $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 service0-upgrade working tree). + Do step 2 above (merging conflicts in a $OPENACS_SERVICE_NAME-upgrade working tree). @@ -466,20 +484,20 @@ 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. + a new upgraded database called $OPENACS_SERVICE_NAME-upgrade. Now we + have a new website called $OPENACS_SERVICE_NAME-upgrade. - Test the service0-upgrade site + Test the $OPENACS_SERVICE_NAME-upgrade site - If service0-upgrade is fully functional, do the real upgrade. + If $OPENACS_SERVICE_NAME-upgrade is fully functional, do the real upgrade. - Take down the service0 site and put up a "down for maintenance" page. + Take down the $OPENACS_SERVICE_NAME site and put up a "down for maintenance" page. Repeat the upgrade with the most recent database @@ -501,7 +519,7 @@ 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. + Uninstall the old OpenFTS Engine from the $OPENACS_SERVICE_NAME database. Browse to http://yourserver/openfts. @@ -538,19 +556,19 @@ 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 + [root root]# su - $OPENACS_SERVICE_NAME + [$OPENACS_SERVICE_NAME dev]$ psql $OPENACS_SERVICE_NAME -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 + [$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) - [service0 dev]$ exit + [$OPENACS_SERVICE_NAME 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 + 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 @@ -574,7 +592,7 @@ Click Set Parameters - [root root]# restart-aolserver service0 + [root root]# restart-aolserver $OPENACS_SERVICE_NAME Browse to http://yourserver/openfts @@ -600,27 +618,27 @@ 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: + 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 - service0 - [service0 service0]# cd /var/lib/aolserver/service0/bin - [service0 bin]$ ./pg_7.2to7.3_upgrade_helper.pl \ + [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/service0 + /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) - [service0 bin]$ + [$OPENACS_SERVICE_NAME bin]$ @@ -651,7 +669,7 @@ Change the path in - service0's .bashrc or + $OPENACS_SERVICE_NAME's .bashrc or .bash_profile (or both) files to reflect the new postgres73 user directory. Also add in the PGPORT.