head	1.3;
access;
symbols;
locks; strict;
comment	@# @;


1.3
date	2001.07.10.23.50.20;	author stack;	state Exp;
branches;
next	1.2;

1.2
date	2001.06.04.20.14.44;	author edk;	state Exp;
branches;
next	1.1;

1.1
date	2001.06.04.20.12.48;	author edk;	state Exp;
branches;
next	;


desc
@@


1.3
log
@Note on in-situ_upgrade.pl.
@
text
@<h1>In-Situ Upgrades</h1>
<p>Ed Korthof</p>
<p>$Date$</p>
<h2>Overview</h2>
<p>In-Situ upgrades are done to an existing machine, without moving the data.
This document is a rough outline of how to do an in-situ upgrade; it includes
documentation for users and a technical design for how these may occur.

<p>The process of upgrading is one which needs to be automated; 
this document outlines a possible approach to automation.</p>


<h2>Status</h2>
<p>This is a draft document, subject to change during development.  It may
be useful for developers who are building tools to automate the upgrade
procedure.</p>  
<p>The script, <a href="http://helm.tigris.org/source/browse/helm/scripts/in-situ_upgrade.pl?rev=1">in-situ_upgrade.pl</a>, has been started to cover steps A-E outlined below; it needs 
work.</p>
<p></p>

<h2>Upgrade Steps</h2>
<p>The procedure for doing upgrades can be broken down into the following
steps.

<ol>
<li>Check for local modifications
        (make check-local-mods or scripts/find-local-mods)
        for now, this would check for differences in the following ways:
        <ul>
        <li>* cvs diff -u (see A below)
        <li>* check for changes to files generated by configure.pl and
            reconfigure.pl (see B below)
        <li>* check for differences between the conf files in each
            directory of the form $SANDBOX/*/conf -- and whether or not
            they're currently installed into the various directories.
            (this would check only *servlets*, *zone.properties*, and
            *httpd.conf*) (see C below)
        </ul>

<li>Update the applications to a different tag -- in the future, it
        might be possible to go either up or down, but for now probably only
        the former can be supported
        (NEWREV={TAG} make change-tag or scripts/change-sandbox-tag {NEWREV})
        for now, this would do the following operations:
        <ul>
        <li>* determine the old tag, and store it (see D below)
        <li>* cvs update (see E below)
        <li>* top level make in the sandbox (see F below)
        <li>* use the migration scripts to upgrade from the old tag to the
            new tag (see G below)
        </ul>
<li> qa the resulting installation (tools are needed to perform sanity checks)
</ol>

<h2>Implementation</h2>
<p>First, helm/Makefile and helm/data will be changed so that by
default, make install in helm will not install data into the data dir --
a separate target will be used for that (DONE -- but not everywhere.  Look
for a 'install-data' make target).

<p>Scripts will be created for each of the high level steps identified
above (STARTED. See <a href="http://helm.tigris.org/source/browse/helm/scripts/in-situ_upgrade.pl?rev=1">in-situ_upgrade.pl</a>).</p>

<p>
Here's psuedocode which I'd use for the steps named above, A-G -- all
ssume that env.sh has been sourced.  The implementation may well be in
perl, despite the fact that much of this psuedocode is sh scripting.

<h3>A : checking for changes via CVS</h3>
<pre>        # get OLDREVISION using step D -- store as $OLDREV
        CVS_OLD_TAG="TIGRIS_`echo $OLDREV| sed 's/\./_/g'`"
        cd $SANDBOX
        ( cvs diff -u -l ;
          for dir in * ; do if [ -d "$dir/CVS" ] ; then
                echo "CHECKING $dir" ; cd $dir ;
                cvs diff -u -r$OLDREV; cd .. ; fi ;
          done ) 2>&1 | # process for local modifications of any sort
</pre>

<h3>B : checking for changes to files generated by configure.pl and
    reconfigure.pl</h3>
<pre>        # Note that the items below assume configure.pl and
        # reconfigure.pl have the '--output-base' option.  Available
        # in the tigris cvs HEAD.
        #
        mkdir -p $SANDBOX/tmp/conftest
        $SANDBOX/scripts/configure.pl --output-base=$SANDBOX/tmp/conftest
        $SANDBOX/scripts/reconfigure.pl --base=$SANDBOX/tmp/conftest
        cd $SANDBOX/tmp/conftest
        FILES=`find . -type f -exec cmp -s {} ../tmp/{} \; -print`
        if [ "x$FILES" != "x" ] ; then
                echo "local changes in these files: $FILES"
                # exit with error
        fi
</pre>

<h3>C : checking for changes in the conf files which are used by
    reconfigure.pl (compared with the version in CVS dirs)</h3>
<pre>        cd $SANDBOX
        for dir in */conf ; do
                for base in servlets conf zone.properties ; do
                        for file in *$base *$base.in  ; do
                                # compare $file and
                                # $SANDBOX/conf/DIR/$file
                                # where DIR = $base or DIR = httpd.conf
                                # if $base == conf
                                # describe error if these don't match
                        done
                done
        done
</pre>

<h3>D : determining old tag </h3>
<pre>        OLDREV=`grep 'TIGRIS_VERSION=' $SANDBOX/conf/version.properties|
                sed 's/TIGRIS_VERSION=//'`
</pre>

<h3>E : updating to a new tag</h3>
<pre>        # assume NEWREV is of the form : X.Y.Z, eg 1.0.8
        CVS_NEW_TAG="TIGRIS_`echo $NEWREV | sed 's/\./_/g'`"
        cd $SANDBOX
        rm scripts/env.sh 
        ( cvs update -dP -r$CVS_NEW_TAG -l ;
          for dir in * ; do if [ -d "$dir/CVS" ] ; then
                echo "UPDATING $dir" ;
                cd $dir ; cvs update -dP -rCVS_NEW_TAG ; cd .. ; fi
          done ) 2>&1 | # process for errors
        cp $INSTANCE/env.sh scripts/
</pre>

<h3>F : top level make</h3>
<pre>        cd $SANDBOX
        make
</pre>

<h3>G : running migration scripts</h3>
<pre>        # assume NEWREV is of the form X.Y.Z, eg. 1.0.8
        cd $SANDBOX/helm/scripts
        ./upgrade_tigris $OLDREV $NEWREV
</pre>


<h2>Notes</h2>
Note that in step A, it is expected that there will be local changes to
env.sh.
<hr>
$Id$
@


1.2
log
@add some notes based on an initial pass through this procedure
@
text
@d1 3
a3 1
<h1>Upgrades</h1>
d5 2
a6 2
<p>Upgrades are done to an existing machine, without moving the data.
This document is a rough outline of how to do an upgrade; it includes
d9 3
a11 2
<p>The process of upgrading is one which needs to be automated; this
document outlines a possible approach to automation.
d16 4
a19 1
procedure.
d26 1
a26 1
<li> check for local modifications
d40 1
a40 1
<li> update the applications to a different tag -- in the future, it
d58 2
a59 1
a separate target will be used for that.
d62 1
a62 1
above.
d82 4
a85 2
<pre>        # note that the items below assume configure.pl and
        # reconfigure.pl have a few feature additions
d146 2
@


1.1
log
@add initial design proposal for upgrades
@
text
@d113 1
d119 1
d134 3
@

