root/trunk/hotstuff/installation.txt

Hotstuff installation instructions
==================================

This guide contains complete installation instructions for the Hotstuff
sources. It is highly recommended to install Hotstuff from binary packages
(e.g. on Debian) since installation from source is not trivial and requires
some care.
In this guide, the installation instructions of dependencies and additional
servers are also given for installing from source, since this might be
requires whenever a piece of software is not available.

Step 0: install Hotstuff
------------------------

If not yet done, all Hotstuff scripts and manual pages should
be installed. A simple Makefile is included so calling 'make install'
should be sufficient. This will put all of Hotstuff into directories
under the /usr/local hierarchy. If this is not wanted, modify the Makefile
first.

If the system is new, do not forget to install tools such as less, vim,
make, subversion and the like.

Step 1: install PostgreSQL
--------------------------

Currently, only PostgreSQL is supported as the database server. On most
distributions, it is available as a pre-configured package. In case it isn't,
it can be installed from scratch:

% wget ftp://ftp5.es.postgresql.org/mirror/postgresql/source/ \
  v8.0.3/postgresql-base-8.0.3.tar.bz2
% tar xvjf postgresql-base-8.0.3.tar.bz2
% ./configure --prefix=~/postgresql
% make && make install

A database can then be initialised with the following commands:

% export PATH=~/postgresql/bin:$PATH
% export PGDATA=~/postgresql/var
% initdb
% postmaster

Hotstuff needs a dedicated database. Its setup will be described in
the next step.

Step 2: configure PostgreSQL
----------------------------

The database must be created first. This used to require the setup of a
database and a user for it, and its initialisation with SQL schema files.

Nowadays, the 'hotstuff-siteadmin' tool will handle this task. Call it
once for a test repository, in the form:

% hotstuff-siteadmin add test

Step 3: install Perl modules
----------------------------

All the needed Perl modules can be installed from CPAN, in case the
distribution doesn't provide them.
Needed are:
* DXS common: MIME::Base64, SOAP::Lite, Data::Dumper
* DXS server: DBI (plus DBD::Pg module)
* DXS client: DateTime, XML::DOM, Getopt::Long, Term::Shell, LWP::Simple
* DXS client, optionally: Crypt::SSLeay, Term::Readline
* GHNS scripts: a few of those of DXS, plus: XML::Writer, CGI

* extra since 0.9.2: Date::Parse, DateTime

% cpan
...
% export PERL5LIB=~/perl/lib/perl5/site_perl/5.8.6
% perl -MCPAN -e "install XML::DOM"
% perl -MCPAN -e "install DBD::Pg"
% perl ...

Step 4: configure Apache
------------------------

Apache, or equivalent web servers, should provide Hotstuff as a virtual
host. However, this is not strictly necessary. There will be five different
areas where web access to Hotstuff is needed or wanted:
- the CGI scripts, which means hotstuff-dxs for DXS access and hotstuff-stuff
  for providing the GHNS feeds
- the admin interface (which ships with Hotstuff)
- the user interface, called Cocodrilo, which can be installed anywhere since
  it will interface with Hotstuff via HTTP
- a WebDAV folder for uploads, when no FTP is used
- the download area for the data and preview files and the provider file

An example for an alternative web server would be:

% thttpd -p 8080 -l ...../LOG -c "/cgi-bin/*"

The web pages are stored in /usr/local/share/hotstuff-admin by default.
See below for notes on the admin interface.

Step 5: configure Hotstuff
--------------------------

The Hotstuff configuration template file must be copied to /etc
and edited to fit the system configuration.

% cp hotstuff/src/hotstuff.conf-dist /etc/hotstuff.d/foo.conf
% vim /etc/hotstuff.d/foo.conf
...

When hotstuff-siteadmin is used, the most important values are already
filled out.

Step 6: import of test data
---------------------------

A Hotstuff database is useless without actual data. The hotstuff-scan tool
usually looks for uploads and imports them into a database. It can however
also process download feeds from other GHNS providers and fetch the referenced
files for import. This is usually the easiest way to get some initial data.

% wget http://download.kde.org/khotnewstuff/wallpaper/wallpaper.xml
% hotstuff-scan -s wallpaper.xml -f

Depending on the configuration, the second step may need to be performed as
root.

Step 7: Versioning
------------------

If the test data worked sufficiently, e.g. by pointing a GHNS implementation
such as KNewStuff to it or by using the Cocodrilo web frontend, some advanced
topics can be tackled. The first of them is versioning. Versioning is enabled
in this step, afterwards the procedure of step 6 (the import of test data)
should be repeated. The download directory as specified in hotstuff.conf will
be used as the checkout directory.

There are two ways of using hotstuff-versioning: As a transparent backend for
conventional uploads (such as FTP, HTTP or WebDAV), and as a gateway to the
Hotstuff database for when all data is already maintained in a version control
system such as SVN.

The first way works as follows:

% hotstuff-versioning --setup /repository

% (cd directory && svn status)
% hotstuff-versioning -c hotstuff.conf

What hotstuff-versioning does is that it looks for newly added files for the
repository and adds versioning meta data to them. Files are placed into the
checkout directory (equal to download directory) by hotstuff-scan which finds
the files in the upload directory.

The second way works as follows:

No local repository is assumed, since the second way should work transparently
with remote repositories. Similarly to the first way, the download directory
equals the checkout directory. However, hotstuff-versioning doesn't look for
locally added files to the checkout directory which are placed there by
hotstuff-scan. Instead, it runs "svn update" or an equivalent command, and for
each changed meta file invokes hotstuff-scan on its own, with the option to
not remove any meta files and not move any preview or payload files.

A cron job running every 10 minutes or so would execute the following command
for each Hotstuff site:

% hotstuff-versioning -c hotstuff.conf --repo

One must ensure that the repository URL leads to an anonymous checkout. Also,
the upload URL must be equal to the download URL so that hotstuff-scan can find
the checked-out files. Finally, the actual repository URL must be given in the
configuration file.

Step 8: Desktop eXchange Service (DXS)
--------------------------------------

Running 'dxsclient' should be sufficient to test the DXS capabilities on the
command line. The web service URL can be given as a parameter, and should
point to the location of the hotstuff-dxs script.

Step 9: Administration frontend
-------------------------------

The hotstuff-admin frontend is currently not well developed. In order to make
use of it, copy htconf-dist to .htconf and fill out its values for one
particular repository. (Only one can be administered at a time right now.)

Step 10: Test
-------------

Under KDE 3, run 'khotnewstuff <providerurl>'.

Under KDE 4, run 'khotnewstuff4 <file.knsrc>. This file must at least contain the
following information:
        [KNewStuff2]
        ProvidersUrl=<providerurl>
and must be placed in KDE's configuration directory, e.g. $KDEHOME/share/config.