Index: openacs-4/packages/acs-core-docs/www/upgrade-openacs-files.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/upgrade-openacs-files.adp,v diff -u -r1.5 -r1.6 --- openacs-4/packages/acs-core-docs/www/upgrade-openacs-files.adp 25 Apr 2018 08:38:28 -0000 1.5 +++ openacs-4/packages/acs-core-docs/www/upgrade-openacs-files.adp 3 Sep 2024 15:37:32 -0000 1.6 @@ -1,7 +1,11 @@ -{/doc/acs-core-docs {ACS Core Documentation}} {Upgrading the OpenACS files} +{/doc/acs-core-docs/ {ACS Core Documentation}} {Upgrading the OpenACS files} Upgrading the OpenACS files + Upgrading the OpenACS files

-Choosing a Method to Upgrade your -Files

OpenACS is distributed in many different ways:

    +Choosing a +Method to Upgrade your Files

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, +

Upgrades work by first changing the filesystem (via any of the +previous methods), and then using the APM to scan the filesystem, 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: the -section called “Upgrading an OpenACS 5.0.0 or greater -installation” +the last method was added, which automatically changes the +filesystem 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: the section +called “Upgrading an OpenACS 5.0.0 or greater installation”

-Methods of upgrading OpenACS files

    +Methods of +upgrading OpenACS files

  • Upgrading files for a site which is not in a CVS -repository.  Unpack the tarball into a new directory +repository. 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
+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
+su - $OPENACS_SERVICE_NAME
 cd /var/lib/aolserver
 tar xzf /var/tmp/openacs-5-1.tgz
 cp -r openacs-5-1/* openacs-4
-exit
+exit

  • Upgrading files for a site in a @@ -54,12 +58,12 @@ 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.

    -

    Figure 5.2. Upgrading a local +

    Figure 5.2. Upgrading a local CVS repository

    Upgrading a local CVS repository

    • -Step 0: Set up a working CVS checkout.  To +Step 0: Set up a working CVS checkout. 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 @@ -73,20 +77,20 @@ 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
+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]$ 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-compatpackagename packagename2...
+[$OPENACS_SERVICE_NAME aolserver]$ cvs -d :pserver:anonymous\@cvs.openacs.org:/cvsroot checkout -r openacs-5-1-compatpackagename packagename2...
 
 [$OPENACS_SERVICE_NAME aolserver]$ cd ../..
-[$OPENACS_SERVICE_NAME aolserver]$ mv openacs-4 openacs-5-1
+[$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
@@ -97,58 +101,56 @@
 
      Step 1: Import new OpenACS code. 
        
 
      • 
 
        
-Update CVS.  Update your local CVS working
-checkout (unless you just set it up).
        [root root]# su - $OPENACS_SERVICE_NAME
+Update CVS. 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]$ cd /var/lib/aolserver/openacs-5-1
 
 [$OPENACS_SERVICE_NAME aolserver]$ cvs up -Pd ChangeLog *.txt bin etc Tcl www packages/*
 
        
 
      • 
 
        
 Update 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 - $OPENACS_SERVICE_NAME
+checkout. 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 aolserver]$ cd /var/lib/aolserver/packages/openacs-5-1
 
-[$OPENACS_SERVICE_NAME openacs-5-1]$ cvs up -Pd packagename
+[$OPENACS_SERVICE_NAME openacs-5-1]$ cvs up -Pd packagename
 
 
        In the next section, the import must be tailored to just this
 package.
        
 
        •

    • -Step 2: Merge New OpenACS code.  Now that +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.

      -[$OPENACS_SERVICE_NAME openacs-5-1]$  cd /var/lib/aolserver/openacs-5-1
+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
+[$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
 
 
      
 
      Tip
      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
+myfirstpackage package.
      [root root]# su - $OPENACS_SERVICE_NAME
 
-[$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver/openacs-5-0/package/myfirstpackage
+[$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
+[$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
+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
@@ -158,15 +160,15 @@
 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"
+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"

    • -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.

      [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME-upgrade]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME
+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.
      [$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)
@@ -176,38 +178,37 @@

Upgrading files for a site using -the OpenACS CVS repository (cvs.openacs.org)

  1. [$OPENACS_SERVICE_NAME ~]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME
+the OpenACS CVS repository (cvs.openacs.org)
    1. [$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]$

-Upgrading a Production Site Safely

If you are upgrading a production OpenACS site which is on a +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:

  1. Declare a freeze on new cvs updates - ie, you cannot run cvs update on the production site

  2. Make a manual backup of the production site in addition to the automated backups

  3. 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 +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).

    +bad.

    Do step 2 above (merging conflicts in a $OPENACS_SERVICE_NAME-upgrade working +tree).

  4. Manually resolve any conflicts in the working upgrade tree

  5. 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.

  6. Test the $OPENACS_SERVICE_NAME-upgrade -site

  7. -

    If $OPENACS_SERVICE_NAME-upgrade is -fully functional, do the real upgrade.

      -

    1. Take down the $OPENACS_SERVICE_NAME site and put -up a "down for maintenance" page.

    2. Repeat the upgrade with the most recent database

    3. 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.

      4. +database, to ake a new upgraded database called $OPENACS_SERVICE_NAME-upgrade. Now we +have a new website called $OPENACS_SERVICE_NAME-upgrade.

    4. Test the $OPENACS_SERVICE_NAME-upgrade site

    5. +

      If $OPENACS_SERVICE_NAME-upgrade is fully +functional, do the real upgrade.

        +

      1. Take down the $OPENACS_SERVICE_NAME site and put up a +"down for maintenance" page.

      2. Repeat the upgrade with the most recent database

      3. 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.