Zero Install

Case study #1: packaging Contacts for Zero Install

This tutorial / case-study covers the following topics:

• Setting up a new Zero Install site.
• Building the archives to export with 0build.
• Uploading the archives to a web-server.
• Testing the site with Zero Install.
• Making updates to the site.

Contacts is simple address-book application. In this case study, we go though the process of making it available via Zero Install step-by-step. Contacts is a very easy program to start with because:

• It's written in Python, and so is platform independent.
• It doesn't have any hard-coded paths (doesn't expect to be in /usr, etc).
• It uses ROX-Lib, which is already in Zero Install.

The packages will be hosted on roxos.sunsite.dk, so we'll create a directory on our local machine to contain everything about this project (any name can be used). Inside, we'll make a directory for our working copy of the site (site), and a directory for the tar archives that get copied to the webserver (export). Inside site we create the directory structure that the user will see when they visit our site. We make an apps directory for all the applications on this site (we might later want lib and docs directories too, for example).

$ mkdir roxos.sunsite.dk
$ mkdir roxos.sunsite.dk/site
$ mkdir roxos.sunsite.dk/site/apps
$ mkdir roxos.sunsite.dk/export

We now create an apps/Contacts subdirectory for our application, and extract Contacts into it, renaming it to the correct version:

$ cd roxos.sunsite.dk/site/apps
$ mkdir Contacts
$ cd Contacts
$ tar xjf /path/to/Contacts.tar.bz2
$ mv Contacts Contacts-0.6.1

import pygtk; pygtk.require('2.0')
import findrox; findrox.version(1, 9, 6)
import rox

Now that we've set up the structure we want users to see, we'll run 0build to export it to the export directory:

$ alias 0build=/uri/0install/zero-install.sourceforge.net/bin/0build
$ cd roxos.sunsite.dk/site
$ 0build ../export roxos.sunsite.dk

You'll now be prompted to create a GPG key for the site. When you make updates to the site, you'll sign it with your key. When people refresh the site, Zero Install will check that the key is the same as the first time they accessed the site. You must create a key with exactly the name and email address 0build displays. GPG will also prompt for some other values; you may accept the defaults offered. In this case, the important values are:

Real name: Zero Install
Email address: 0install@roxos.sunsite.dk
Comment: (leave blank)

You only have to create the key once. After this is done, 0build will create some (hidden) files in the export directory. We now need to upload them to our web-server. We'll create a script to make this easier, which we'll save as roxos.sunsite.dk/0push:

#!/bin/bash
alias 0build=/uri/0install/zero-install.sourceforge.net/bin/0build
cd `dirname "$0"`
(cd site && 0build) || exit 1
rsync -av --delete --rsh="ssh -l fred" export/.0inst-{archives,index.tgz,index.tar.bz2} roxos.sunsite.dk:/path/to/htdocs/

Of course, you'll have to modify this for your setup. Change fred to your login name on the web-server, roxos.sunsite.dk to your site's name, and /path/to/htdocs/ to the root directory which your web-server exports. Then, run 0push to upload the files and try accessing your new site:

$ chmod a+x 0push
$ ./0push
$ cd /uri/0install/roxos.sunsite.dk

You should find that you see a copy of your site directory here, and you can run Contacts directly from it.

To make changes to your site, edit the site directory. We'll start by making it easier to run the current version. At the moment, apps/Contacts appears as a normal directory containing all the versions. Users often just want to run the latest version without having to change all their links on each upgrade. We'll create a latest symlink for this, and make apps/Contacts a wrapper application that runs latest:

$ cd roxos.sunsite.dk/site/apps/Contacts
$ ln -s Contacts-0.6.1 latest
$ ln -s latest/AppRun AppRun
$ ln -s latest/.DirIcon .DirIcon
$ ln -s latest/AppInfo.xml AppInfo.xml
$ ln -s latest/Help Help

Now Contacts appears as an application (to ROX-Filer users at least), which runs the latest version by default. Rerun 0push to send the updates to your webserver (you should keep the export directory around so that 0build can work out which archives actually need to be updated, rather than recreating everything), and use 0refresh to update your cache:

$ cd roxos.sunsite.dk
$ ./0push
$ cd /uri/0install/roxos.sunsite.dk
$ 0refresh