APT Repository for RabbitMQ in Debian
=====================================

First, a note on what we're trying to do. We want a single "testing" 
repository. When RabbitMQ is more stable we will also want a 
"stable" repository. It is very important to understand that these refer 
to the state of the rabbit code, *NOT* which Debian distribution they go 
with. At the moment our dependencies are very simple so our packages can 
be used with any current Debian version (etch, lenny, sid) as well as 
with Ubuntu. So although we have a "testing" distribution, this is not 
codenamed "lenny". Instead it's currently codenamed "kitten" since 
that's a baby rabbit.

Secondly, a note on software. We need a tool to manage the repository, 
and a tool to perform uploads to the repository. Debian being Debian 
there are quite a few of each. We will use "rerepro" to manage the 
repository since it's modern, maintained, and fairly simple. We will use 
"dupload" to perform the uploads since it gives us the ability to run 
arbitrary commands after the upload, which means we don't need to run a 
cron job on the web server to process uploads.

Creating a repository
=====================

Much of this was cribbed from:
http://www.debian-administration.org/articles/286

The repository is fundamentally just some files in a folder, served over 
HTTP (or FTP etc). So let's make it "debian" in the root of 
www.rabbitmq.com. 

This means the repository will be at http://www.rabbitmq.com/debian/ and 
can be added to a sources.list as:

deb http://www.rabbitmq.com/debian/ testing main
deb-src http://www.rabbitmq.com/debian/ testing main

Inside this folder we need a "conf" folder, and in 
that we need a "distributions" configuration file - see the file in this 
folder. Note that:

* We list all architectures so that people can install rabbitmq-server 
  on to anything.
* We don't list the "all" architecture even though we use it; it's 
  implied.
* We only have a "main" component, we could have non-free and contrib 
  here if it was relevant.
* We list the email address associated with the key we want to use to 
  sign the repository. Yes, even after signing packages we still want to 
  sign the repository.

We're now ready to go. Assuming the path to our repository is /path, 
(and hence configuration is in /path/conf) we can upload a file to the 
repository (creating it in the process) by doing something like this on 
the repository host:

$ reprepro --ignore=wrongdistribution -Vb /path include kitten \
           rabbitmq-server_1.0.0-alpha-1_i386.changes

Note that we upload to the distribution "kitten" rather than "testing". 
We also pass --ignore=wrongdistribution since the current packages are 
built to go in "unstable" (this will be changed obviously).

Note also that the .changes file claims to be for i386 even though the 
package is for architecture "all". This is a bug in debhelper.

Finally, if you've just created a repository, you want to run:

$ reprepro -Vb /path createsymlinks

since this will create "kitten" -> "testing" symlinks. You only need to 
do this once.

Removing packages
=================

Fairly simple:

$ reprepro --ignore=wrongdistribution -Vb /path remove kitten \
           rabbitmq-server

Subsequent updates and "dupload"
================================

You can run the "reprepro" command above again to update the versions of 
software in the repository. Since we probably don't want to have to log 
into the machine in question to do this, we can use "dupload". This is a 
tool which uploads Debian packages. The supplied file "dupload.conf" can 
be renamed to ~/.dupload.conf. If you then run:

$ dupload -to rabbit --nomail .

in the folder with the .changes file, dupload will:

* create an incoming folder in your home directory on the repository 
machine
* upload everything there
* run reprepro to move the packages into the repository
* "rm -rf" the uploads folder

This is a bit cheesy but should be enough for our purposes. The 
dupload.conf uses scp and ssh so you need a public-key login (or tpye 
your password lots).

There's still an open question as to whether dupload is really needed 
for our case.

Keys and signing
================

We currently sign the package as we build it; but we also need to sign 
the repository. The key is currently on my machine (mrforgetful) and has 
ID 056E8E56. We should put it on CDs though.

reprepro will automatically sign the repository if we have the right 
SignWith line in the configuration, AND the secret key is installed on 
the repository server. This is obviously not ideal; not sure what the 
solution is right now.

You can export the public key with:

$ gpg --export --armor 056E8E56 > rabbit.pub

(Open question: do we want to get our key on subkeys.pgp.net?)

We can then add this key to the website and tell our users to import the 
key into apt with:

# apt-key add rabbit.pub

