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 -r1.15.2.1 --- openacs-4/packages/acs-core-docs/www/xml/install-guide/upgrade.xml 10 Mar 2004 03:49:51 -0000 1.15 +++ openacs-4/packages/acs-core-docs/www/xml/install-guide/upgrade.xml 17 Apr 2004 14:11:03 -0000 1.15.2.1 @@ -1,5 +1,5 @@ - %myvars; @@ -286,7 +286,7 @@ Upgrading a Custom or CVS site - If you have no custom code, and your site is not in a CVS repository, upgrade with these steps: + If you have custom code, and your site is in a CVS repository, upgrade with these steps: @@ -322,16 +322,16 @@ 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 +[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 @@ -345,69 +345,155 @@ - + - Unpack the new files into a working directory. + + Step 1: Import new CVS code + 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. + + + + + (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 +[service0 aolserver]$ cd /tmp +[service0 tmp]$ tar xzf openacs-4-6.tgz +[service0 tmp]$ cd openacs-4.6 + + + + (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.) + + [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 + + + + (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 + In the next section, the import must be tailored to just this package. + + + + + + Step 2: Merge New OpenACS code + 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 import -m "upgrade to OpenACS 4.6" openacs - OpenACS openacs-4-6 + [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 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. - - +[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" - cd openacs-upgrade - cvs commit -m "Upgraded to 4.6" - +[service0 openacs-upgrade]$ cvs commit -m "Upgraded to 4.6" + + 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 - (CVS feedback) - [service0 service0]$ exit - [root root]# - cd /var/lib/aolserver/service0 - cvs up -Pd - exit + +[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]$ - - - - - Upgrading files for a site using the OpenACS.org CVS repository - + + + Upgrading a Production Site Safely + 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. - [service0 ~]$ cd /var/lib/aolserver/service0 - [service0 service0]$ cvs up -Pd - (CVS feedback) - [service0 service0]$ + 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. + - - + + + + Upgrading Platform components @@ -463,9 +549,9 @@ [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 +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