UPGRADING OPENINTERACT
========================================

This document has a few pointers for upgrading OpenInteract.

==============================
QUICK HELP
==============================

Most of the time, upgrading OpenInteract is as simple as:

 1) Running the Perl upgrade:

  > cd OpenInteract-1.xx/
  > perl Makefile.PL
  > make
  > make test
  > make install

This updates all the core OpenInteract:: modules to the versions
included with the distribution.

 2) Running the OpenInteract upgrade:

  > oi_manage upgrade --base_dir=/path/to/installation

from the directory where you unpacked the OpenInteract
distribution. This will upgrade all the core OpenInteract packages in
the base installation to the versions included with the distribution.

 3) Once you've done that, you can upgrade packages in the websites at
 your leisure.


==============================
GENERAL UPGRADE NOTES
==============================

Always read the 'Changes' file in this directory for more details
about changes between versions. 

If you have any problems, check the archives of the openinteract-help
mailing list at:

  http://www.geocrawler.com/lists/3/SourceForge/8429/0/

and if you don't find your solution there, mail the list at:

  openinteract-help@lists.sourceforge.net

--------------------
Server configuration:
--------------------

As we improve OpenInteract, we occasionally add new configuration
options to the 'server.perl' file. Since we have not yet developed a
utility to integrate these changes automatically, check here to see
what updates there have been between the versions.

==============================
UPGRADING TO 1.3
==============================

This is not as substantial as the upgrade to 1.2, but there are a
number of new features. These features come with some additional
configuration options which are all documented in 'Changes'.

The only required new configuration item is:

  {dir}{cache_tt} => '$BASE/cache/tt',

You'll also need to create this directory in any websites you're
upgrading. For websites created with 'oi_manage create_website' after
the upgrade, you will not need to create this directory.


==============================
UPGRADING TO 1.2
==============================

This is a substantial upgrade. Please read the following notes before
upgrading.

Briefly:

 - The way we use the Template Tolkit has drastically changed, but the
 interface is almost entirely the same. There is a script to migrate
 templates.

 - All templates must have an associated package now

 - There are a number of changes to the server configuration file.

 - All DBI objects need to derive from 'OpenInteract::SPOPS::DBI'
 rather than 'OpenInteract::SPOPS'

--------------------
Template changes:
--------------------

 - To translate all the old templates in one or more directories to
 new ones, run (from the source distribution directory):

     $ perl script/template_translate.pl directory [ directory, directory ]

   For instance:

     $ perl script/template_translate.pl /devel/pkg/mypkg/template

   All old templates are saved with a .old extension, new ones are
   saved under the old name.

 - All templates should be processed using
 'OpenInteract::Template::Process' instead of
 'OpenInteract::Template::Toolkit'. So older packages with something
 like:

   my $TMPL_CLASS = 'OpenInteract::Template::Toolkit';

   sub listing {
     ...
     return $TMPL_CLASS->handler( ... );
   }

 just change the first line to:

   my $TMPL_CLASS = 'OpenInteract::Template::Process';

 You can also delete the line and use (recommended):

   sub listing {
     ...
     return $R->template->handler( ... );
   }


 - You also need to pass BOTH the template name and package to the
 template processor:

     return $R->template->handler( ..., { db      => 'mytemplate',
                                          package => 'mypackage' } );

  You'll know you need to do this when you see an error like:

     Cannot process template!file error - Template
     (::mytemplate) is not in the website common directory and
     is not in the format 'package::name' at
     .../OpenInteract/Template/Process.pm line 45.
 

--------------------
Server configuration changes:
--------------------

 - There are a large number of changes to the server configuration, so
   it would probably be easiest to open up your existing server
   configuration and the sample configuration file
   side-by-side. (There are also documentation updates, which should
   help.) Copy over information from your existing configuration file
   to the sample, then save.

 - Add:

    {dir}{template} => '$BASE/template'

    You can store templates here specific to your website and refer to
    them by template name only.

 - Move:

    {db_info}

   to:

    {db_info}{main}

 - Add:

    {default_connection_db} => 'main'

 - If you're using LDAP, add:

    {default_connection_ldap} => 'main'
    {ldap_info}{main} => { ...params...}

 - Add:

    {cache}{template}{expires} => 900

 - If you're using MySQL as a session store, change:

     {system_alias}{'OpenInteract::Session::MySQL'} => [ 'session' ]

   to be:

     {system_alias}{'OpenInteract::Session::DBI'}   => [ 'session' ]


 - Add:

     {default_objects}{superuser}  => 1
     {default_objects}{supergroup} => 1

 - Add:

     {id}{user_type}  => 'int'
     {id}{group_type} => 'int'

    If you're using LDAP, use 'char' instead of 'int'


==============================
UPGRADING FROM 1.06 (AND EARLIER)
==============================

--------------------
Table schema changes (field renaming):

  sys_security:

     oid     --> object_id
     level   --> security_level

  object_track:

     oid     --> object_id


--------------------
Add the line:

  config_type  perl

to your 'conf/base.conf' file.

--------------------
In 'conf/server.perl'

Add the configuration keys:

  db_info => {
    sql_install   => '',
    long_read_len => 65536,
    long_trunc_ok => 0,
  }

Change the configuration key:

  system_alias => {
    'OpenInteract::Cookies' => [ qw/ cookies / ],
  }

to

  system_alias => {
    'OpenInteract::Cookies::Apache' => [ qw/ cookies / ],
  }

 

==============================
UPGRADING FROM 1.05 (AND EARLIER)
==============================

--------------------
SPOPS/MySQL changes:

If the website authors do not upgrade to the new packages and use the
'AUTO_INCREMENT' feature of MySQL, they need to add the following line
to the SPOPS configuration (conf/spops.conf in a package directory)
for each object:

  increment_field => 1,

The packages distributed with OpenInteract all have this change.


--------------------
Package Repository:

Version 1.06 and higher use an entirely different package repository
format, so you'll need to do some extra work. (Don't worry, it's not
much and you only need to do it once.)

To do the upgrade:

 1) Download the distribution.

 2) Do the normal Perl install:

  > cd OpenInteract-1.xx/
  > perl Makefile.PL
  > make
  > make test
  > make install

 3) Do the upgrade:

  > oi_manage upgrade --base_dir=/path/to/installation

The upgrade should tell you that it has upgraded the base installation
package repository to the new version. Now you need to upgrade the
package repository for all the websites:

  > oi_manage upgrade_website_repository --website_dir=/path/to/website

While this should be a seamless upgrade, you MUST restart the Apache
process to have the changes take effect.


========================================
$Id: UPGRADE,v 1.5 2001/10/15 05:38:01 lachoy Exp $