About
=====
cape is an asynchronous multi component framework with distributed computing
capabilities. A lot of aspects of message oriented middleware systems are
integrated, too, since one of the goals is driving a fully fledged, planetwide
Delay Tolerant Network (DTN).

It's current primary development focus points are:

* operate our fleet of naval development and testing ships (e.g. the MS0x00)

* aggregate, process and (re-)distribute navigational data from many
  different sources to many different targets

* form and manage a meshed DTN

Usage is pretty unlimited, as long as you can do it reasonably in Python.

Warning
=======
This README, as cape itself, is young and thus heavy WiP!

Installation
============
The installation is being overhauled to an automated process via Python's
setuptools. The long instructions here will still be valid, especially for
Debian systems.

If you're not on any strange/colourful/alien platform, try the
Quick Setup.

Quick Setup
-----------
This is a quicksetup optimized for Debian.

Dependencies
''''''''''''
What you'll need (bare minimum):

 * mercurial
 * python setuptools
 * python headers
 * gcc
 * mongodb

As root, use::

    apt-get install mercurial gcc python-dev python-setuptools mongodb

to install cape's dependencies.

cape
''''
This quick setup cannot install all extras and addons, but the core cape
system. Missing things are: Mapnik2 and Mongo connectors.

**Warning**: You should use a *virtual environment* to install cape. See next
chapter! If you don't want to use a virtual enviroment, you will need to
execute the next commands as root (e.g. with *sudo*).

Clone manually (cape is not yet published on pypi) and install via setup.py::

    hg clone https://repos.hackerfleet.org/cape/cape
    cd cape
    python setup.py install

All required dependencies should be installed automatically via PyPi, Python's
official package repository.

There are some other packages in preparation, see
https://repos.hackerfleet.org/cape for more information.  You will probably
want to install cape.tkadmin, if you want to develop cape components::

    sudo apt-get install python-tk
    hg clone https://repos.hackerfleet.org/cape/cape.tkadmin
    cd cape.tkadmin
    python setup.py install

Et, voila!

Virtual Environment
-------------------
E.g. Debian has a lot of prepackaged python libraries. Please do not use them.
Instead, setup a virtual environment and install into this via pip if possible.
This also enhances security and makes development a lot easier.

Before downloading and installing cape, make sure you have python-virtualenv
and set up an environment::

    virtualenv venv
    cd venv
    source bin/activate

Some features/components rely on external non-python software and thus need the 
appropriate packages installed.


MongoDB on armhf
----------------
If you're installing dependencies on debian's armhf port, you'll notice mongodb
missing. This is because the non-x86 port of mongodb isn't yet debian-packaged.

So you will need to install and build mongodb from hand here.
This document describes the procedure quite well:

https://github.com/mongodb/mongo/blob/master/docs/building.debian.etch.ec2.md

Mind you, there is no need to use gcc4.1 in sid or wheezy, so skip
that part.

Configuration
-------------
cape needs a configuration to do anything. Automatic generation of the necessary
data is in preparation.
Until then, copy::

    cape/doc/cape.conf.example

to::

    /etc/cape/cape.conf

and modify if necessary.

Running & Tests
---------------
Now you should be ready to start the system with::

    cape.py

cape logs (by default) to /tmp/cape.log if not specified otherwise.
You should inspect this file if you encounter problems.

Tests haven't been written, yet. This is going to be funny work. Very.

AddOns
------
There are some init-scripts and helper utilities. You can find these in
cape/Tools. Their integration into your system will be implemented as command
for the automated installation procedure, soon. In the meantime read the files
for more documentation.

Documentation
=============
After installation, try::

    pydoc cape

Contributors
============

* riot <riot@hackerfleet.org>
* Martin Ling <martin@earth.li>

Should you be missing inappropriately, send a mail to riot@hackerfleet.org

Committing
==========
If you'd like to commit patches to the official repository, contact
riot@hackerfleet.org

Contact/Support
===============
This software comes without warranty and express support (See License).
Support is based on community best-effort.

cape's project page is here:
https://hackerfleet.org/dev/wiki/cape

You can browse the source code comfortably here:
https://hackerfleet.org/dev/browser/cape

Tickets can be found here:
https://hackerfleet.org/dev/query?component=cape

Here are the official contact urls:

irc://freenode.org/#hackerfleet
https://hackerfleet.org/support

License
=======
Component Architecture for Python Environments (cape)
Copyright (C) 2011-2013 riot <riot@hackerfleet.org> and others.

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.