<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> <html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Upgrading the OpenACS files</title><link rel="stylesheet" href="openacs.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="upgrade.html" title="Chapter 5. Upgrading"><link rel="previous" href="upgrade-5-0-dot.html" title="Upgrading an OpenACS 5.0.0 or greater installation"><link rel="next" href="upgrade-supporting.html" title="Upgrading Platform components"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="upgrade-5-0-dot.html">Prev</a> </td><th width="60%" align="center">Chapter 5. Upgrading</th><td width="20%" align="right"> <a accesskey="n" href="upgrade-supporting.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="upgrade-openacs-files"></a>Upgrading the OpenACS files</h2></div></div><div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2979105"></a>Chosing a Method to Upgrade your Files</h3></div></div><div></div></div><p>OpenACS is distributed in many different ways: </p><div class="itemizedlist"><ul type="disc"><li><p>as a collection of files</p></li><li><p> as one big tarball</p></li><li><p> via CVS</p></li><li><p> via automatic download from within the APM (package manager)</p></li></ul></div><p> </p><p>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: <a href="upgrade-5-0-dot.html" title="Upgrading an OpenACS 5.0.0 or greater installation">Section , “Upgrading an OpenACS 5.0.0 or greater installation”</a> </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2979166"></a>Methods of upgrading OpenACS files</h3></div></div><div></div></div><div class="itemizedlist"><ul type="disc"><li><p><b>Upgrading files for a site which is not in a CVS repository. </b>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.</p><pre class="screen">[root root]# <b class="userinput"><tt>su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></tt></b> [$OPENACS_SERVICE_NAME aolserver]$ <b class="userinput"><tt>cd /var/lib/aolserver</tt></b> [$OPENACS_SERVICE_NAME web]$ <b class="userinput"><tt>tar xzf /var/tmp/openacs-5-1.tar.gz</tt></b> [$OPENACS_SERVICE_NAME web]$ <b class="userinput"><tt>cp -r openacs-5-1/* openacs-4</tt></b> [$OPENACS_SERVICE_NAME openacs-upgrade]$ <b class="userinput"><tt>exit</tt></b> [root root]# <span class="action"><span class="action">su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> cd /var/lib/aolserver tar xzf /var/tmp/openacs-5-1.tgz cp -r openacs-5-1/* openacs-4 exit</span></span></pre></li><li><p> <span class="strong">Upgrading files for a site in a private CVS repository</span> </p><p>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. </p><p>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.</p><div class="figure"><a name="id2979286"></a><p class="title"><b>Figure 5.2. Upgrading a local CVS repository</b></p><div class="mediaobject" align="center"><img src="../images/upgrade-cvs.png" align="middle" alt="Upgrading a local CVS repository"></div></div><div class="itemizedlist"><ul type="circle"><li><p><b>Step 0: Set up a working CVS checkout. </b>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.</p><p>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.</p><p>The <span class="replaceable"><span class="replaceable">openacs-5-1-compat</span></span> 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 <tt class="computeroutput">openacs-5-1-compat</tt>.</p><p>You will want to separately check out all the packages you are using. </p><pre class="screen">[root root]# <b class="userinput"><tt>su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></tt></b> [$OPENACS_SERVICE_NAME aolserver]$ <b class="userinput"><tt>cd /var/lib/aolserver</tt></b> [$OPENACS_SERVICE_NAME aolserver]$ <b class="userinput"><tt>cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot checkout -r <span class="replaceable"><span class="replaceable">openacs-5-1-compat</span></span> acs-core</tt></b> [$OPENACS_SERVICE_NAME aolserver]$ <b class="userinput"><tt>cd openacs-4/packages</tt></b> [$OPENACS_SERVICE_NAME aolserver]$ <b class="userinput"><tt>cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot checkout -r <span class="replaceable"><span class="replaceable">openacs-5-1-compat</span></span> <span class="replaceable"><span class="replaceable">packagename packagename2...</span></span></tt></b> [$OPENACS_SERVICE_NAME aolserver]$ <b class="userinput"><tt>cd ../..</tt></b> [$OPENACS_SERVICE_NAME aolserver]$ <b class="userinput"><tt>mv openacs-4 <span class="replaceable"><span class="replaceable">openacs-5-1</span></span></tt></b></pre><p>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. </p></li><li><p><b>Step 1: Import new OpenACS code. </b> </p><div class="itemizedlist"><ul type="disc"><li><p><b>Update CVS. </b>Update your local CVS working checkout (unless you just set it up). </p><pre class="screen">[root root]# <b class="userinput"><tt>su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></tt></b> [$OPENACS_SERVICE_NAME aolserver]$ <b class="userinput"><tt>cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">openacs-5-1</span></span></tt></b> [$OPENACS_SERVICE_NAME aolserver]$ <b class="userinput"><tt>cvs up -Pd ChangeLog *.txt bin etc tcl www packages/*</tt></b></pre></li><li><p><b>Update a single package via cvs working checkout. </b>You can add or upgrade a single package at a time, if you already have a cvs working directory.</p><pre class="screen">[root root]# <b class="userinput"><tt>su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></tt></b> [$OPENACS_SERVICE_NAME aolserver]$ <b class="userinput"><tt>cd /var/lib/aolserver/packages/<span class="replaceable"><span class="replaceable">openacs-5-1</span></span></tt></b> [$OPENACS_SERVICE_NAME openacs-5-1]$ <b class="userinput"><tt>cvs up -Pd <span class="replaceable"><span class="replaceable">packagename</span></span></tt></b></pre><p>In the next section, the import must be tailored to just this package.</p></li></ul></div></li><li><p><b>Step 2: Merge New OpenACS code. </b>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.</p><p>Import the new files into your cvs repository; where they match existing files, they will become the new version of the file.</p><pre class="screen">[$OPENACS_SERVICE_NAME openacs-5-1]$ <b class="userinput"><tt> cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">openacs-5-1</span></span></tt></b> [$OPENACS_SERVICE_NAME openacs-5-1]$ <b class="userinput"><tt> cvs -d /var/lib/cvs import -m "upgrade to OpenACS 5.1" <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> OpenACS <span class="replaceable"><span class="replaceable">openacs-5-1</span></span></tt></b> </pre><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>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 <tt class="computeroutput">myfirstpackage</tt> package.</p><pre class="screen">[root root]# <b class="userinput"><tt>su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></tt></b> [$OPENACS_SERVICE_NAME aolserver]$ <b class="userinput"><tt>cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">openacs-5-0</span></span>/package/<span class="replaceable"><span class="replaceable">myfirstpackage</span></span></tt></b> [$OPENACS_SERVICE_NAME myfirstpackage]$ <b class="userinput"><tt>cvs -d /var/lib/cvs/ import -m "importing package" <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/<span class="replaceable"><span class="replaceable">myfirstpackage</span></span> OpenACS openacs-5-1</tt></b></pre></div><p>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!</p><pre class="screen">[$OPENACS_SERVICE_NAME openacs-5.1]$ <b class="userinput"><tt> cd /var/lib/aolserver</tt></b> [$OPENACS_SERVICE_NAME tmp]$ <b class="userinput"><tt>rm -rf <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>-upgrade</tt></b> [$OPENACS_SERVICE_NAME tmp]$ <b class="userinput"><tt>mkdir <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>-upgrade</tt></b> [$OPENACS_SERVICE_NAME tmp]$ <b class="userinput"><tt>cvs checkout -d <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>-upgrade -jOpenACS:yesterday -jOpenACS -kk <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> > cvs.txt 2>&1</tt></b> (CVS feedback here)</pre><p>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 <tt class="computeroutput">M-x sort-lines</tt> (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.</p><p>Once you've fixed any conflicts, commit the new code to your local tree. </p><pre class="screen">[$OPENACS_SERVICE_NAME tmp]$ <b class="userinput"><tt>cd <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>-upgrade</tt></b> [$OPENACS_SERVICE_NAME <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>-upgrade]$ <b class="userinput"><tt>cvs commit -m "Upgraded to 5.1"</tt></b></pre></li><li><p><b>Step 3: Upgrade your local staging site. </b>Update your working tree with the new files. The CVS flags ensure that new directories are created and pruned directories destroyed.</p><pre class="screen">[$OPENACS_SERVICE_NAME <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>-upgrade]$ <b class="userinput"><tt>cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></tt></b> [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <b class="userinput"><tt>cvs up -Pd</tt></b> (CVS feedback) [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <b class="userinput"><tt>exit</tt></b> [root root]# </pre></li></ul></div></li></ul></div><p> <span class="strong">Upgrading files for a site using the OpenACS CVS repository (cvs.openacs.org)</span> </p><div class="orderedlist"><ol type="1"><li><pre class="screen">[$OPENACS_SERVICE_NAME ~]$ <b class="userinput"><tt>cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></tt></b> [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <b class="userinput"><tt>cvs up -Pd</tt></b> (CVS feedback) [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$</pre></li></ol></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2983117"></a>Upgrading a Production Site Safely</h3></div></div><div></div></div><p>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:</p><div class="orderedlist"><ol type="1"><li><p>Declare a freeze on new cvs updates - ie, you cannot run cvs update on the production site</p></li><li><p> Make a manual backup of the production site in addition to the automated backups</p></li><li><p>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 <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> 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.</p><p>Do step 2 above (merging conflicts in a <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>-upgrade working tree).</p></li><li><p> Manually resolve any conflicts in the working upgrade tree </p></li><li><p>Use the upgrade script and a recent backup of the production database, to ake a new upgraded database called <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>-upgrade. Now we have a new website called <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>-upgrade. </p></li><li><p> Test the <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>-upgrade site </p></li><li><p>If <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>-upgrade is fully functional, do the real upgrade.</p><div class="orderedlist"><ol type="a"><li><p>Take down the <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> site and put up a "down for maintenance" page.</p></li><li><p>Repeat the upgrade with the most recent database</p></li><li><p>Test the that the new site is functional. If so, change the upgraded site to respond to <span class="replaceable"><span class="replaceable">yourserver.net</span></span> requests. If not, bring the original production site back up and return to the merge.</p></li></ol></div></li></ol></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="upgrade-5-0-dot.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="upgrade-supporting.html">Next</a></td></tr><tr><td width="40%" align="left">Upgrading an OpenACS 5.0.0 or greater installation </td><td width="20%" align="center"><a accesskey="u" href="upgrade.html">Up</a></td><td width="40%" align="right"> Upgrading Platform components</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/current/upgrade-openacs-files.html#comments">View comments on this page at openacs.org</a></center></body></html>