Setting up Umegaya
==================

Programs needed
---------------

 - Apache
 - Berkeley DB
 - curl
 - The following Perl modules:
   - BerkeleyDB
   - LWP
   - Mouse
   - YAML::XS
   - YAML::Appconfig

Configuration
-------------

 - Set up an Apache virtual host using the `umegaya.conf` file in
   `/etc/apache2/conf-available/`.
 - Set up a directory where Apache can write the `umegaya.db` Berkeley DB
   and optionally save a copy of the upstream, copyright and control files
   in the `packages-metatata` pool (by default in `/var/lib/umegaya`).
 - Make sure that the Umegaya administrator has also write access to the
   directory.
 - Umegaya finds the package's VCS using the `debcheckout` command of the
   devscripts package, so a `deb-src` line tracking Sid is necessary for a full
   coverage.  The [[!debpkg cron-apt]] package is useful to keep the apt cache
   up to date.

Triggering
----------

Umegaya is a passive system, that refreshes itself only when accessed.  It
can be kept up to date by systems that will access it when some resources
are refreshed, for intance commit hooks.

To refresh Umegaya for each package that has been uploaded to Debian,
subscribe to the [debian-devel-changes][] mailing list and pipe its messages to
umegaya-ddc-ping(1).

[debian-devel-changes]:	http://lists.debian.org/debian-devel-changes

Another way is to periodically access a list of selected packages.  For
instance, the script `umegaya-refresh-blends(1)` refreshes Umegaya for all
packages in Debian Pure Blends.  It is called by a daily cron job and can be
must be activated through the refresh_blends parameter in `/etc/umegaya/umegaya.conf`.

`umegaya-refresh-blends(1)` tries to guess the VCS URL packages that are not know
of debcheckout, using the layout policy of the blends.

The list of packages recommended by each blend overlap.  To avoid unnecessary
requests, the default refresh delay is set to one hour.  Alioth is never
queried when the last refresh was made within the refresh delay.

This (and below) assumes that the VCS name is the source package names.
This is true in theory, but in practice, a safeguard for errors may be
necessary.

To determine if a package managed with Git on Alioth contains a debian/upstream/metadata file.

    for repo in /git/debian-med/*.git
    do
      (cd $repo ; git ls-tree master debian/ |
       grep 'debian/upstream/metadata$' > /dev/null && echo "$repo")
    done | sed -e 's|/git/debian-med/||' -e 's|.git$||'


Accumulating the files on the local disk
----------------------------------------

Via the _store_files_ and _debian_control_ and _debian_copyright_ options,
umegaya can keep a local copy of the upstream, control and copyright files of
the packages, in the _db_dir_ directory.

The Debian package provides a pooled directory structure in `/var/lib/umegaya`,
but it needs to be created if another path is chosen.


Pushing these files to a remote Subversion server
-------------------------------------------------

Create a passwordless key, and restrict it to run only svnserve, as [explained
in the red bean book][svn-ssh-tricks].  Check out the repository in umegaya's
_db_dir_ (--force).  Commit from time to time.

[svn-ssh-tricks]: http://svnbook.red-bean.com/en/1.7/svn.serverconfig.svnserve.html#svn.serverconfig.svnserve.sshtricks


Notes about YAML
----------------

    # Invalid
    foo: bar:
    
    # Valid
    foo: "bar:"
    
    # Also valid
    foo: >
     bar:
    
    Also valid
    foo: |
     bar:

The difference between | and > is roughly the same as between the multi-line
and folded fields in Debian control files.
