My favorites | Sign in
Project Home Downloads Wiki Issues Source
READ-ONLY: This project has been archived. For more information see this post.
Search
for

Index

Demo  
Updated Nov 14, 2011 by marcde...@gmail.com

Simple Demonstration

This page is a guided demo to show some of the features of ofver.

We will assume that the application we want to mantain(installation and upgrade procedures) using ofver is called application (yes, very imaginative... :)).

The ofver tool is meant to be used in the following manner:

  • application is being developed under a repository (Subversion, GIT, Mercurial...).
  • Stable releases of the application are always stored in a dedicated branch; i.e. stable. Note that ofver code evolves with the application code, either in the same branch or out of the branch (in other branches or in other repositories). Please check OFVER_IN_BRANCH flag for more details about this.

We are going to use google code project's Demo branch to simulate this "stable" branch of our application. Using tagged versions, upgrade will be possible emulation that we are releasing new versions of our applicaiton (check repo file under tools/ folder for jump emulation details).

In addition we are going to use in-branch mode, effectively meaning installation code (ofver code) is under the same branch as the application,

Starting... Some basics on ofver

First clone and checkout demoVersion1 tag:

marc@foix:~/# git clone https://code.google.com/p/ofver/ ofvertest
marc@foix:~/# cd ofvertest
marc@foix:~/# git checkout demoVersion1 #Note we are using tagged demoVersion1 to point to our first version

If you checked out correctly the contents of version file should should be 0.1:

marc@foix:~/ofvertest/application# cat version 
0.1

File structure

Now we can inspect a little bit the files:

marc@foix:~/ofvertest/application# tree -L 1
.
├── bin     #Would contain the binaries of our application
├── src     #Would contain the sources of our application
├── tools   #Contains ofver files for install and upgrade of the application
└── version #Special file that is used by ofver to know current branch code(src and bin) version.

The folder tools is, indeed, were all the files of ofver are placed (except version files, that we wil speak later) .

The structure of the ofver subtree is:

marc@foix:~/ofvertest/application/tools# tree -L 5
.
├── common    #ofver libraries
│   ├── commands
│   ├── init
│   ├── modules
│   ├── utils
│   └── versioning
├── log       #Folder that will store log files
├── ofver     #Executable
├── repo      #Script that must be filled with upgrade code for the ofver tool (either if using in-branch mode or not)
├── rescue    #Folder that will store backup files
├── settings  #Settings file :)
└── versions  #Application dependant installation and upgrade scripts
    ├── default
    │   ├── install
    │   │   ├── backup
    │   │   ├── install
    │   │   ├── lib
    │   │   ├── post-install-hook
    │   │   ├── pre-install-hook
    │   │   └── rollback
    │   └── upgrade
    │       └── default
    │           ├── backup
    │           ├── lib
    │           ├── post-upgrade-hook
    │           ├── pre-upgrade-hook
    │           ├── rollback
    │           └── upgrade
    └── version-checks

versions folder contains a specific structure with some predefined files in which installation and upgrade procedures can be written.

That means installation and upgrade have a predefined basic structure or workflow, broken down in several steps or modules:

  • Installation
    1. pre-install-hook
    2. install
    3. post-install-hook
  • Upgrade
    1. pre-upgrade-hook
    2. backup
    3. upgrade
    4. post-upgrade-hook

Both, installation and upgrade workflows may call rollback module in case of a severe error, in order to trigger a rollback mechanism.

Executable options

To see options of the commands:

marc@foix:~/ofvertest/application/tools# ./ofver -h

ofver v0.21 

Description: OFelia VERsioning system; a simple set of bash scripts to simplify 
repository based installations and upgrades.
Authorship: { marc.sune, leonardo.bergesio } @i2cat.net (i2CAT foundation)
Websites: http://code.google.com/p/ofver/, http://www.fp7-ofelia.eu


Usage: ofver {install upgrade} [options] 

         -h      Help and usage
         -d      Enable debug mode
         -n      Disable logging
         -b      Disable backup
         -f      Force mode. DO NOT USE 'Force mode' in PRODUCTION systems.

More information here

Testing installation (v0.1)

We will simulate now the installation of our application. Simply:

marc@foix:~/ofvertest/application/tools# ./ofver install

It will prompt for confirmation and after installation it will show a message of success. No magic ;)

Taking a closer look...

If you check now parent application folder, a new file has been created next to application/version file application/.currentVersion. This file stores current installed version, and allows ofver to dermine if installation/upgrades are possible. Current value should be no 0.1.

Now, check the following files:

marc@foix:~/ofvertest/application/tools/versions/default/install# tree
.
├── backup
├── install
├── lib
│   ├── dependencies
│   ├── procedure1
│   └── procedure2
├── post-install-hook
├── pre-install-hook
└── rollback

As you have seen we are under the default/install folder. The default folder contains standard or default installation procedures.

If you take a look at the content of these files, you will see that while installating, ofver has simply called the different scripts in the order previously mentioned.

However you can see in the content of install file, that instead of source bash function, a special function is used: loadModule function. We will comment it in depth afterwards, but loadModulelet's ofver load dynamically scripts or modules.

Upgrading v0.1 -> 0.2 (Standard upgrade)

Now we are going to do an standard upgrade. That means, all the procedures used will be "default" ones (hence located under versions/default/upgrade/default/ folder).

