Helga supports any number of versions on a single machine. This document describes the method by which to install and remove those versions.

This is necessary in a production environment, because new versions must be tested in the same setup as part of the upgrade process; it is unacceptable to have to "throw the switch" and hope that nothing breaks.

Installing a New Version of Helga

1. Pick a version name or #

If the name you pick is not a numbered version, you'll still also have to choose a number to represent it within Tcl, because the Tcl packaging system needs a number for commands like "package require". We'll use the name "dev" and the number 2.0 as an example.

2. Make a new branch in the file structure

Make a new branch of your File Structure underneath "dist", e.g. (/helga/dist/dev). To do this, you'll need to populate that folder with a version of Helga somehow: download a tar'd release, do a checkout from the svn repository, copy another folder under dist, svn export from another folder under dist.

3. Create a symlink for the Tcl shell

Create a new symlink so the Tcl shell can find the new version of the Helga Tcl libraries. This symlink should be created within /usr/share/tcltk, and point to the shell/lib folder of your Helga version. Though it doesn't matter what you call this symlink, a helpful convention is to name something similar to your version name so you can tell the symlinks apart later.

ln -s /helga/dist/dev/shell/lib /usr/share/tcltk/helgadev

4. Correct the Tcl packaging numbers

Change the version numbers in pkgIndex.tcl and helgaPkg.tcl. These files are responsible for providing the Helga Tcl package to the tcl shell. They are both located in shell/lib, the directory you just made a symlink pointing to. At the top of both files you will see lines making use of version number:

pkgIndex.tcl

package ifneeded helga 2.0 [list source [file join $dir helgaPkg.tcl]]

helgaPkg.tcl

package provide helga 2.0

The version number in each of those lines (2.0 in the above examples) must match the version number you've chosen for your new version.

5. Create a new database

The new version needs it own database as well. Most times you will want to begin using your current data right away in the new version of Helga. You can do this via a MySQL dump:

$ mysql -u root -p
mysql> CREATE DATABASE helgadev;
mysql> exit;
$ mysqldump -u root -p helga | mysql -u root -p helgadev

6. Allow the Helga users to access the new database

Give your MySQL users permissions on the new database. This includes all users: helgaGuest, helgaBasic, helgaAdvanced, and helgaAdmin. Remember to use their current passwords with IDENTIFIED BY, or you could lock everyone out of your database!

GRANT ALL PRIVILEGES ON helgadev.* TO helgaAdmin@'%' IDENTIFIED BY '<admin sql password>'

A script will be made available very soon to aid in setting more fine-grained permissions on the new database.

7. Create a new config file

Create a new configuration file in <helga root>/dist/conf. Name it the with the same base name as your version name, e.g. if your version is called dev, name it dev.conf. The new configuration file needs at least one value, HELGAVERSION:

HELGAVERSION=dev

And in most cases will need a second value, SQLDB, to point to the new database:

SQLDB=helgadev

8. Test out the Shell

Test the new version of the Helga Shell with "package require helga <version #>". The Tcl shell will only let you have one Helga version loaded at once, so if you are automatically loading a Helga version in ~/.tclshrc, you will need to disable that line before starting the Tcl shell. package require should return only the version number you chose, and nothing else.

$ tclsh
% package require helga 2.0
2.0
/>

9. Ensure helgatcp loads the right libraries

The helgatcp script is used by HelgaWeb to communicate with HelgaShell via TCP. It loads the Helga Tcl libraries via a "package require helga <version>". Especially if you've just copied this branch from a preexisting branch of yours, you should make sure this script loads the right version number of the Helga Tcl libraries.

package require helga 2.0

The version number in that line (2.0 in the above example) must match the version number you've chosen.

Every Helga script you write that uses a "package require helga" should explicitly specify a package version, or it will default to the highest version number present on your system.

10. Provide a path to the new Web version

Add a symlink to your Helga docroot so web users can navigate to the new branch. The symlink should point to the "web" folder directly under your newly-created "dist/<version>".

ln -s /helga/dist/dev/web /helga/public/dev

This would make your new HelgaWeb version available at http://<your server name>/dev

Removing a Version of Helga

Follow these steps to remove a version of Helga. The examples given would remove the same Helga version added in the "adding a version" examples above.

Important: only steps 1 and 2 are required to disable a version of Helga. You may stop at any point after step 2, leaving your files, data, and configuration intact.

1. Delete the Shell symlink

Delete the symlink that exposes your Helga Tcl libraries to the Tcl interpreter. This symlink is found in /usr/share/tcltk, and hopefully you named it something that makes it clear which version you're disabling.

rm /usr/share/tcltk/helgadev

2. Remove the Web symlink

Delete the symlink that provides a url through which Web users access this Helga version. This symlink is found in your Helga docroot.

rm /helga/public/dev

3. Delete the file branch

Delete the branch of the file structure under "dist" that contains your Helga version.

rm -rf /helga/dist/dev

4. Remove the database

Delete the database holding your Helga data. Be careful! Back up your data first if you need to:

mysqldump helgadev > helgadev_backup.sql

$ mysql -u root -p
mysql> DROP DATABASE helgadev;

5. Remove the configuration file

Remove the configuration file that provides overrides for that Helga version.

rm /helga/dist/conf/dev.conf