old.kete.net.nz :Documentation

Topic: Upgrading to Kete 1.1 Release

Topic type:
Topic

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

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

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

Parts of this topic assume that 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 havn'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.

Preliminary Notes

As of Kete 1.1 release, the tools used to manage the codebase (svn and piston) have been combined into one very useful tool called Git. As a result, to upgrade to 1.1 will require a few extra steps. Particularly moving from Svn to Git for your codebase's repository in the Production deployment 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.

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
$ mongrel_rails cluster::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.1 release. Clone the 1.1 release from Github with

$ git clone git://github.com/kete/kete.git your_app
$ cd your_app
$ git checkout --track -b 1-1-stable origin/1-1-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/mongrel_cluster.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

backgroundrb.yml has changed in this release, so you'll need to run the following again to get the new settings, then edit config/background.rb to suit your system

$ cp config/backgroundrb.yml.example config/backgroundrb.yml

If you have made any other alterations to Kete's 1.0 codebase, such as template changes, now is the time to merge them in. 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. We install specific versions of packet and libxml-ruby because we know they work. Run (as root)

root@host: # gem uninstall packet --all
root@host: # gem install packet --version=0.1.7
root@host: # gem install chronic
root@host: # gem uninstall libxml-ruby --all
root@host: # gem install libxml-ruby --version=0.6.0

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
$ RAILS_ENV=production ./script/backgroundrb start
$ mongrel_rails cluster::start
$ 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.

Deployment Upgrade - Type 1

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-1-stable origin/1-1-stable
$ git pull
$ cp ../your_app_backup/config/database.yml config
$ cp ../your_app_backup/config/mongrel_cluster.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.

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

set :mongrel_servers, 1
set :mongrel_port, 8000
set :mongrel_environment, 'production'
set :mongrel_address, '127.0.0.1'
set :mongrel_conf, "/etc/mongrel_cluster/#{application}.yml"

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. We install specific versions of packet and libxml-ruby because we know they work.

$ cd /home/kete/apps/your_app/current/
$ RAILS_ENV=production script/backgroundrb stop
$ mongrel_rails cluster::stop -C /etc/mongrel_cluster/your_app.yml

$ gem uninstall packet --all
$ gem install packet --version=0.1.7
$ gem install chronic
$ gem uninstall libxml-ruby --all
$ gem install libxml-ruby --version=0.6.0

$ rake db:migrate RAILS_ENV=production
$ rake kete:upgrade RAILS_ENV=production
$ RAILS_ENV=production script/backgroundrb start
$ mongrel_rails cluster::start -C /etc/mongrel_cluster/your_app.yml
$ 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.

Deployment Upgrade - Type 2

You can use git-svn to migrate and update your codebase, but that it outside the scop of this upgrade guide for now. Check out the Git documentation on how to do this, and post a comment here if you were able to do so successfully.

Kieran P

was the last to edit Upgrading to Kete 1.1 Release

on May 15th, 2009 at 2:17 PM

Kieran P

created Upgrading to Kete 1.1 Release

on Aug 13th, 2008 at 12:17 PM

Flag as:

Discuss This Topic

There are 2 comments in this discussion.

Read and join this discussion

Walter McGinnis

said If rake db:migrate fails with Mysql::Error

If you run into a problem during the "rake db:migrate" step with an error that looks like this:

Mysql::Error: Unknown column 'baskets.show_privacy_controls' in 'where clause': SELECT count(*) AS count_all FROM `baskets`     WHERE (`baskets`.`show_privacy_controls` = 1)

There is a pretty simple workaround, but it requires you to edit a source code file and then restore it. Start by backing up the unaltered file from the command line:

$ cp app/models/basket.rb app/models/basket.rb.bak

Then open up app/models/basket.rb with your favorite editor and comment out (add a # at beginning of the line) lines 34, 36, and 429:

...
# named_scope :should_show_privacy_controls, :conditions => { :show_privacy_controls => true }
...
# @@privacy_exists = (Basket.should_show_privacy_controls.count > 0)
...
# @@privacy_exists = (Basket.should_show_privacy_controls.count > 0)

Save the file, then run the "rake db:migrate" step. When that is done, restore the original basket.rb file, like so:

$ mv app/models/basket.rb.bak app/models/basket.rb

Then return to the rest of the steps in the upgrade.

Tags: upgrade, Kete, 1.1, rake db:migrate, basket.rb

Flag as:

Posted on August 30th, 2008 at 8:25 PM

Walter McGinnis

said Re: if you get rake kete:upgrade fails with "No such file or directory... zebradb/bootstrap.xml.erb"

Edit: As of Kete 1.2, the capistrano deployment scripts now copy these files to the correct location, so you no longer need to do it yourself.

You are probably doing a capistrano deployment, for reasons that are too long to get into here, the zebradb directory isn't updated when you do a source code upgrade under this circumstance. However, several files under zebradb have been added or updated in 1.1 vs 1.0 and need to copied into place. Here's how (assuming you start out in /home/kete/apps/your_app/current):

$ cd ..
$ cp shared/cached-copy/zebradb/bootstrap.xml.erb current/zebradb/
$ cp shared/cached-copy/zebradb/tab/bib1.att current/zebradb/tab/
$ cp shared/cached-copy/zebradb/conf/oai2index.xsl current/zebradb/conf/
$ cp shared/cached-copy/zebradb/conf/cql2pqf.txt current/zebradb/conf/
$ cd current

Then rerun the "rake kete:upgrade" step and proceed with rest of upgrade procedure.

Tags: Kete, 1.1, upgrade, Zebra, zebradb, rake kete:upgrade

Flag as:

Posted on August 30th, 2008 at 8:36 PM

join this discussion