old.kete.net.nz :Documentation

Topic: Upgrading to Kete 1.2 Release

Topic type:
Topic

Notes on how to upgrade your 1.1 Kete to the 1.2 stable release.

Originally written by Kieran Pilkington, Kete Developer for Katipo Communications, Ltd.

Preliminary Notes

This guide assumes you have used Apache and Passenger for your hosting. If you're still using mongrel, we SERIOUSLY recommend you switch to Passenger. All the most recent documentation is aimed at Passenger based installation. Mongrel users should use history links in documentation to find their relevant steps.

Also, when you see 'RAILS_ENV=production' in the commands to run in the console, these tell the script to execute in production mode. If you're running a copy of Kete in development mode, leave this part of the command off.

Upgrade steps necessary for all machines that you host Kete 1.2 on (Simple Upgrade or Best Practices Deployment guides)

YAZ/Zebra Upgrade

We updated Kete to work with the latest versions of YAZ and Zebra. However, this does make previous versions of Kete unable to use older versions (backwards incompatible), so to use Kete 1.2, you'll need to upgrade. It's fairly easy to though. I'm going to use debian examples here. If you use another OS, check the install guide for instructions on how to do this.

First, uninstall any previous versions of Zebra/Yaz from your system. When you run 'zebrasrv' or 'yaz-client', they shouldn't be executable. Then, add the following lines to /etc/apt/sources.list

deb http://ftp.indexdata.dk/debian etch main
deb-src http://ftp.indexdata.dk/debian etch main

Then run the following apt-get command to install the latest Zebra/Yaz

root@host: # apt-get update
root@host: # apt-get install yaz libyaz3-dev idzebra-2.0 libidzebra-2.0 libidzebra-2.0-dev libidzebra-2.0-modules curl libcurl3-dev

Finally, you have to rebuild the zoom gem:

root@host: # gem uninstall zoom
root@host: # gem install zoom

Other Software Updates

If you plan on using embedded meta data harvesting in your application, you will also need to run the following:

root@host: # apt-get install libimage-exiftool-perl
root@host: # gem install mini_exiftool

This finishes the required software upgrades needed on each machine you host Kete 1.2 on. Now continue on with Kete side of the upgrade.

Simple Upgrade

If you didn't follow the 'Best Practices' section of the documentation, and deployed manually, then you'll want to follow these steps. If you did, skip down to the next section. The first step is to shut down your existing Kete setup to free the ports for the new one. Run the following on the machine hosting your Kete setup.

$ cd /path/to/your/your_app
$ ./script/backgroundrb stop

Now backup all of your data, so if something goes wrong, it's fairly easy to revert back to what you had. In the directory of your live application, run the following:

$ mysqldump -u [your_app_database_user] -p [your_app_production_database] > your_app_backup/kete_production_backup.sql
$ cd ../
$ mv your_app your_app_backup

When this is done, you can now grab the 1.2 release. Clone the 1.2 release from Github with

$ git clone git://github.com/kete/kete.git your_app
$ cd your_app
$ git checkout --track -b 1-2-stable origin/1-2-stable
$ git pull

Now pull your config files from your backup into your new app.

$ cp ../your_app_backup/config/database.yml config
$ cp ../your_app_backup/config/backgroundrb.yml config
$ cp ../your_app_backup/zebradb/keteaccess zebradb
$ cp ../your_app_backup/zebradb/conf/kete-zebra-servers.xml zebradb/conf
$ cp -r ../your_app_backup/public/audio public
$ cp -r ../your_app_backup/public/documents public
$ cp -r ../your_app_backup/public/image_files public
$ cp -r ../your_app_backup/public/video public
$ cp -r ../your_app_backup/public/themes public

If you have made any other alterations to Kete's 1.1 codebase, such as template changes, now is the time to merge them in. The default theme has also changed, most notably support for rounded corners (better compatability with IE6). So if you have any other themes besides the default, you'll need to pull rounded_corners.css from the default stylesheets directory into each of you custom themes. When thats done, we can carry on.

You may also want to set the local Timezone that is displayed to your users. See the topic at http://old.kete.net.nz/documentation/topics/show/184-configuring-kete-for-your-timezone for details and then return to this guide and proceed.

Lets install the gems that might be missing from this release.

root@host: # rake manage_gems:required:install

And we're up to date system wise. Now to update our database, and start things up again. Run the following