Upgrade workflow is quite simple.

  1. User triggers upgrade via "ofver upgrade"
  2. Backup module is called to create a backup of application data and whatever is needed(application/tools/versions/default/upgrade/default/backup content)
  3. ofver first upgrades his own code and restarts himself, to know how to proceed with the new code (if any). For doing so it uses the script application/tools/repo. note that for this demo, emulation is needed, but in most common cases this script will only contain something like git pull or svn update, for example.
  4. ofver will restart himself with the new code; now he nows what to do with the new version (if any).
  5. If in-branch mode is not used (hence application code is in another branch or repository), then ofver will try to update the code of the application using the script in: default/upgrade/default/repo.
  6. Real upgrade procedure is then triggered.

So, perform the upgrade by:

marc@foix:~/ofvertest/application/tools# ./ofver upgrade

You can check the content of the files under application/tools/versions/default/upgrade/default/ to check workflow followed.

Rollback mechanism

To demonstrate how rollback module is called, we are going to force an error on the upgrade.

Since we have already upgraded and we are under v0.2, ofver will not allow you to upgrade again, since installed version is the same as the latest repository version. For this reason we are going to use the flag force (-f).

But first let's introduce an error on the code. Edit the file: /tools/versions/default/upgrade/default/upgrade and add the following line at the end:

#Let's introduce an error                                                                    
/bin/false || error "Ups, there was an error!"

We also need, due to emulation of the update of ofver code, to temporally comment all the lines under tools/repo, effectively not letting him jump to next release.

Finally, let's force the upgrade:

marc@foix:~/ofvertest/application/tools# ./ofver upgrade -f

You will see that code in rollback is executed after procedure2. Using error function, automatically loads module rollback if parameter $NO_RESCUE is not present .

Upgrading v0.2 -> 0.3 (Customizing one step of the upgrade)

Before downloading 0.3 release from the repository, lets revert changes (checkout in git) the files that we have modified.

marc@foix:~/ofvertest/application/# git checkout -f

Now let's do the upgrade

marc@foix:~/ofvertest/application/tools# ./ofver upgrade

In this upgrade you will see that a non-default workflow is used. In this case, let's assume that after upgrade module we have to perform some extra actions in the case of upgrading to 0.3. Typically this could be some DB stuff or file management.

If you check the structure of the files now:

marc@foix:~/ofvertest/application/tools/versions# tree
.
├── 0.3
│   └── upgrade
│       └── default
│           └── post-upgrade-hook
├── default
│   ├── install
│   │   ├── backup
│   │   ├── install
│   │   ├── lib
│   │   │   ├── dependencies
│   │   │   ├── procedure1
│   │   │   └── procedure2
│   │   ├── post-install-hook
│   │   ├── pre-install-hook
│   │   └── rollback
│   ├── repo
│   └── upgrade
│       └── default
│           ├── backup
│           ├── lib
│           │   ├── dependencies
│           │   ├── procedure1
│           │   └── procedure2
│           ├── post-upgrade-hook
│           ├── pre-upgrade-hook
│           ├── repo
│           ├── rollback
│           └── upgrade
└── version-checks

You can see that a new folder structure 0.3/ has been created, containing the file 0.3/upgrade/default/post-upgrade-hook.

If you check the output of the upgrade, we can see that effectively ofver uses 0.3/upgrade/default/post-upgrade-hook file instead of default one only for this particular step of the workflow. Nothing more has been added or changed to modify the default workflow.

More about how to customize certain steps of an installation/upgrade

ofver uses loadModule function to load all modules or scripts (e.g. pre-install-hook module). This function has the following behaviour:

  1. In the case of an upgrade it tries to find a specific fromVersion->toVersion module script. If no file is found, it continues...
  2. In the case of an installation or upgrade it tries to find a specific toVersion module script. If no file is found, it continues...
  3. Uses default installation/upgrade module.

ofver expects to find files following this specific structure of folders:

versions/TARGETED_VERSION/install/MODULE_NAME                 #For installation
versions/TARGETED_VERSION/upgrade/CURRENT_VERSION/MODULE_NAME #For upgrades 

More about how to customize certain steps of an installation/upgrade

Examples:

#Specific post-install script for v0.2 installation
versions/0.2/install/post-install-hook
#Specific pre-upgrade script for upgrades from 0.1 version to 0.3                      
versions/0.3/upgrade/upgrade/0.1/pre-upgrade-hook
#Specific "upgrade" script for upgrades from any version to 0.5           
versions/0.5/upgrade/upgrade/default/upgrade      
#Specific "rollback" script for upgrades from any version to 0.5           
versions/0.5/upgrade/upgrade/default/rollback  

Can loadModule be used by modules itself?

Yes. If you use loadModule function in the default implementation of the modules, you will allow other installation/upgrade worflows to customize this small piece of the script (and yes is recursive, so in principle you can use loadModule wherever you want).

An example can be found under default installation and upgrade scripts of the example:

marc@foix:~/ofvertest/application/tools/versions# cat default/upgrade/default/upgrade 
...
#Calling procedure1 (will rollback in case of error)
loadModule lib/procedure1 

#Calling procedure2
loadModule lib/procedure2 

In this case default/upgrade/default/upgrade/lib/procedure1 file will be used if no other specific module is present (e.g. 0.2/upgrade/default/lib/procedure1 will override it for upgrades to 0.2 version).

Upgrading v0.3 -> 0.4 (Forbidden upgrade)

Finally try to upgrade to v0.4:

marc@foix:~/ofvertest/application/tools# ./ofver upgrade

You will see that a special file called forbidden is placed under 0.4/upgrade/0.3 folder. This file effectively forbids this particular upgrade.

marc@foix:~/ofvertest/application/tools/versions# tree
.
...
├── 0.4
│   └── upgrade
│       └── 0.3
│           └── forbidden
...

Unless you use force mode, this specific upgrade will not be allowed.

More...

This is the end of this demo. More information will be added soon :). You can contact us here

Powered by Google Project Hosting