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>
