================================================
Project ConVirt
ConVirt Packaging Guide

Copyright (c) 2009 - ConVirt contributors
================================================

I. Introduction
---------------

This document contains some helpful information for creating a 
redistributable, installable package for the ConVirt tool. It
is intended for use by community contributors looking to package 
ConVirt for their favourite distro.

**NOTE**: If you intend to, or are already maintaining a ConVirt package
for you distro, please be sure to let us know. We would love to place a
link to your distro on the website to ensure easy access and maximum 
benefit to the user community.  


II. Pre-Requisites
-------------------

The following packages are required for ConVirt to function properly
Please ensure that you check for these in your package's pre-req testing
phase. 

  * python >= 2.4
  * xen >= 3.0.4
  * python-gtk (called pygtk2 in some distros)
  * python-curses
  * vte
  * python-paramiko >= 1.6.4

In addition to these base requirements, please pay heed to any others 
specific to your distro and make sure you add them to you package.

**NOTE**: python-paramiko contains a critical bug that prevents
correct behaviour under some circumstances. The src tarball has the 
necessary patch under the ./patches directory. 


III. Source Package Layout
--------------------------

The source package has a fairly standard layout. The one thing of note
from the packaging perspective is the /distros directory ). As the name 
suggests, this directory contains all distro specific files, including 
the ones you will generate for your package. 

The source package already has directories for fedora and suse. Now, say
you are packaging for Ubuntu. You will first create a new directory named
'ubuntu' as a sibling to fedora and suse, then place all your work in that
directory. So, the new layout should look like: 

..distros/
		/fedora
		/suse
		/ubuntu

Typically, your distro's directory will contain a convirt.conf file geared to
your distro (more on this in Section V.) and any pre- or post- installation
scripts you may require for package deployment. 


IV. Deployment Layout
---------------------

As one might suspect, the source package's file structure differs
considerably from that of a fully installed package. Here is a typical
deployment mapping. You can use this as a guide to install the files in 
the appropriate locations for your distro. 

FORMAT: loc in src package  --> loc in deployment env.  (file permissions)


Directories: (don't forget to create them first)

/doc/*			-->	/usr/share/convirt/doc/		(0644)
/src/*			-->	/usr/share/convirt/src/		(0644)
/image_store/*		-->	/var/cache/convirt/image_store/	(0644)
/appliance_store/*	-->	/var/cache/convirt/appliance_store/	(0644)
/install/*		-->	/var/cache/convirt/install/	(0644)


Individual Files: 

install/client/distros/$DISTRO/convirt.conf -->  /etc/		(0644)


Critical File Permissions:

/usr/share/convirt/install/client/ConVirt		(0755)
/var/cache/convirt/image_store/*/provision.sh		(0744)
/var/cache/convirt/src/convirt/core/appliance/xen/provision.sh	(0744)


Other:

- create a symbolic link:
	/usr/bin/convirt --> /usr/share/convirt/install/client/ConVirt



V. Configuration
----------------

convirt.conf: 

ConVirt uses a consolidated configuration file called convirt.conf for 
critical information about the deployment and the host environment. As 
mentioned in Section III., you are responsible for providing this file fine
tuned for your distro under your distro's directory. 

**NOTE**  The easiest way to do this would be to copy one from an existing 
distro's directory and modify it to suit your environment.

Most of the entries in convirt.conf are fairly self explanatory and aren't 
expected to vary from distro to distro. However, a few merit some comments: 

  * PATHS/exec_path: As the name suggests, this is the PATH variable setting 
for all shell commands executed by ConVirt. Make sure it is set so the 
following executables are reachable on your distro:
	
	- lvcreate/lvremove/vgs		(the LVM executables)
	- xm, xentop			(the xen management tools)
	- uname 			(system info)

  * CLIENT CONFIGURATION/html_browser: Set this to the executable ConVirt 
should launch to view the html help documents. 


Image Store:

Since v0.5, convirt has had the ability to provision pre-packaged virtual
machine images through the Image Store feature. The source package contains 
a few default images; however, we highly recommend you consider packaging a 
provisionable virtual machine image appropriate to your distro. For more
details, please see the 'Image Builders Guide' available under the /doc 
directory.


VI. Process
-----------

As mentioned throughout our documentation and on the project website, we are 
relying on  community involvment to create the widest possible packaging 
coverage in terms of distro's supported. We hope that this document would help 
us achieve that goal. 

If you are interested in creating and/or maintaining a distros pecific 
package, please get in touch with us via the mailing list/forums/developer 
emails. Once we know about your interest/contribution, you can expect the 
following process: 

	1- A pre-release source package will be delivered to you  in enough 
time to allow repackaging and a coordinated release on all platforms.

	2- You will return a revised source package that'll include all your 
changes for the release under the /distro/$YOUR_DISTRO directory, and a 
pointer to wherever your downloadable package is located (if you need help 
with staging your package, please let us know ... we'll be glad to stage it 
for you).

	3- Upon release, the publically available source package will contain 
your contributions. The main download page at the ConVirt website will contain 
an acknowledgement and a link to a direct download of your package.



VII. Miscellany
---------------

At any and all times, we are available for help/feedback/criticism/suggestions.
Just visit the ConVirt website ( http://www.convirt.net/) and drop us a note in 
the mailing list, the forums or by email.