Topic: Upgrading to Kete 1.1 Release

Topic type:

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.

An appendix to the Installation Guide


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

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.

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.

Discuss This Topic

There are 2 comments in this discussion.

Read and join this discussion

join this discussion

Creative Commons Attribution-Share Alike 3.0 New Zealand License
Upgrading to Kete 1.1 Release by Kieran P is licensed under a Creative Commons Attribution-Share Alike 3.0 New Zealand License