$ rake db:migrate RAILS_ENV=production
$ rake kete:upgrade RAILS_ENV=production
$ script/backgroundrb start
$ touch tmp/restart.txt
$ rake tmp:cache:clear

Now fire up your application in your browser, and navigate to the homepage. If it works, continue on, otherwise, run over the steps again. See if you missed anything. If you still can't get it working, post a comment on this topic describing your problem. Upload log/production.log somewhere and post a link to it along with your comment.

At this point you can optionally set up your site to use content licensing. Check out http://old.kete.net.nz/documentation/topics/show/181-using-content-licenses-in-kete-11 for that procedure and work on that before doing the next step.

If you see the homepage successfully, login as the default administrator account or a user that has the tech admin role, click "Rebuild search databases" in the "Administrators Toolbox", use the default settings except check the box for "skip private records", and click "Rebuild Search Records". If all goes well, your Kete upgrade should now be complete. Report any problems in a comment within this topic.

The steps below are for those of you having been using the setup outlined in "Optional Best practices - 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.

Finally, it also assumes you haven't made any alterations to Kete that you need to port over. If you have, do this right after having updated your codebase in the sections below.

Deployment Upgrade

If you use Capistrano for deployment, then why not switch to Git with us! Its fairly easy to do so. Lets get a Git repo up and running first. Login to the host you'll use to store the repository and run

$ cd /path/to/repos
$ mkdir your_app.git
$ cd your_app.git
$ git --bare init --shared=group

Then logout and on your development/local machine, run the following:

$ svn export svn://your_svn_repo_url/trunk ~/your_app_backup
$ git clone git://github.com/kete/kete.git ~/your_app
$ cd ~/your_app
$ git checkout --track -b 1-2-stable origin/1-2-stable
$ git pull
$ cp ../your_app_backup/config/database.yml config
$ cp ../your_app_backup/config/backgroundrb.yml config
$ cp ../your_app_backup/zebradb/keteaccess zebradb
$ cp ../your_app_backup/zebradb/conf/kete-zebra-servers.xml zebradb/conf

Now merge in any changes you made to the SVN source code such as templates or themes. The default theme has also changed, most notably support for rounded corners (better compatability with IE6). So if you have any other themes besides the default, you'll need to pull rounded_corners.css from the default stylesheets directory into each of you custom themes.

Once thats done, edit your config/deploy.rb file to use the new git repo path like so:set :application, "your_app"

set :repository,  "your_server:/path/to/repos/#{application}.git"

set :scm, :git
set :branch, "master"
set :scm_username, "kete"
set :scm_password, "kete_pass"

role :app, "www.your_server.com"
role :web, "www.your_server.com"
role :db,  "www.your_server.com", :primary => true

set :deploy_to, "/home/kete/apps/#{application}"
set :user, "kete"
set :group, "kete"
set :config_files, []
set :deploy_via, :remote_cache

Now commit all changes and once done, push them to your new Git repo.

$ git add -f .
$ git commit -m "initial import"
$ git remote rm origin
$ git remote add origin ssh://your_server/path/to/repos/your_app.git
$ git push origin master
$ rm -rf ~/your_app_backup

And now follow through with your regular deployment proceedures.

$ cap deploy:update
....
....
 ** transaction: commit

If you encountered problems, look over your deploy.rb file to make sure you have the right settings, make sure you have your ssh keys in the target host users authorized_keys files.

Once done, login to user on the host you just deployed to. We have to setup symlinks to the config files.

$ cd /home/kete/apps/your_app/current/config
$ ln -s /home/kete/apps/your_app/shared/config/database.yml
$ ln -s /home/kete/apps/your_app/shared/config/backgroundrb.yml

And now we can finish the update.

$ cd /home/kete/apps/your_app/current/
$ script/backgroundrb stop
$ sudo rake manage_gems:required:install
$ rake db:migrate RAILS_ENV=production
$ rake kete:upgrade RAILS_ENV=production
$ script/backgroundrb start
$ touch tmp/restart.txt
$ rake tmp:cache:clear

If you see the homepage successfully, login as the default administrator account or a user that has the tech admin role, click "Rebuild search databases" in the "Administrators Toolbox", leave the default settings, and click "Rebuild Search Records". If all goes well, your Kete upgrade should now be complete. Report any problems in a comment within this topic.