upgrade.xml
Delivered as text/xml
[ hide source ]
File Contents
<?xml version='1.0' ?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [ <!ENTITY % myvars SYSTEM "../variables.ent"> %myvars; ]> <chapter id="upgrade"> <title>Upgrading</title> <authorblurb> <para>by <ulink url="mailto:joel@aufrecht.org">Joel Aufrecht</ulink></para> </authorblurb> <sect1 id="upgrade-overview"> <title>Overview</title> <para>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.</para> <para>If all of these conditions are true:</para> <itemizedlist> <listitem> <para>Your OpenACS Core is 5.0.0 or later</para> </listitem> <listitem> <para>You do not keep your OpenACS site in a local CVS repository</para> </listitem> <listitem> <para>You do not have any custom code</para> </listitem> </itemizedlist> <para>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:</para> <orderedlist> <listitem> <para>Browse to the <ulink url="/acs-admin/install/">Installer</ulink>.</para> </listitem> <listitem> <para>Click install or upgrade under "Install from OpenACS Repository" and select the packages to install or upgrade.</para> </listitem> <listitem> <para>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.</para> </listitem> </orderedlist> <figure> <title>Upgrading with the APM</title> <mediaobject> <imageobject> <imagedata fileref="images/upgrade-apm.png" format="PNG" align="center"/> </imageobject> </mediaobject> </figure> <para>It's always a good idea to precede an upgrade attempt with a <link linkend="snapshot-backup">snapshot backup</link>.</para> <table> <title>Assumptions in this section</title> <tgroup cols="2"> <tbody> <row> <entry>name of OpenACS user</entry> <entry><replaceable>$OPENACS_SERVICE_NAME</replaceable></entry> </row> <row> <entry>OpenACS server name</entry> <entry><replaceable>$OPENACS_SERVICE_NAME</replaceable></entry> </row> <row> <entry>Root of OpenACS file tree</entry> <entry><replaceable>/var/lib/aolserver/$OPENACS_SERVICE_NAME</replaceable></entry> </row> <row> <entry>Database backup directory</entry> <entry><replaceable>/var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup</replaceable></entry> </row> </tbody> </tgroup> </table> </sect1> <sect1 id="upgrade-4.5-to-4.6"> <title>Upgrading 4.5 or higher to 4.6.3</title> <indexterm> <primary>upgrade</primary> <secondary>OpenACS 4.5 to 4.6.x</secondary> <tertiary>Linux/Unix</tertiary> </indexterm> <para>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. </para> <para>If upgrading from 4.4, you need to manually run acs-kernel/sql/postgres/upgrade-4.4-4.5.sql. See <ulink url="http://openacs.org/bugtracker/openacs/bug?bug_number=632">Bug #632</ulink></para> <itemizedlist mark="circle"> <listitem><para>A computer with OpenACS 4.5.</para> </listitem> <listitem><para><ulink url="http://openacs.org/projects/openacs/download/">OpenACS 4.6 tarball</ulink> or CVS checkout/export.</para> </listitem> <listitem><para>Required for Full Text Search on PostgreSQL: <ulink url="http://openfts.sourceforge.net">OpenFTS 0.3.2</ulink></para> </listitem> </itemizedlist> <orderedlist> <listitem> <formalpara> <title>Make a Backup</title> <para>Back up the database and filesystem (see <xref linkend="snapshot-backup"/>).</para> </formalpara> </listitem> <listitem> <formalpara> <title>OPTIONAL: Upgrade OpenFTS</title> <para><xref linkend="upgrade-openfts-0.2-to-0.3.2"/></para> </formalpara> </listitem> <listitem> <para> Stop the server </para> <screen>[root root]# <userinput>svc -d /service/<replaceable>$OPENACS_SERVICE_NAME</replaceable></userinput></screen> </listitem> <listitem> <formalpara> <title>Upgrade the filesystem</title> <para><xref linkend="upgrade-openacs-files"/></para> </formalpara> </listitem> <listitem> <para> <emphasis role="strong">Start the server</emphasis> </para> <screen>[root root]# <userinput>svc -u /service/<replaceable>$OPENACS_SERVICE_NAME</replaceable></userinput></screen> </listitem> <listitem> <formalpara id="upgrade-with-apm"> <title>Use APM to upgrade the database</title> <para></para> </formalpara> <orderedlist> <listitem> <para>Browse to the package manager, <computeroutput>http://<replaceable>yourserver</replaceable>/acs-admin/apm</computeroutput>.</para> </listitem> <listitem> <para>Click <computeroutput><guilabel>Install packages.</guilabel></computeroutput></para> </listitem> <listitem> <para>Select the packages you want to install. This should be everything that says <computeroutput>upgrade</computeroutput>, 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.</para> </listitem> <listitem> <para>On the next screen, click <computeroutput><guibutton>Install Packages</guibutton></computeroutput></para> </listitem> <listitem> <para>When prompted, restart the server:</para> <screen>[root root]# <userinput>restart-aolserver <replaceable>$OPENACS_SERVICE_NAME</replaceable></userinput></screen> </listitem> <listitem> <para>Wait a minute, then browse to the package manager, <computeroutput>http://<replaceable>yourserver</replaceable>/acs-admin/apm</computeroutput>.</para> </listitem> <listitem> <para>Check that the kernel upgrade worked by clicking <computeroutput><guilabel>All</guilabel></computeroutput> and making sure that <computeroutput>acs-kernel</computeroutput> version is &version;.</para> </listitem> </orderedlist> </listitem> <listitem> <formalpara> <title>Rollback</title> <para>If anything goes wrong, <link linkend="recovery">roll back</link> to the backup snapshot.</para> </formalpara> </listitem> </orderedlist> </sect1> <sect1 id="upgrade-4.6.3-to-5"> <title>Upgrading OpenACS 4.6.3 to 5.0</title> <itemizedlist> <listitem> <formalpara> <title>Oracle</title> <para>This forum posting documents <ulink url="http://openacs.org/forums/message-view?message_id=201394"> how to upgrade an Oracle installation from OpenACS 4.6.3 to 5 </ulink>. </para> </formalpara> </listitem> <listitem> <formalpara> <title>PostgreSQL</title> <para>You must use PostgreSQL 7.3.x or newer to upgrade OpenACS beyond 4.6.3. See <link linkend="upgrade-postgres-7.2-to-7.3">Upgrade PostgreSQL to 7.3</link>; <xref linkend="compatibility-matrix"/> </para> </formalpara> <orderedlist> <listitem> <para><link linkend="snapshot-backup">Back up the database and filesystem.</link></para> </listitem> <listitem> <formalpara> <title>Upgrade the filesystem for packages/acs-kernel</title> <para><xref linkend="upgrade-openacs-files"/></para> </formalpara> </listitem> <listitem> <para>Upgrade the kernel manually. (There is a script to do most of the rest: <ulink url="http://cvs.openacs.org/browse/OpenACS/openacs-4/contrib/misc/upgrade_4.6_to_5.0.sh?r=1.6">/contrib/misc/upgrade_4.6_to_5.0.sh on HEAD</ulink>). You'll still have to do a lot of stuff manually, but automated trial and error is much more fun.)</para> <screen>[root root]# <userinput>su - <replaceable>$OPENACS_SERVICE_NAME</replaceable></userinput> [$OPENACS_SERVICE_NAME aolserver]$ <userinput>cd /var/lib/aolserver/ <replaceable>$OPENACS_SERVICE_NAME</replaceable>/packages/acs-kernel/sql/postgresql/upgrade</userinput></screen> <para> Manually execute each of the upgrade scripts in sequence, either from within psql or from the command line with commands such as <computeroutput><userinput>psql -f upgrade-4.6.3-4.6.4.sql <replaceable>$OPENACS_SERVICE_NAME</replaceable></userinput></computeroutput>. Run the scripts in this order (order is tentative, not verified): </para> <programlisting>psql -f upgrade-4.6.3-4.6.4.sql <replaceable>$OPENACS_SERVICE_NAME</replaceable> psql -f upgrade-4.6.4-4.6.5.sql <replaceable>$OPENACS_SERVICE_NAME</replaceable> psql -f upgrade-4.6.5-4.6.6.sql <replaceable>$OPENACS_SERVICE_NAME</replaceable> psql -f upgrade-4.7d-4.7.2d.sql <replaceable>$OPENACS_SERVICE_NAME</replaceable> psql -f upgrade-4.7.2d-5.0d.sql <replaceable>$OPENACS_SERVICE_NAME</replaceable> psql -f upgrade-5.0d-5.0d2.sql <replaceable>$OPENACS_SERVICE_NAME</replaceable> psql -f upgrade-5.0d2-5.0d3.sql <replaceable>$OPENACS_SERVICE_NAME</replaceable> psql -f upgrade-5.0d6-5.0d7.sql <replaceable>$OPENACS_SERVICE_NAME</replaceable> psql -f upgrade-5.0d7-5.0d9.sql <replaceable>$OPENACS_SERVICE_NAME</replaceable> psql -f upgrade-5.0d11-5.0d12.sql <replaceable>$OPENACS_SERVICE_NAME</replaceable> psql -f upgrade-5.0.0a4-5.0.0a5.sql <replaceable>$OPENACS_SERVICE_NAME</replaceable> psql -f upgrade-5.0.0b1-5.0.0b2.sql <replaceable>$OPENACS_SERVICE_NAME</replaceable> psql -f upgrade-5.0.0b2-5.0.0b3.sql <replaceable>$OPENACS_SERVICE_NAME</replaceable> psql -f upgrade-5.0.0b3-5.0.0b4.sql <replaceable>$OPENACS_SERVICE_NAME</replaceable></programlisting> </listitem> <listitem> <para>Upgrade ACS Service Contracts manually:</para> <screen>[$OPENACS_SERVICE_NAME aolserver]$ <userinput>cd /var/lib/aolserver/ <replaceable>$OPENACS_SERVICE_NAME</replaceable>/packages/acs-service-contracts/sql/postgresql/upgrade</userinput> psql -f upgrade-4.7d2-4.7d3.sql <replaceable>$OPENACS_SERVICE_NAME</replaceable> </screen> </listitem> <listitem> <para>Load acs-authentication data model.</para> <screen><userinput>psql -f /var/lib/aolserver/<replaceable>$OPENACS_SERVICE_NAME</replaceable>/openacs-5/packages/acs-authentication/sql/postgresql/acs-authentication-create.sql <replaceable>$OPENACS_SERVICE_NAME</replaceable></userinput></screen> </listitem> <listitem> <para>Load acs-lang data model.</para> <screen><userinput>psql -f /var/lib/aolserver/<replaceable>$OPENACS_SERVICE_NAME</replaceable>/packages/acs-lang/sql/postgresql/acs-lang-create.sql <replaceable>$OPENACS_SERVICE_NAME</replaceable></userinput></screen> </listitem> <listitem> <para>(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 <replaceable>$OPENACS_SERVICE_NAME</replaceable>/tcl/zzz-postload.tcl containing:</para> <programlisting>if {![apm_package_installed_p acs-lang]} { apm_package_install -enable -mount_path acs-lang $::acs::rootdir/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::rootdir/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 }</programlisting> </listitem> <listitem> <para>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. </para> </listitem> <listitem> <para>Upgrade other packages <link linkend="upgrade-with-apm">via the APM</link></para> </listitem> </orderedlist> <para> See also these forum posts: <ulink url="http://openacs.org/forums/message-view?message_id=143497">Forum OpenACS Development: 4.6.3 upgrade to 5-HEAD: final results</ulink>, <ulink url="http://openacs.org/forums/message-view?message_id=152200">OpenACS 5.0 Upgrade Experiences</ulink>.</para> <para> 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. </para> </listitem> </itemizedlist> </sect1> <sect1 id="upgrade-5-0-dot"> <title>Upgrading an OpenACS 5.0.0 or greater installation</title> <itemizedlist> <listitem> <formalpara> <title>Upgrading a stock site</title> <para>If you have no custom code, and your site is not in a CVS repository, upgrade with these steps:</para> </formalpara> <orderedlist> <listitem> <para>Go to <ulink url="/acs-admin/install">/acs-admin/install/</ulink> and click "Upgrade Your System" in "Install from OpenACS Repository"</para> </listitem> <listitem> <para>Select all of the packages you want to upgrade and proceed</para> </listitem> <listitem> <para>After upgrade is complete, restart the server as indicated.</para> </listitem> <listitem> <para>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.</para> </listitem> </orderedlist> </listitem> <listitem> <formalpara> <title>Upgrading a Custom or CVS site</title> <para>If you have custom code, and your site is in a CVS repository, upgrade with these steps:</para> </formalpara> <orderedlist> <listitem> <formalpara> <title>Upgrade the filesystem for all packages in use</title> <para><xref linkend="upgrade-openacs-files"/></para> </formalpara> </listitem> <listitem> <para>Go to <ulink url="/acs-admin/install">/acs-admin/install/</ulink> and click "Upgrade Your System" in "Install from local filesystem"</para> </listitem> <listitem> <para>Select all of the packages you want to upgrade and proceed</para> </listitem> <listitem> <para>After upgrade is complete, restart the server as indicated.</para> </listitem> <listitem> <para>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.</para> </listitem> </orderedlist> </listitem> </itemizedlist> </sect1> <sect1 id="upgrade-openacs-files"> <title>Upgrading the OpenACS files</title> <sect2> <title>Choosing a Method to Upgrade your Files</title> <para>OpenACS is distributed in many different ways: <itemizedlist> <listitem><para>as a collection of files</para></listitem> <listitem><para> as one big tarball</para></listitem> <listitem><para> via CVS</para></listitem> <listitem><para> via automatic download from within the APM (package manager)</para></listitem> </itemizedlist> </para> <para>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 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: <xref linkend="upgrade-5-0-dot"/> </para> </sect2> <sect2> <title>Methods of upgrading OpenACS files</title> <itemizedlist> <listitem> <formalpara> <title>Upgrading files for a site which is not in a CVS repository</title> <para>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.</para> </formalpara> <screen>[root root]# <userinput>su - <replaceable>$OPENACS_SERVICE_NAME</replaceable></userinput> [$OPENACS_SERVICE_NAME aolserver]$ <userinput>cd /var/lib/aolserver</userinput> [$OPENACS_SERVICE_NAME web]$ <userinput>tar xzf /var/tmp/openacs-5-1.tar.gz</userinput> [$OPENACS_SERVICE_NAME web]$ <userinput>cp -r openacs-5-1/* openacs-4</userinput> [$OPENACS_SERVICE_NAME openacs-upgrade]$ <userinput>exit</userinput> [root root]# <action>su - <replaceable>$OPENACS_SERVICE_NAME</replaceable> cd /var/lib/aolserver tar xzf /var/tmp/openacs-5-1.tgz cp -r openacs-5-1/* openacs-4 exit</action></screen> </listitem> <listitem> <para> <emphasis role="strong">Upgrading files for a site in a private CVS repository</emphasis> </para> <para>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. </para> <para>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.</para> <figure> <title>Upgrading a local CVS repository</title> <mediaobject> <imageobject> <imagedata fileref="images/upgrade-cvs.png" format="PNG" align="center"/> </imageobject> </mediaobject> </figure> <itemizedlist> <listitem> <formalpara> <title>Step 0: Set up a working CVS checkout</title> <para>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.</para> </formalpara> <para>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.</para> <para>The <replaceable>openacs-5-1-compat</replaceable> 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 <computeroutput>openacs-5-1-compat</computeroutput>.</para> <para>You will want to separately check out all the packages you are using. </para> <screen>[root root]# <userinput>su - <replaceable>$OPENACS_SERVICE_NAME</replaceable></userinput> [$OPENACS_SERVICE_NAME aolserver]$ <userinput>cd /var/lib/aolserver</userinput> [$OPENACS_SERVICE_NAME aolserver]$ <userinput>cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot checkout -r <replaceable>openacs-5-1-compat</replaceable> acs-core</userinput> [$OPENACS_SERVICE_NAME aolserver]$ <userinput>cd openacs-4/packages</userinput> [$OPENACS_SERVICE_NAME aolserver]$ <userinput>cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot checkout -r <replaceable>openacs-5-1-compat</replaceable> <replaceable>packagename packagename2...</replaceable></userinput> [$OPENACS_SERVICE_NAME aolserver]$ <userinput>cd ../..</userinput> [$OPENACS_SERVICE_NAME aolserver]$ <userinput>mv openacs-4 <replaceable>openacs-5-1</replaceable></userinput></screen> <para>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. </para> </listitem> <listitem> <formalpara> <title>Step 1: Import new OpenACS code</title> <para> <itemizedlist> <listitem> <formalpara> <title>Update CVS</title> <para>Update your local CVS working checkout (unless you just set it up). </para> </formalpara> <screen>[root root]# <userinput>su - <replaceable>$OPENACS_SERVICE_NAME</replaceable></userinput> [$OPENACS_SERVICE_NAME aolserver]$ <userinput>cd /var/lib/aolserver/<replaceable>openacs-5-1</replaceable></userinput> [$OPENACS_SERVICE_NAME aolserver]$ <userinput>cvs up -Pd ChangeLog *.txt bin etc Tcl www packages/*</userinput></screen> </listitem> <listitem> <formalpara> <title>Update a single package via cvs working checkout</title> <para>You can add or upgrade a single package at a time, if you already have a cvs working directory.</para> </formalpara> <screen>[root root]# <userinput>su - <replaceable>$OPENACS_SERVICE_NAME</replaceable></userinput> [$OPENACS_SERVICE_NAME aolserver]$ <userinput>cd /var/lib/aolserver/packages/<replaceable>openacs-5-1</replaceable></userinput> [$OPENACS_SERVICE_NAME openacs-5-1]$ <userinput>cvs up -Pd <replaceable>packagename</replaceable></userinput></screen> <para>In the next section, the import must be tailored to just this package.</para> </listitem> </itemizedlist></para> </formalpara> </listitem> <listitem> <formalpara> <title>Step 2: Merge New OpenACS code</title> <para>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.</para> </formalpara> <para>Import the new files into your cvs repository; where they match existing files, they will become the new version of the file.</para> <screen>[$OPENACS_SERVICE_NAME openacs-5-1]$ <userinput> cd /var/lib/aolserver/<replaceable>openacs-5-1</replaceable></userinput> [$OPENACS_SERVICE_NAME openacs-5-1]$ <userinput> cvs -d /var/lib/cvs import -m "upgrade to OpenACS 5.1" <replaceable>$OPENACS_SERVICE_NAME</replaceable> OpenACS <replaceable>openacs-5-1</replaceable></userinput> </screen> <tip> <para>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 <computeroutput>myfirstpackage</computeroutput> package.</para> <screen>[root root]# <userinput>su - <replaceable>$OPENACS_SERVICE_NAME</replaceable></userinput> [$OPENACS_SERVICE_NAME aolserver]$ <userinput>cd /var/lib/aolserver/<replaceable>openacs-5-0</replaceable>/package/<replaceable>myfirstpackage</replaceable></userinput> [$OPENACS_SERVICE_NAME myfirstpackage]$ <userinput>cvs -d /var/lib/cvs/ import -m "importing package" <replaceable>$OPENACS_SERVICE_NAME</replaceable>/packages/<replaceable>myfirstpackage</replaceable> OpenACS openacs-5-1</userinput></screen> </tip> <para>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!</para> <screen>[$OPENACS_SERVICE_NAME openacs-5.1]$ <userinput> cd /var/lib/aolserver</userinput> [$OPENACS_SERVICE_NAME tmp]$ <userinput>rm -rf <replaceable>$OPENACS_SERVICE_NAME</replaceable>-upgrade</userinput> [$OPENACS_SERVICE_NAME tmp]$ <userinput>mkdir <replaceable>$OPENACS_SERVICE_NAME</replaceable>-upgrade</userinput> [$OPENACS_SERVICE_NAME tmp]$ <userinput>cvs checkout -d <replaceable>$OPENACS_SERVICE_NAME</replaceable>-upgrade -jOpenACS:yesterday -jOpenACS -kk <replaceable>$OPENACS_SERVICE_NAME</replaceable> > cvs.txt 2>&1</userinput> (CVS feedback here)</screen> <para>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 <computeroutput>M-x sort-lines</computeroutput> (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.</para> <para>Once you've fixed any conflicts, commit the new code to your local tree. </para> <screen>[$OPENACS_SERVICE_NAME tmp]$ <userinput>cd <replaceable>$OPENACS_SERVICE_NAME</replaceable>-upgrade</userinput> [$OPENACS_SERVICE_NAME <replaceable>$OPENACS_SERVICE_NAME</replaceable>-upgrade]$ <userinput>cvs commit -m "Upgraded to 5.1"</userinput></screen> </listitem> <listitem> <formalpara> <title>Step 3: Upgrade your local staging site</title> <para>Update your working tree with the new files. The CVS flags ensure that new directories are created and pruned directories destroyed.</para> </formalpara> <screen>[$OPENACS_SERVICE_NAME <replaceable>$OPENACS_SERVICE_NAME</replaceable>-upgrade]$ <userinput>cd /var/lib/aolserver/<replaceable>$OPENACS_SERVICE_NAME</replaceable></userinput> [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <userinput>cvs up -Pd</userinput> (CVS feedback) [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <userinput>exit</userinput> [root root]# </screen> </listitem> </itemizedlist> </listitem> </itemizedlist> <para> <emphasis role="strong">Upgrading files for a site using the OpenACS CVS repository (cvs.openacs.org)</emphasis> </para> <orderedlist> <listitem> <screen>[$OPENACS_SERVICE_NAME ~]$ <userinput>cd /var/lib/aolserver/<replaceable>$OPENACS_SERVICE_NAME</replaceable></userinput> [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <userinput>cvs up -Pd</userinput> (CVS feedback) [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$</screen> </listitem> </orderedlist> </sect2> <sect2> <title>Upgrading a Production Site Safely</title> <para>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:</para> <orderedlist> <listitem> <para>Declare a freeze on new cvs updates - ie, you cannot run cvs update on the production site</para> </listitem> <listitem> <para> Make a manual backup of the production site in addition to the automated backups</para> </listitem> <listitem> <para>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 <replaceable>$OPENACS_SERVICE_NAME</replaceable> 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.</para> <para>Do step 2 above (merging conflicts in a <replaceable>$OPENACS_SERVICE_NAME</replaceable>-upgrade working tree).</para> </listitem> <listitem> <para> Manually resolve any conflicts in the working upgrade tree </para> </listitem> <listitem> <para>Use the upgrade script and a recent backup of the production database, to ake a new upgraded database called <replaceable>$OPENACS_SERVICE_NAME</replaceable>-upgrade. Now we have a new website called <replaceable>$OPENACS_SERVICE_NAME</replaceable>-upgrade. </para> </listitem> <listitem> <para> Test the <replaceable>$OPENACS_SERVICE_NAME</replaceable>-upgrade site </para> </listitem> <listitem> <para>If <replaceable>$OPENACS_SERVICE_NAME</replaceable>-upgrade is fully functional, do the real upgrade.</para> <orderedlist> <listitem> <para>Take down the <replaceable>$OPENACS_SERVICE_NAME</replaceable> site and put up a "down for maintenance" page.</para> </listitem> <listitem> <para>Repeat the upgrade with the most recent database</para> </listitem> <listitem> <para>Test the that the new site is functional. If so, change the upgraded site to respond to <replaceable>yourserver.net</replaceable> requests. If not, bring the original production site back up and return to the merge.</para> </listitem> </orderedlist> </listitem> </orderedlist> </sect2> </sect1> <sect1 id="upgrade-supporting"> <title>Upgrading Platform components</title> <sect2 id="upgrade-openfts-0.2-to-0.3.2"> <title>Upgrading OpenFTS from 0.2 to 0.3.2</title> <para>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.</para> <orderedlist> <listitem> <para>Uninstall the old OpenFTS Engine from the <replaceable>$OPENACS_SERVICE_NAME</replaceable> database.</para> <orderedlist> <listitem><para><emphasis role='bold'>Browse to <computeroutput>http://<replaceable>yourserver</replaceable>/openfts</computeroutput>.</emphasis> </para> </listitem> <listitem><para><emphasis role='bold'>Click <computeroutput><guilabel>Administration</guilabel></computeroutput>.</emphasis></para> </listitem> <listitem><para><emphasis role='bold'>Click <computeroutput><guibutton>Drop OpenFTS Engine</guibutton></computeroutput></emphasis></para> </listitem> </orderedlist> </listitem> <listitem> <para>Build and install the new OpenFTS driver and supporting Tcl procedures. (This section of shell code is not fully documented; please exercise care.)</para> <screen>cd /usr/local/src/ tar xzf /var/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 </screen> <para> Back up the old fts driver as a precaution and install the newly compiled one</para> <screen>mv /usr/local/aolserver/bin/nsfts.so /usr/local/aolserver/bin/nsfts-0.2.so cp nsfts.so /usr/local/aolserver/bin </screen> <para>Build and install the OpenFTS code for PostgreSQL</para> <screen>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</screen> <para>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.</para> <screen>[root root]# <userinput>su - <replaceable>$OPENACS_SERVICE_NAME</replaceable></userinput> [$OPENACS_SERVICE_NAME dev]$ <userinput>psql <replaceable>$OPENACS_SERVICE_NAME</replaceable> -f /usr/local/pgsql/share/contrib/openfts.sql</userinput> CREATE CREATE [$OPENACS_SERVICE_NAME dev]$ <userinput>psql <replaceable>$OPENACS_SERVICE_NAME</replaceable> -f /usr/local/src/postgresql-7.2.3/contrib/tsearch/tsearch.sql</userinput> BEGIN CREATE (~30 more lines) [$OPENACS_SERVICE_NAME dev]$ <userinput>exit</userinput> [root root]# <action>su - <replaceable>$OPENACS_SERVICE_NAME</replaceable> psql <replaceable>$OPENACS_SERVICE_NAME</replaceable> -f /usr/local/pgsql/share/contrib/openfts.sql psql <replaceable>$OPENACS_SERVICE_NAME</replaceable> -f /usr/local/src/postgresql-7.2.3/contrib/tsearch/tsearch.sql exit</action></screen> </listitem> <listitem> <formalpara> <title>OPTIONAL: Install the new OpenFTS Engine.</title> <para>If you want to upgrade the OpenFTS Engine, do these steps. (You must have already upgraded the OpenFTS driver to 0.3.2.)</para> </formalpara> <orderedlist> <listitem> <para>Browse to <computeroutput>http://<replaceable>yourserver</replaceable>/admin/site-map</computeroutput></para> </listitem> <listitem> <para>On the <computeroutput>openfts</computeroutput> line, click on <computeroutput><guilabel>set parameters</guilabel></computeroutput>.</para> </listitem> <listitem> <para>Change the value of <computeroutput>openfts_tcl_src_path</computeroutput> from <computeroutput>/usr/local/src/Search-OpenFTS-tcl-0.2/</computeroutput> to <computeroutput>/usr/local/src/Search-OpenFTS-tcl-0.3.2/</computeroutput></para> </listitem> <listitem> <para>Click <computeroutput><guibutton>Set Parameters</guibutton></computeroutput></para> </listitem> <listitem> <screen>[root root]# restart-aolserver <replaceable>$OPENACS_SERVICE_NAME</replaceable></screen> </listitem> <listitem> <para>Browse to <computeroutput>http://<replaceable>yourserver</replaceable>/openfts</computeroutput></para> </listitem> <listitem><para><emphasis role='bold'>Click <computeroutput><guilabel>Administration</guilabel></computeroutput>.</emphasis></para> </listitem> <listitem><para><emphasis role='bold'>Click <computeroutput><guibutton>Initialize OpenFTS Engine</guibutton></computeroutput></emphasis></para> </listitem> </orderedlist> </listitem> </orderedlist> </sect2> <sect2 id="upgrade-postgres-7.2-to-7.3"> <title>Upgrading from PostgreSQL 7.2 to 7.3</title> <para>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.</para> <para> 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 <computeroutput>/var/lib/aolserver/<replaceable>$OPENACS_SERVICE_NAME</replaceable>/bin/pg_7.2to7.3_upgrade_helper.pl</computeroutput> on the dump file, and reply the dump. See <ulink url="http://openacs.org/forums/message-view?message_id=109337">Forum OpenACS Q&A: PG 7.2->7.3 upgrade gotcha?</ulink>. Example:</para> <orderedlist> <listitem> <para>Back up the database as per <xref linkend="postgres-snapshot-backup"/>.</para> </listitem> <listitem> <para>Run the upgrade script on the backup file.</para> <screen>[root root]# <userinput>su - <replaceable>$OPENACS_SERVICE_NAME</replaceable></userinput> [$OPENACS_SERVICE_NAME <replaceable>$OPENACS_SERVICE_NAME</replaceable>]# <userinput>cd /var/lib/aolserver/<replaceable>$OPENACS_SERVICE_NAME</replaceable>/bin</userinput> [$OPENACS_SERVICE_NAME bin]$ <userinput>./pg_7.2to7.3_upgrade_helper.pl \ ../database-backup/nightly.dmp \ ../database-backup/upgrade-7.3.dmp \ /var/lib/aolserver/<replaceable>$OPENACS_SERVICE_NAME</replaceable></userinput> ================================================================== 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 <emphasis>(many lines omitted)</emphasis> [$OPENACS_SERVICE_NAME bin]$ </screen> </listitem> <listitem> <para>Use perl to replace <computeroutput>timestamp</computeroutput> with <computeroutput>timestamptz</computeroutput> in the dump file. See example perl code in step two in <ulink url="http://cvs.openacs.org/browse/OpenACS/openacs-4/contrib/misc/upgrade_4.6_to_5.0.sh?r=1.6">/contrib/misc/upgrade_4.6_to_5.0.sh</ulink></para> </listitem> <listitem> <para>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 <computeroutput>export PGPORT=5434</computeroutput> to the .bashrc and/or .bash_profile for the postgres73 user. </para> </listitem> <listitem> <para>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.</para> </listitem> <listitem> <para>Change the path in <replaceable>$OPENACS_SERVICE_NAME</replaceable>'s .bashrc or .bash_profile (or both) files to reflect the new postgres73 user directory. Also add in the PGPORT.</para> </listitem> <listitem> <para>Restore the database from dump as per the <link linkend="restore-postgres">recovery instructions</link>.</para> </listitem> </orderedlist> </sect2> </sect1> </chapter>