Kete.net.nz: Documentation

Topic: Upgrading to Kete 1.0 Release Branch

Topic Type: Topic

Notes on how to upgrade your pre-1.0 Kete to the 1.0 stable release branch.

Outdated. New upgrade guide available at Upgrading to Kete 1.1 Release

Originally written by Walter McGinnis, Kete Project Lead for Katipo Communications, Ltd.

An appendix to the Installation Guide

This assumes that you having been using the setup outlined in "Optional Bestpractices - Managing your Kete application's codebase and deploying it to a production host".

This also assumes that you are on your development machine (unless noted). It's recommended that you run through the upgrade on a development Kete installation of your project, check that it works, then run through your deployment to production. You will need to repeat some steps on your production deployment. They will be noted.

Preparation

Make sure your supporting software is up to date. See the "Installing Required Software" topic for your platform in the Installation Guide and double-check that your environment for where you are going to run Kete matches (i.e. both your development host and your production host). Of particular importance is that RubyGems, Rake, Rails, and Mongrel are updated.

Update your codebase to use the latest Kete or Kete 1.0 Stable Release Branch

We currently use Piston to manage importing the Kete codebase into specific projects' version control repositories (though we are seriously considering Git, if want to take it upon yourself to show us how, please create a related topic about how to do so).

Piston is a program that wraps up specific functionality of Subversion called Vendor Branch Management which that handles cleanly importing third party vendors' code, in this case the Kete software's code, into a project so that you can customize it to suit your needs.

First, you need to apply a patch to Piston to make it handle version control "adds and deletes" a bit better. The patch can be found at http://rubyforge.org/tracker/index.php?func=detail&aid=16698&group_id=2105&atid=8179.

On Mac OS X 10.5.x the file you will need to patch is found at /Library/Ruby/Gems/1.8/gems/piston-1.3.3/lib/piston/command.rb, in Debian Etch it is /var/lib/gems/1.8/gems/piston-1.3.3/lib/piston/command.rb.

Important Note: Even with the patch, if your project is running a quite old version of Kete, the following command may abort with failures caused by missing files or directories. Usually rerunning the command until if finishes successfully will work.

Move into a subversion checkout of your project's code where you include the full directory structure, including the "trunk" directory, etc. Then run a piston update.

$ cd ~/apps/your_app # this should contain a trunk directory...
$ piston update # this is the command you may have to run several times, can be VERY SLOW
...

After you get through to a successful piston update, commit your update of the latest Kete code to your project's version control.

$ svn commit -m "importing the latest Kete code into the project"
...

Optional: Now that Kete has a stable release branch, you probably want to switch to that rather than taking your chances with the Kete trunk which may be unstable at any given time.

$ piston switch http://svn.kete.net.nz/projects/kete/branches/1-0-stable trunk # may also be VERY SLOW
...
$ svn commit -m "switching to the stable 1.0 release branch of Kete"
...

Upgrade Kete

From here on out, you will need to do these steps first for development, then on your production host after a Capistrano deployment. Make note of the steps for production...

For a production deployment, first do this from your development environment to update your code base:

$ cd trunk # should be in apps/your_app/trunk on development host
$ cap deploy:update # maybe prompted for passwords...
...

Now that we have the Kete code we need, there are some additional steps that Kete will need to be set up right.

Note: the steps below are in your RAILS_ROOT of your application. If you have followed the steps above and in the Installation Guide , this is something like apps/your_app/trunk of development and apps/your_app/current for a Capistrano deployment on your production host.

Make sure we have all the ruby gems we need:

$ rake manage_gems:required:install
...

We've updated to use a later version of the Backgroundrb Ruby on Rails plugin, you may need to do the steps outlined in this topic to configure your config/backgroundrb.yml correctly. Do that if necessary and then continue.

Next up is making sure our database's schema is up to date. Do this for a development Kete:

$ rake db:migrate
...

or this for a production Kete:

$ rake db:migrate RAILS_ENV=production
...

Kete now includes handy upgrade program that will do things like add the correct data to your database that it needs. Do this for a development Kete:

$ rake kete:upgrade
...

or this for a production Kete:

$ rake kete:upgrade RAILS_ENV=production
...

Additional Steps ONLY for production deployment:

If you didn't have a themes directory before, you'll need to copy the apps/your_app/shared/cached_copy/public/themes/* to your_app/shared/system/themes/ by hand the first time after the upgrade. Like so:

$ cd ~/apps/your_app/shared
$ cp -r cached_copy/public/themes/* system/themes/

You'll also need to make sure that backgroundrb is set up right. If you haven't done it for production yet, do the steps in this topic and then do this:

$ cd ~/apps/your_app
$ cp current/config/backgroundrb.yml shared/config/

Finishing up and updating your site's configuration (For both development and production deployment)

Now restart your site's Kete server as outlined in this topic for production, or do a "cap deploy:restart" from your development machine to restart your production site.

There are probably a number of System Settings that have been added to Kete since your last upgrade. Go to your site, log in as a user with the tech admin role, click on "reconfigure site" from the Administrator's Toolbox at the bottom of any page. Click the "Advanced Options" link on the resulting page. Run through the various sections and make the appropriate changes.

Restart your site again for your changes to take effect.